KMoreTools

#include <kmoretools.h>

Public Types

enum  ConfigureDialogAccessibleSetting { ConfigureDialogAccessible_Always, ConfigureDialogAccessible_Defensive }
 
enum  MenuSection { MenuSection_Main, MenuSection_More }
 
enum  ServiceLocatingMode { ServiceLocatingMode_Default, ServiceLocatingMode_ByProvidedExecLine }
 

Public Member Functions

 KMoreTools (const QString &uniqueId)
 
 KMoreTools (const KMoreTools &)=delete
 
KMoreToolsMenuBuildermenuBuilder (const QString &userConfigPostfix=QString()) const
 
KMoreToolsoperator= (const KMoreTools &)=delete
 
KMoreToolsServiceregisterServiceByDesktopEntryName (const QString &desktopEntryName, const QString &kmtDesktopfileSubdir=QString(), ServiceLocatingMode serviceLocatingMode=ServiceLocatingMode_Default)
 

Detailed Description

Helps to create user-configurable menus with tools which are potentially not yet installed.

This class is one entry point of the KMoreTools API. See also KMoreToolsMenuFactory.

Note
This is a new API (published within KNewStuff since April 2015). Its current target are KDE applications which are part of the kdesrcbuild infrastructure. Here, it is possible to find all usages and to adapt to API changes when needed. So, if you use this in your own application, beware that there might be API changes when more use cases are developed.

Introduction

KMoreTools helps to to build user-configurable menus with tools which might not installed yet. These tools may also take URL arguments supplied by the application.

The user will see a menu item for a tool even if it is not installed (in the 'More' section). Furthermore, it makes long menus shorter by providing a main and more section. It provides a 'Configure menu' dialog to make the menu user-configurable.

It does this in the following ways:

  • Provide an API to define external applications for a given context.
  • If a defined application is not installed (yet) the application is (optionally) still presented to the user with a hint that it is not installed and a link to the homepage (later with integration to package management). This increases the discoverability of useful applications the user never heard about yet.
  • In case of many applications for a given context, it provides a GUI to the user to hand-pick favorite tools. This makes it easier for application developers to add alternative application/tool suggestions without worrying about cluttered menus.
  • Menu items can be (automatically) moved to the "More" submenu.
  • Reduce translation effort by re-using .desktop files of the services added to the menu.

Details

The term "kmt-desktopfile" refers to a 1:1 copy of a .desktop file. The kmt-desktopfile is provided by the application that uses KMoreTools and must be installed to subdirectories of /usr/share/kf5/kmoretools/

  • e.g. /usr/share/kf5/kmoretools/dolphin/statusbar-diskspace-menu/
  • e.g. /usr/share/kf5/kmoretools/kate/addons/project/git-tools/
  • generally, 'QStandardPaths::GenericDataLocation'/kf5/kmoretools/'uniqueId'

See KMoreTools::KMoreTools for hints of how to install this correctly using cmake.

The kmt-desktopfiles are used to get ready-made translations for application name and description even if the application is not installed. You can also provide an icon which is used in the not-installed section when the application is not installed yet.

For details about the resulting menu structure, see KMoreToolsMenuBuilder.

See also https://community.kde.org/Scratchpad/KMoreToolsFramework (outdated)

Rationale for the "Not installed" section

  • Increase discoverability and visibility of useful free software that have inherently low budget for marketing.
  • Make interconnection of different free software packages as effortless as possible (in terms of creating and maintaining the menu).
  • Provide expert (i.e. your) knowledge to useful free software alternatives to solve a certain task.
  • Give novice users hints about tools that are useful in a particular context even if they are not installed.
  • Improve self-documentation of applications.

Presets

Before installing desktop files in your application you might take a look at KMoreToolsPresets or KMoreToolsMenuFactory which might already contain the needed tools.

Screenshots

This section shows screenshots of usage examples.

KSnapshot's Send To... menu

Last updated: 2015-04-17, uncommitted demo, source code: src/kde/kdegraphics/ksnapshot/ksnapshotsendtoactions.cpp

Note, that the last item in the 'More' menu in the following screenshot was added by KSnapshot's code.

kmoretools-ksnapshot-sendto-1.png
Send To menu

Dolphins's Space info menu

Last updated: 2015-04-17, uncommitted demo, source code: src/kde/applications/dolphin/src/statusbar/spaceinfotoolsmenu.cpp

kmoretools-dolphin-spaceinfo-1.png
Space info menu

Kate's Project plugin git menu

Last updated: 2015-03-25, uncommitted demo, source code: src/kde/applications/kate/addons/project/kateprojecttreeviewcontextmenu.cpp

kmoretools-kate-project-1-all-installed.png
All git tools installed
kmoretools-kate-project-2-two-not-installed.png
Not all git tools installed
kmoretools-kate-project-3-config-dialog-all-installed.png
'Configure menu' dialog

Kate's Project plugin git menu

Last updated: 2015-04-17, source code: src/frameworks/knewstuff/tests/kmoretools/kmoretoolstest.cpp

kmoretools-tests-configure-dialog-notinstalledapps.png
Configure dialog when there are non-installed apps

FAQ

Why is everything based on desktopfiles?

  • With desktopfiles translation can be reused.
  • Definition of application icon can be reused.
  • They provide a unified interface for dealing with program arguments.

todo later

Since
5.10

Definition at line 161 of file kmoretools.h.

Member Enumeration Documentation

Specify if the Configure dialog be accessible from the menu (via a "Configure..." menu item)

Enumerator
ConfigureDialogAccessible_Always 

Always show the "Configure..." menu item (default)

ConfigureDialogAccessible_Defensive 

Defensively show the "Configure..." menu item.

The "Configure..." menu item will only be shown if there are non-installed apps. Rationale (suggestion): Do not clutter menu more than needed in standard cases. But when there are not-installed apps the configure dialog can be used to find out more about these apps.

Note, that the "Configure..." menu item still becomes visible when the user holds the Ctrl key while opening the menu.

Definition at line 221 of file kmoretools.h.

Specify where a menu item be placed by default.

Enumerator
MenuSection_Main 

The item is placed in the main section (default)

MenuSection_More 

The item is placed in the "More" submenu.

Definition at line 187 of file kmoretools.h.

Specify how should be determined if a service is installed or not.

Enumerator
ServiceLocatingMode_Default 

by existence of desktop file (discoverable by KService)

ServiceLocatingMode_ByProvidedExecLine 

by existence of executable defined in the TryExec or Exec line of the provided kmt-desktopfile

Definition at line 170 of file kmoretools.h.

Constructor & Destructor Documentation

KMoreTools::KMoreTools ( const QString uniqueId)
explicit
Parameters
uniqueIddefines two things 1) the config section name where the user settings done by the Configure dialog will be stored. 2) the location where the kmt-desktopfiles should be installed because there they will be searched by default. If uniqueId contains slashes they will result in subdirectories. The default location can be overridden by registerServiceByDesktopEntryName's kmtDesktopfileSubdir parameter. This is currently used in KMoreToolsPresets implementation to separate the kmt-desktopfiles location from the user's config section name.

Install Desktopfiles

Example 1 (CMakeLists.txt if uniqueId = "dolphin/statusbar-diskspace-menu"):

 # note the trailing slash       ------------. (it makes sure only the contents of the directory is copied)
 #                                           |                                 ----fix---
 #                                           v                                            ------ uniqueId-----------------
 install(DIRECTORY statusbar/kmt-desktopfiles/ DESTINATION ${KDE_INSTALL_DATADIR_KF5}/kmoretools/dolphin/statusbar-diskspace-menu)

Example 2:

                                                                                ------ uniqueId--------------
 install(DIRECTORY kmt-desktopfiles/ DESTINATION ${KDE_INSTALL_DATADIR_KF5}/kmoretools/kate/addons/project/git-tools)

About ${KDE_INSTALL_DATADIR_KF5}

In general, ${KDE_INSTALL_DATADIR_KF5}/kmoretools/hallo ends up in /usr/share/kf5/kmoretools/hallo.

To use it, you need to add

include(KDEInstallDirs) 

to your CMakeLists.txt.

Definition at line 81 of file kmoretools.cpp.

Member Function Documentation

KMoreToolsMenuBuilder * KMoreTools::menuBuilder ( const QString userConfigPostfix = QString()) const
Returns
the interface to build the menu. It is a singleton instance for each different userConfigPostfix (which is "" by default). So repeated calls with same parameter will return the same object.

The pointer lives as long as KMoreTools.

Parameters
userConfigPostfixis empty by default. You can use it to specify a postfix for the user config section. So you can build different menus which can be configured separately. (This is used in unit tests to separated test cases.)
See also
KMoreToolsMenuBuilder::clear()

Definition at line 175 of file kmoretools.cpp.

KMoreToolsService * KMoreTools::registerServiceByDesktopEntryName ( const QString desktopEntryName,
const QString kmtDesktopfileSubdir = QString(),
KMoreTools::ServiceLocatingMode  serviceLocatingMode = ServiceLocatingMode_Default 
)

Registers a service with KMoreTools.

If the method is called more than once for the same desktopEntryName the service is located again and the old service is replaced with the new one.

Parameters
desktopEntryNameis the name of the desktopfile (without the .desktop extension) The desktop file is
  1. either already installed. Then the information of the installed file is used.
  2. or not installed and kmt-desktopfile is present. Then the information of the app-local copy of desktopfile located in the kmt-desktopfiles directory is used
  3. or not installed and no kmt-desktopfile provided. In this case KMoreToolsService::setHomepageUrl should be used so that at least a website link can be displayed.
kmtDesktopfileSubdirwhen not empty overrides the uniqueId parameter from the ctor when it comes to searching a kmt-desktopfile. Default value is the empty string.
serviceLocatingMode== ServiceLocatingMode_ByProvidedExecLine: Some programs don't install a desktop file of their own (e.g. gitk). If set to true then installed desktop files are not searched but the provided in kmt-desktopfiles will be used to extract exec line. The exec line will be used to determine if the executable is installed.
Returns
a KMoreToolsService pointer which lives as long as KMoreTools, so do not store it for later use.
nullptr if the kmt provided desktop file is faulty. This kind of error must be fixed before you ship your application. This case is only used for unit tests.

Definition at line 92 of file kmoretools.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Wed Aug 12 2020 22:42:03 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.