Difference between revisions of "Scratchpad/KMoreToolsFramework"

(→‎Early API draft: notInstalledAppsSuggestionsEnabled)
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
= The "More Tools Suggestion" (MTS) Framework -- Draft =
+
= The "K More Tools" (KMT) Framework -- Draft =
 +
{{Note|First version commited to src/frameworks/knewstuff/src/kmoretools. So the content here can be outdated.}}
  
 
== Abstract ==
 
== Abstract ==
This scratchpad page is the starting point for the draft specification of a framework or module called "More Tools Suggestion" ('''MTS''').
+
This scratchpad page is the starting point for the draft specification of a framework or module called "K Tools Suggestion" (''KMT''').
  
MTS should the support the following purpose:
+
KMT should provide an API to provide a consistent UI for the following purpose:
  
1a) PRIMARY GOAL: '''Give novice users hints about tools that are useful in a particular context even if the are not installed'''.
+
1) GOAL: '''Quick access to related tools in a given context.'''
  
1b) CONDITION: The tool suggestions - especially for not-installed tools - should be '''non-obstrusive'''. The advanced user should have a global option to '''turn off''' the suggestions.
+
2) GOAL: '''Give novice users hints about tools that are useful in a particular context even if the are not installed'''.
  
2) NICE-TO-HAVE: When the user chooses a not-installed tool, the distro specific package manager should be used to start the installation process for the chosen software.
+
3) GOAL: Make it easier for application developers to add alternative application/tool suggestions without worrying about cluttered menus.
 +
 
 +
4) CONDITION: The tool suggestions - especially for not-installed tools - should be '''non-obstrusive'''.
 +
 
 +
5) NICE-TO-HAVE: When the user chooses a not-installed tool, the distro specific package manager should be used to start the installation process for the chosen software.
  
 
== Use cases / References==
 
== Use cases / References==
  
* ksnapshot's SendTo menu: ... TODO ...
+
See KMoreTools API documentation: ...TODO... link
* Dolphin's status bar disk space menu: "dolphin: add menu to SpaceInfo widget for detailled disk usage information": https://git.reviewboard.kde.org/r/121478/
+
 
 +
=== ksnapshot's SendTo menu ===
 +
... TODO ...
 +
 
 +
=== Dolphin's status bar disk space menu ===
 +
[https://git.reviewboard.kde.org/r/121478/ RR: dolphin: add menu to SpaceInfo widget for detailled disk usage information]
  
== Technical details ==
+
Screenshots of '''current implementation (without KMT)''':
 +
 
 +
KDiskFree and Filelight both installed:
 +
 
 +
[[File:Diskusage-utils-1.png]]
 +
 
 +
Filelight not installed:
 +
 
 +
[[File:Diskusage-utils-2.png]]
 +
 
 +
This could be improved doing it '''with KMT''':
 +
 
 +
'''CURRENT:''' (without KMT)
 +
Menu
 +
  `- Filelight [not installed]
 +
  `- View Disk Usage
  
=== Early API draft ===
+
'''NEW:''' (with KMT support)
 +
Menu
 +
  `- View Disk Usage
 +
  `- More >
 +
        `- Not installed >
 +
              `- Disk Usage Statstics with Filelight
 +
              `- <GenericName> with <Name>
 +
              `- Configure this menu...
  
'''void MTS::registerApplication(QString globally_unique_context_id, QUrl service_desktop_file);'''
+
* All applications which are not installed are placed in a submenu called '''Not installed''' which is placed in the '''More''' submenu.
 +
* [LATER] If such a menu item is clicked the systems package manager opens and '''asks the user to install''' the package. As an intermediate step one could launch a simple Internet search.
 +
* The '''More''' submenu can also contain less often used items (user-configurable in a later version of KMT)
 +
* '''Configure this menu...''': Opens a dialog that gives the option not to show not installed applications.
 +
.----------------------------------------------------------------.
 +
| Configure More Tools Suggestions                              |
 +
-----------------------------------------------------------------|
 +
| Global settings                                                |
 +
|                                                                |
 +
| [x] Show menu entries of tools that are not installed          |
 +
| If you do like to see suggestions of applications that are not |
 +
| installed enable this option                                  |
 +
|                                                                |
 +
|                                        [Ok] [Apply] [Cancel]  |
 +
`----------------------------------------------------------------`
 +
* '''Configure this menu...''' [LATER]: In a later version of KMT it could be made user-configurable which menu items should be shown in the ''More'' menu instead of in the first level.
  
// register KDiskFree
+
== Technical details ==
// "dolphin_resources/kdf.desktop" is a dolphin-local copy of /usr/share/applications/kde4/kdf.desktop
 
// TODO: where to actually place it? It must not be found by the standard KService.
 
MTS::registerApplication("dolphin-statusbar-diskspace-menu", "dolphin_resources/kdf.desktop");
 
  
// register Filelight
+
=== Components ===
// "dolphin_resources/org.kde.filelight.desktop" is a dolphin-local copy of Filelight's desktop file
 
MTS::registerApplication("dolphin-statusbar-diskspace-menu", "dolphin_resources/org.kde.filelight.desktop");
 
  
'''bool MTS::notInstalledAppsSuggestionsEnabled(QString globally_unique_context_id);'''
+
* Library to be used by application developer (see API draft)
 +
* Some configuration GUI to enable or disabled suggestions (e.g. for not-installed tools)
  
Example:
+
=== User settings ===
 +
* User settings are saved _per id_ (todo: clarify what that means) in the application settings (KConfig). Similar to the "Recent files" entries.
  
if (MTS::notInstalledAppsSuggestionsEnabled("dolphin-statusbar-diskspace-menu")) {
+
=== Early API draft ===
    // Fill the "not installed suggestions" menu with the registered apps. Use information retrieved by the desktop files.
 
} else {
 
    // User had previously turned off the suggestions for not-installed apps.
 
    // Do not add suggestions.
 
    // User must go to global settings if he/she wants to turn suggestions on again.
 
}
 
  
 
=== Why .desktop files for not-installed applications/services? ===
 
=== Why .desktop files for not-installed applications/services? ===
 +
 +
* From a given application name it is often hard to guess what purpose it has. The .desktop file contains a more understandable description of an application.
  
 
... [draft] / comments? ...
 
... [draft] / comments? ...
Line 54: Line 94:
 
'''Q:''' Maintaining the copy of the .desktop file?
 
'''Q:''' Maintaining the copy of the .desktop file?
  
'''A:''' In regular intervals the upstream .desktop file of the referenced package should be updated. But in general there is no tight coupling, so the application that uses MTS is ''not'' forced to do it on every minor change.
+
'''A:''' In regular intervals the upstream .desktop file of the referenced package should be updated. But in general there is no tight coupling, so the application that uses KMT is ''not'' forced to do it on every minor change.
 +
 
 +
== API usage by example ==
 +
 
 +
=== Dolphin's SpaceInfo menu ===
 +
 
 +
{{Input|<syntaxhighlight lang="cpp" line>
 +
KMoreTools kmt("dolphin-statusbar-diskspace-menu");
 +
 +
auto kdiskfreeApp = kmt.addService("dolphin_resources/kdf.desktop"); // returns a KMoreToolsRegisteredService*
 +
auto filelightApp = kmt.addService("dolphin_resources/org.kde.filelight.desktop");
 +
auto gpartedApp = kmt.addService("dolphin_resources/gparted.desktop");
 +
 +
//
 +
// add simple application with no parameters
 +
//
 +
auto ktmMenuBuilder = kmt.getMenuBuilder(); // returns a KMoreToolsMenuBuilder*
 +
auto kdiskfreeAction = ktmMenuBuilder.addAction(kdiskfreeApp); KMoreToolsAction*
 +
// INTERNALS:
 +
//  when kdiskfreeApp->isAvailable() == true
 +
//    the resulting action's name is kdiskfreeService->genericName()
 +
//    the icon is QIcon::fromTheme(kdiskfreeService->icon())
 +
//  if false: the icon is not set because it is probably not available
 +
if (kdiskfreeApp->isAvailable()) {
 +
        auto kdiskfreeService = kdiskfreeApp->getService(); // is not nullptr because isAvailable() was true
 +
        // kdiskfreeAction->action() returns the action QAction*
 +
        connect(kdiskfreeAction->action(), &QAction::triggered, this, [kdiskfreeService](bool) {
 +
            KRun::runService(*kdiskfreeService, { }, nullptr);
 +
        }); 
 +
} // INTERNALS: else the menu entry will be displayed in the "More >" submenu
 +
 +
//
 +
// filelight, 3 menu entries from one application but with different parameters
 +
//
 +
auto filelightDirectoryAction = ktmMenuBuilder.addAction(filelightApp)
 +
    ->appendText(" - " + i18nc("@action:inmenu", "current folder")); // also returns KMoreToolsAction*
 +
auto filelightDeviceAction = ktmMenuBuilder.addAction(filelightApp);
 +
    ->appendText(" - " + i18nc("@action:inmenu", "current device"));
 +
auto filelightAllDevicesAction = ktmMenuBuilder.addAction(filelightApp);
 +
    ->appendText(" - " + i18nc("@action:inmenu", "all devices"));
 +
if (filelightApp->isAvailable()) {
 +
    // TODO .................
 +
}
 +
 +
//
 +
// add simple application with no parameters, but in the "More >" submenu by default
 +
//
 +
auto gpartedAction = ktmMenuBuilder.addAction(gpartedApp, KMoreTools::DefaultLocation_MoreSubmenu);
 +
gpartedAction->connectDefaultRunServiceIfAvailable();
 +
// INTERNALS: does the same as with kdiskfreeAction but as convenience method
 +
 +
// (TODO: example where no desktop file is provided, here or elsewhere)
 +
 +
//
 +
// build menu
 +
//
 +
// auto menu = ktmMenuBuilder->buildMenu(); // returns a QMenu*, or better:
 +
QMenu menu;
 +
ktmMenuBuilder->addToMenu(&menu); // adds the menu entries to the given menu
 +
 
 +
</syntaxhighlight>}}
  
 
== Later: package mgmt integration ==
 
== Later: package mgmt integration ==
Line 60: Line 160:
 
* "KDiskFree not installed. If you would like to install it, click here to install it."
 
* "KDiskFree not installed. If you would like to install it, click here to install it."
 
* Similar to /usr/bin/cnf but for .desktop files of programs that are not yet installed: start the distro GUI package mgmt for the specific package.
 
* Similar to /usr/bin/cnf but for .desktop files of programs that are not yet installed: start the distro GUI package mgmt for the specific package.
 
+
* Open with Muon discover
TODO: is there already related work in this direction?
 
* ...
 
* ...
 

Latest revision as of 22:55, 16 April 2015

The "K More Tools" (KMT) Framework -- Draft

Note
First version commited to src/frameworks/knewstuff/src/kmoretools. So the content here can be outdated.


Abstract

This scratchpad page is the starting point for the draft specification of a framework or module called "K Tools Suggestion" (KMT').

KMT should provide an API to provide a consistent UI for the following purpose:

1) GOAL: Quick access to related tools in a given context.

2) GOAL: Give novice users hints about tools that are useful in a particular context even if the are not installed.

3) GOAL: Make it easier for application developers to add alternative application/tool suggestions without worrying about cluttered menus.

4) CONDITION: The tool suggestions - especially for not-installed tools - should be non-obstrusive.

5) NICE-TO-HAVE: When the user chooses a not-installed tool, the distro specific package manager should be used to start the installation process for the chosen software.

Use cases / References

See KMoreTools API documentation: ...TODO... link

ksnapshot's SendTo menu

... TODO ...

Dolphin's status bar disk space menu

RR: dolphin: add menu to SpaceInfo widget for detailled disk usage information

Screenshots of current implementation (without KMT):

KDiskFree and Filelight both installed:

Diskusage-utils-1.png

Filelight not installed:

Diskusage-utils-2.png

This could be improved doing it with KMT:

CURRENT: (without KMT)

Menu
 `- Filelight [not installed]
 `- View Disk Usage

NEW: (with KMT support)

Menu
 `- View Disk Usage
 `- More >
        `- Not installed >
             `- Disk Usage Statstics with Filelight
             `- <GenericName> with <Name>
             `- Configure this menu...
  • All applications which are not installed are placed in a submenu called Not installed which is placed in the More submenu.
  • [LATER] If such a menu item is clicked the systems package manager opens and asks the user to install the package. As an intermediate step one could launch a simple Internet search.
  • The More submenu can also contain less often used items (user-configurable in a later version of KMT)
  • Configure this menu...: Opens a dialog that gives the option not to show not installed applications.
.----------------------------------------------------------------.
| Configure More Tools Suggestions                               |
-----------------------------------------------------------------|
| Global settings                                                |
|                                                                |
| [x] Show menu entries of tools that are not installed          |
| If you do like to see suggestions of applications that are not |
| installed enable this option                                   |
|                                                                |
|                                        [Ok] [Apply] [Cancel]   |
`----------------------------------------------------------------`
  • Configure this menu... [LATER]: In a later version of KMT it could be made user-configurable which menu items should be shown in the More menu instead of in the first level.

Technical details

Components

  • Library to be used by application developer (see API draft)
  • Some configuration GUI to enable or disabled suggestions (e.g. for not-installed tools)

User settings

  • User settings are saved _per id_ (todo: clarify what that means) in the application settings (KConfig). Similar to the "Recent files" entries.

Early API draft

Why .desktop files for not-installed applications/services?

  • From a given application name it is often hard to guess what purpose it has. The .desktop file contains a more understandable description of an application.

... [draft] / comments? ...

Q: Why add the .desktop file of each tool that should be in the suggestion list to the application that makes the suggestion?

A: The .desktop file contains the translated application name and generic name (short tool description) that can be displayed to the user even if the package is not installed yet.

Q: Maintaining the copy of the .desktop file?

A: In regular intervals the upstream .desktop file of the referenced package should be updated. But in general there is no tight coupling, so the application that uses KMT is not forced to do it on every minor change.

API usage by example

Dolphin's SpaceInfo menu

 1  KMoreTools kmt("dolphin-statusbar-diskspace-menu");
 2  
 3  auto kdiskfreeApp = kmt.addService("dolphin_resources/kdf.desktop"); // returns a KMoreToolsRegisteredService*
 4  auto filelightApp = kmt.addService("dolphin_resources/org.kde.filelight.desktop");
 5  auto gpartedApp = kmt.addService("dolphin_resources/gparted.desktop");
 6  
 7  //
 8  // add simple application with no parameters
 9  //
10  auto ktmMenuBuilder = kmt.getMenuBuilder(); // returns a KMoreToolsMenuBuilder*
11  auto kdiskfreeAction = ktmMenuBuilder.addAction(kdiskfreeApp); KMoreToolsAction*
12  // INTERNALS:
13  //   when kdiskfreeApp->isAvailable() == true
14  //     the resulting action's name is kdiskfreeService->genericName()
15  //     the icon is QIcon::fromTheme(kdiskfreeService->icon())
16  //   if false: the icon is not set because it is probably not available
17  if (kdiskfreeApp->isAvailable()) {
18         auto kdiskfreeService = kdiskfreeApp->getService(); // is not nullptr because isAvailable() was true
19         // kdiskfreeAction->action() returns the action QAction*
20         connect(kdiskfreeAction->action(), &QAction::triggered, this, [kdiskfreeService](bool) {
21             KRun::runService(*kdiskfreeService, { }, nullptr);
22         });  
23  } // INTERNALS: else the menu entry will be displayed in the "More >" submenu
24  
25  //
26  // filelight, 3 menu entries from one application but with different parameters
27  //
28  auto filelightDirectoryAction = ktmMenuBuilder.addAction(filelightApp)
29     ->appendText(" - " + i18nc("@action:inmenu", "current folder")); // also returns KMoreToolsAction*
30  auto filelightDeviceAction = ktmMenuBuilder.addAction(filelightApp);
31     ->appendText(" - " + i18nc("@action:inmenu", "current device"));
32  auto filelightAllDevicesAction = ktmMenuBuilder.addAction(filelightApp);
33     ->appendText(" - " + i18nc("@action:inmenu", "all devices"));
34  if (filelightApp->isAvailable()) {
35     // TODO .................
36  }
37  
38  //
39  // add simple application with no parameters, but in the "More >" submenu by default
40  //
41  auto gpartedAction = ktmMenuBuilder.addAction(gpartedApp, KMoreTools::DefaultLocation_MoreSubmenu);
42  gpartedAction->connectDefaultRunServiceIfAvailable();
43  // INTERNALS: does the same as with kdiskfreeAction but as convenience method
44  
45  // (TODO: example where no desktop file is provided, here or elsewhere)
46  
47  //
48  // build menu
49  // 
50  // auto menu = ktmMenuBuilder->buildMenu(); // returns a QMenu*, or better:
51  QMenu menu;
52  ktmMenuBuilder->addToMenu(&menu); // adds the menu entries to the given menu

Later: package mgmt integration

Use case:

  • "KDiskFree not installed. If you would like to install it, click here to install it."
  • Similar to /usr/bin/cnf but for .desktop files of programs that are not yet installed: start the distro GUI package mgmt for the specific package.
  • Open with Muon discover

This page was last edited on 16 April 2015, at 22:55. Content is available under Creative Commons License SA 4.0 unless otherwise noted.
-->