KMoreTools Class Reference

#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)
KMoreToolsMenuBuilder *	menuBuilder (const QString &userConfigPostfix=QString()) const
KMoreTools &	operator= (const KMoreTools &)=delete
KMoreToolsService *	registerServiceByDesktopEntryName (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 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.

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

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

• question: KMoreTools::registerServiceByDesktopEntryName():
  • warn if service is not of Type=Application (KService::isApplication()) or just leave it? Add support for package managers to install software (e.g. muon discover)
• maybe: kmt-desktopfiles: add a config file that can configure the homepage URLs and e.g. the package name if needed for package manager support

Definition at line 162 of file kmoretools.h.

Member Enumeration Documentation

ConfigureDialogAccessibleSetting

enum KMoreTools::ConfigureDialogAccessibleSetting

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

MenuSection

enum KMoreTools::MenuSection

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.

ServiceLocatingMode

enum KMoreTools::ServiceLocatingMode

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

Constructor & Destructor Documentation

KMoreTools()

KMoreTools::KMoreTools ( const QString & uniqueId )

explicit

Parameters

uniqueId

defines 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 79 of file kmoretools.cpp.

Member Function Documentation

menuBuilder()

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

userConfigPostfix

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

Parameters

desktopEntryName	is the name of the desktopfile (without the .desktop extension) The desktop file is either already installed. Then the information of the installed file is used. 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 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.
kmtDesktopfileSubdir	when 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 86 of file kmoretools.cpp.

---

The documentation for this class was generated from the following files:

• kmoretools.h
• kmoretools.cpp