Search for usage in LXR

#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 KMoreTools &)=delete
 KMoreTools (const QString &uniqueId)
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.

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.


KMoreTools helps 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.


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 (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.


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


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.

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

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

All git tools installed
Not all git tools installed
'Configure menu' dialog

Kate's Project plugin git menu

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

Configure dialog when there are non-installed apps


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

Definition at line 162 of file kmoretools.h.

Member Enumeration Documentation

◆ ConfigureDialogAccessibleSetting

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


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


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 220 of file kmoretools.h.

◆ MenuSection

Specify where a menu item be placed by default.


The item is placed in the main section (default)


The item is placed in the "More" submenu.

Definition at line 187 of file kmoretools.h.

◆ ServiceLocatingMode

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


by existence of desktop file (discoverable by KService)


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

Definition at line 171 of file kmoretools.h.

Constructor & Destructor Documentation

◆ KMoreTools()

KMoreTools::KMoreTools ( const QString uniqueId)
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)


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

To use it, you need to add


to your CMakeLists.txt.

Definition at line 79 of file kmoretools.cpp.

Member Function Documentation

◆ menuBuilder()

KMoreToolsMenuBuilder * KMoreTools::menuBuilder ( const QString userConfigPostfix = QString()) const
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.

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

Definition at line 151 of file kmoretools.cpp.

◆ registerServiceByDesktopEntryName()

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.

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.
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 86 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-2023 The KDE developers.
Generated on Tue Dec 5 2023 04:05:28 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.