KNewStuff

kmoretools.h
1 /*
2  SPDX-FileCopyrightText: 2015 Gregor Mi <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-or-later
5 */
6 
7 #ifndef KMORETOOLS_H
8 #define KMORETOOLS_H
9 
10 #include <QMenu>
11 #include <QString>
12 #include <QUrl>
13 
14 #include <KService>
15 
16 #include "knewstuff_export.h"
17 
18 class KMoreToolsService;
20 class KMoreToolsPrivate;
21 
22 /**
23  * Helps to create user-configurable menus with tools which are potentially not yet installed.
24  *
25  * This class is one entry point of the KMoreTools API.
26  * See also KMoreToolsMenuFactory.
27  *
28  * @note This is a new API (published within KNewStuff since April 2015). Its current
29  * target are KDE applications which are part of the kdesrcbuild infrastructure.
30  * Here, it is possible to find all usages and to adapt to API changes when needed.
31  * So, if you use this in your own application, beware that there might be API
32  * changes when more use cases are developed.
33  *
34  *
35  * Introduction
36  * ------------
37  * KMoreTools helps to build user-configurable menus with tools which
38  * might not installed yet. These tools may also take URL arguments supplied
39  * by the application.
40  *
41  * The user will see a menu item for a tool even if it is not installed (in the
42  * 'More' section). Furthermore, it makes long menus shorter by providing a
43  * main and more section.
44  * It provides a 'Configure menu' dialog to make the menu user-configurable.
45  *
46  * It does this in the following ways:
47  * - Provide an API to define external applications for a given context.
48  * - If a defined application is not installed (yet) the application is (optionally)
49  * still presented to the user with a hint that it is not installed and a link
50  * to the homepage (later with integration to package management).
51  * This increases the discoverability of useful applications the user never
52  * heard about yet.
53  * - In case of many applications for a given context, it provides a GUI to the
54  * user to hand-pick favorite tools.
55  * This makes it easier for application developers to add alternative
56  * application/tool suggestions without worrying about cluttered menus.
57  * - Menu items can be (automatically) moved to the "More" submenu.
58  * - Reduce translation effort by re-using .desktop files of the services added
59  * to the menu.
60  *
61  *
62  * Details
63  * -------
64  * The term "kmt-desktopfile" refers to a 1:1 copy of a .desktop file. The
65  * kmt-desktopfile is provided by the application that uses KMoreTools
66  * and must be installed to subdirectories of /usr/share/kf5/kmoretools/
67  * - e.g. /usr/share/kf5/kmoretools/dolphin/statusbar-diskspace-menu/
68  * - e.g. /usr/share/kf5/kmoretools/kate/addons/project/git-tools/
69  * - generally, 'QStandardPaths::GenericDataLocation'/kf5/kmoretools/'uniqueId'
70  *
71  * See KMoreTools::KMoreTools for hints of how to install this correctly
72  * using cmake.
73  *
74  * The kmt-desktopfiles are used to get ready-made translations for application
75  * name and description even if the application is not installed. You can
76  * also provide an icon which is used in the not-installed section when the
77  * application is not installed yet.
78  *
79  * For details about the resulting menu structure, see KMoreToolsMenuBuilder.
80  *
81  * See also https://community.kde.org/Scratchpad/KMoreToolsFramework (outdated)
82  *
83  *
84  * Rationale for the "Not installed" section
85  * -----------------------------------------
86  * - Increase discoverability and visibility of useful free software that have
87  * inherently low budget for marketing.
88  * - Make interconnection of different free software packages as effortless as
89  * possible (in terms of creating and maintaining the menu).
90  * - Provide expert (i.e. your) knowledge to useful free software alternatives
91  * to solve a certain task.
92  * - Give novice users hints about tools that are useful in a particular
93  * context even if they are not installed.
94  * - Improve self-documentation of applications.
95  *
96  *
97  * Presets
98  * -------
99  * Before installing desktop files in your application you might take a look
100  * at KMoreToolsPresets or KMoreToolsMenuFactory which might already contain
101  * the needed tools.
102  *
103  *
104  * Screenshots
105  * -----------
106  * This section shows screenshots of usage examples.
107  *
108  * ### KSnapshot's Send To... menu
109  *
110  * Last updated: 2015-04-17, uncommitted demo, source code:
111  * src/kde/kdegraphics/ksnapshot/ksnapshotsendtoactions.cpp
112  *
113  * Note, that the last item in the 'More' menu in the following screenshot was
114  * added by KSnapshot's code.
115  *
116  * \image html kmoretools-ksnapshot-sendto-1.png "Send To menu" width=100px
117  *
118  * ### Dolphins's Space info menu
119  *
120  * Last updated: 2015-04-17, uncommitted demo, source code: src/kde/applications/dolphin/src/statusbar/spaceinfotoolsmenu.cpp
121  *
122  * \image html kmoretools-dolphin-spaceinfo-1.png "Space info menu" width=100px
123  *
124  * ### Kate's Project plugin git menu
125  *
126  * Last updated: 2015-03-25, uncommitted demo, source code:
127  * src/kde/applications/kate/addons/project/kateprojecttreeviewcontextmenu.cpp
128  *
129  * \image html kmoretools-kate-project-1-all-installed.png "All git tools installed" width=100px
130  *
131  * \image html kmoretools-kate-project-2-two-not-installed.png "Not all git tools installed" width=100px
132  *
133  * \image html kmoretools-kate-project-3-config-dialog-all-installed.png "'Configure menu' dialog" width=100px
134  *
135  * ### Kate's Project plugin git menu
136  *
137  * Last updated: 2015-04-17, source code: src/frameworks/knewstuff/tests/kmoretools/kmoretoolstest.cpp
138  *
139  * \image html kmoretools-tests-configure-dialog-notinstalledapps.png "Configure dialog when there are non-installed apps" width=100px
140  *
141  *
142  * FAQ
143  * ---
144  * ### Why is everything based on desktopfiles?
145  *
146  * - With desktopfiles translation can be reused.
147  * - Definition of application icon can be reused.
148  * - They provide a unified interface for dealing with program arguments.
149  *
150  *
151  * todo later
152  * ----------
153  * - question: KMoreTools::registerServiceByDesktopEntryName():
154  * - warn if service is not of Type=Application (KService::isApplication()) or just leave it?
155  * Add support for package managers to install software (e.g. muon discover)
156  * - maybe: kmt-desktopfiles: add a config file that can configure the homepage URLs
157  * and e.g. the package name if needed for package manager support
158  *
159  * @since 5.10
160  */
161 class KNEWSTUFF_EXPORT KMoreTools
162 {
163  friend class KMoreToolsService;
164  friend class KMoreToolsServicePrivate;
165 
166 public:
167  /**
168  * Specify how should be determined if a service is installed or not
169  */
171  /**
172  * by existence of desktop file (discoverable by KService)
173  */
175 
176  /**
177  * by existence of executable defined in the TryExec or Exec line of
178  * the provided kmt-desktopfile
179  */
181  };
182 
183  /**
184  * Specify where a menu item be placed by default
185  */
186  enum MenuSection {
187  /**
188  * The item is placed in the main section (default)
189  */
191 
192  /**
193  * The item is placed in the "More" submenu.
194  */
196  };
197 
198  // /* *
199  // * todo/later: introduce when needed
200  // */
201  // enum NotInstalledSectionOption
202  // {
203  // /* *
204  // * default
205  // */
206  // NotInstalledSection_Show,
207  //
208  // /* *
209  // * Even if there are non-installed apps the Not-Installed section will
210  // * not be shown
211  // */
212  // NotInstalledSection_Hide
213  // };
214 
215  /**
216  * Specify if the Configure dialog be accessible from the menu
217  * (via a "Configure..." menu item)
218  */
220  /**
221  * Always show the "Configure..." menu item
222  * (default)
223  */
225 
226  /**
227  * Defensively show the "Configure..." menu item
228  *
229  * The "Configure..." menu item will only be shown if there are non-installed
230  * apps.
231  * Rationale (suggestion): Do not clutter menu more than needed in standard
232  * cases. But when there are not-installed apps the configure dialog can
233  * be used to find out more about these apps.
234  *
235  * Note, that the "Configure..." menu item still becomes visible when the
236  * user holds the Ctrl key while opening the menu.
237  */
239  };
240 
241 public:
242  /**
243  * @param uniqueId defines two things
244  * 1) the config section name where the user settings done by the Configure
245  * dialog will be stored.
246  * 2) the location where the kmt-desktopfiles should be installed because
247  * there they will be searched by default.
248  * If @p uniqueId contains slashes they will result in subdirectories.
249  * The default location can be overridden by
250  * registerServiceByDesktopEntryName's kmtDesktopfileSubdir parameter.
251  * This is currently used in KMoreToolsPresets implementation to
252  * separate the kmt-desktopfiles location from the user's config section
253  * name.
254  *
255  * Install Desktopfiles
256  * --------------------
257  * Example 1 (CMakeLists.txt if uniqueId = "dolphin/statusbar-diskspace-menu"):
258  * \verbatim
259  # note the trailing slash ------------. (it makes sure only the contents of the directory is copied)
260  # | ----fix---
261  # v ------ uniqueId-----------------
262  install(DIRECTORY statusbar/kmt-desktopfiles/ DESTINATION ${KDE_INSTALL_DATADIR_KF5}/kmoretools/dolphin/statusbar-diskspace-menu)
263  \endverbatim
264 
265  Example 2:
266  \verbatim
267  ------ uniqueId--------------
268  install(DIRECTORY kmt-desktopfiles/ DESTINATION ${KDE_INSTALL_DATADIR_KF5}/kmoretools/kate/addons/project/git-tools)
269  \endverbatim
270  *
271  * ### About ${KDE_INSTALL_DATADIR_KF5}
272  *
273  * In general, ${KDE_INSTALL_DATADIR_KF5}/kmoretools/hallo ends up in /usr/share/kf5/kmoretools/hallo.
274  *
275  * To use it, you need to add \verbatim include(KDEInstallDirs) \endverbatim to your CMakeLists.txt.
276  */
277  explicit KMoreTools(const QString &uniqueId);
278 
279  ~KMoreTools();
280 
281  KMoreTools(const KMoreTools &) = delete;
282  KMoreTools &operator=(const KMoreTools &) = delete;
283 
284  /**
285  * Registers a service with KMoreTools.
286  *
287  * If the method is called more than once for the same desktopEntryName
288  * the service is located again and the old service is replaced with the
289  * new one.
290  *
291  * @param desktopEntryName is the name of the desktopfile (without the
292  * .desktop extension)
293  * The desktop file is
294  * 1. either already installed. Then the information of the installed file
295  * is used.
296  * 2. or not installed and kmt-desktopfile is present. Then the information
297  * of the app-local copy of desktopfile located in the kmt-desktopfiles
298  * directory is used
299  * 3. or not installed and no kmt-desktopfile provided. In this case
300  * KMoreToolsService::setHomepageUrl should be used so that at least a
301  * website link can be displayed.
302  *
303  * @param kmtDesktopfileSubdir when not empty overrides the @p uniqueId
304  * parameter from the ctor when it comes to searching a kmt-desktopfile.
305  * Default value is the empty string.
306  *
307  * @param serviceLocatingMode == ServiceLocatingMode_ByProvidedExecLine:
308  * Some programs don't install a desktop file of their own (e.g. gitk).
309  * If set to true then installed desktop files are not searched
310  * but the provided in kmt-desktopfiles will be used to extract exec line.
311  * The exec line will be used to determine if the executable is installed.
312  *
313  * @return a KMoreToolsService pointer which lives as long as KMoreTools, so
314  * do not store it for later use.
315  * @return nullptr if the kmt provided desktop file is faulty.
316  * This kind of error must be fixed before you ship your application.
317  * This case is only used for unit tests.
318  */
319  KMoreToolsService *registerServiceByDesktopEntryName(const QString &desktopEntryName,
320  const QString &kmtDesktopfileSubdir = QString(),
321  ServiceLocatingMode serviceLocatingMode = ServiceLocatingMode_Default);
322 
323  /**
324  * @returns the interface to build the menu. It is a singleton instance
325  * for each different @p userConfigPostfix (which is "" by default).
326  * So repeated calls with same parameter will return the same object.
327  *
328  * The pointer lives as long as KMoreTools.
329  *
330  * @param userConfigPostfix is empty by default. You can use it to specify
331  * a postfix for the user config section. So you can build different menus
332  * which can be configured separately. (This is used in unit tests to
333  * separated test cases.)
334  *
335  * @sa KMoreToolsMenuBuilder::clear()
336  */
337  KMoreToolsMenuBuilder *menuBuilder(const QString &userConfigPostfix = QString()) const;
338 
339 private:
340  KMoreToolsPrivate *d;
341 };
342 
343 // --------------------------------------------------------------------------------------
344 // --------------------------------------------------------------------------------------
345 
346 class KMoreToolsServicePrivate;
347 
348 /**
349  * A service described in a .desktop file (kmt-desktopfile) which will be
350  * called "registered service".
351  *
352  * A registered service can either be installed (isInstalled() == true)
353  * or - if not found on the system - not installed (isInstalled() == false).
354  *
355  * @since 5.10
356  */
357 class KNEWSTUFF_EXPORT KMoreToolsService
358 {
359  friend class KMoreTools;
360  friend class KMoreToolsPrivate;
361 
362 public:
364 
365  KMoreToolsService(const KMoreToolsService &) = delete;
366  KMoreToolsService &operator=(const KMoreToolsService &) = delete;
367 
368  /**
369  * @return the desktop entry name which the service is identified by and with which
370  * it was registered (see registerServiceByDesktopEntryName).
371  *
372  * Filename without .desktop: e.g. if the desktop file is named
373  * "org.kde.ksnapshot.desktop" then the desktop entry name is
374  * "org.kde.ksnapshot".
375  */
376  QString desktopEntryName() const;
377 
378  /**
379  * @returns true if the desktopfile with the given
380  * desktopname (name of the .desktop file without the .desktop)
381  * is installed on the system
382  */
383  bool isInstalled() const;
384 
385  /**
386  * @returns the KService represented by an installed desktop file.
387  *
388  * @note that this might be nullptr even if isInstalled() is true.
389  * This can only happen when ServiceLocatingMode::ServiceLocatingMode_ByProvidedExecLine
390  * is used in registerServiceByDesktopEntryName. (Then the kmt-desktopfile's
391  * Exec line is used to determine if a program is installed)
392  */
393  KService::Ptr installedService() const;
394 
395  /**
396  * @returns a non-null KService::Ptr if app-local kmt-desktopfile is
397  * found and valid
398  */
399  KService::Ptr kmtProvidedService() const;
400 
401  /**
402  * @return the icon provided by the KMoreTools' user and not the installed one.
403  * (e.g. QGit currently has got a blank icon installed)
404  */
405  QIcon kmtProvidedIcon() const;
406 
407  /**
408  * @see setHomepageUrl()
409  */
410  QUrl homepageUrl() const;
411 
412  /**
413  * Sets the homepage url the user is shown when a service is not installed.
414  * This way the user gets some information of how to install the
415  * application.
416  */
417  void setHomepageUrl(const QUrl &url);
418 
419  /**
420  * @see setMaxUrlArgCount()
421  */
422  int maxUrlArgCount() const;
423 
424  /**
425  * In KMoreToolsMenuFactory some minor magic is done. In the context of
426  * connecting the action trigger signal we need to know the maximum number
427  * of URL arguments a given service can accept. Usually a number between
428  * 0 and 1. Sometimes 2.
429  * E.g. kdf must not be called with any positional argument.
430  * E.g. gitg can be called with zero or one arguments.
431  */
432  void setMaxUrlArgCount(int maxUrlArgCount);
433 
434  /**
435  * @param formatString supports the following placeholders:
436  *
437  * 1. $GenericName
438  * 2. $Name
439  * 3. $DesktopEntryName
440  *
441  * which are replaced by the corresponding desktop file entries.
442  *
443  * If a value for a placeholder is not available (or empty)
444  * (e.g. if no desktop file is available (not installed or not provided
445  * via kmt-desktopfiles)) then the next one is used until 3. is reached which
446  * is always available. Example: the formatString is "$GenericName", but
447  * the GenericName field is not available. So $Name is used. If this is
448  * also not available, $DesktopEntryName is used.
449  *
450  * @sa KMoreToolsMenuItem::setInitialItemText
451  * @sa KMoreToolsMenuBuilder::setInitialItemTextTemplate
452  */
453  QString formatString(const QString &formatString) const;
454 
455  /**
456  * 1. Icon from installed desktop file
457  * If 1. is not found not found then...
458  * 2. icon from kmt desktop file (which is then searched in the kmt-desktopfiles
459  * directory, must have extension .svg or .png)
460  * If 2. is not not found then...
461  * 3. no icon
462  */
463  QIcon icon() const;
464 
465  /**
466  * Will override the "Exec=" line of the service. Will only apply if the
467  * service is installed.
468  *
469  * @see KService::setExec(...)
470  */
471  void setExec(const QString &exec);
472 
473  /**
474  * Returns the associated appstream id that was previously set with setAppstreamId().
475  * If no appstream id was set, an empty string is returned.
476  *
477  * @return The service's appstream id.
478  *
479  * @since 5.48
480  */
481  QString appstreamId() const;
482 
483  /**
484  * Sets the appstream id of the service. This is used to create a
485  * appstream url for installing the service via a software store
486  * (e.g. Discover). For instance, the appstream id for filelight is
487  * "org.kde.filelight.desktop".
488  *
489  * @param id the appstream id
490  *
491  * @since 5.48
492  */
493  void setAppstreamId(const QString &);
494 
495 private:
496  /**
497  * @param kmtDesktopfileSubdir where to find kmt-desktopfiles
498  * @param desktopEntryName name of the desktopfile without the .desktop extension
499  * @param isInstalled true if desktop file is installed
500  * @param installedService not nullptr if @p isInstalled is true
501  * @param kmtDesktopfile not null if app-local kmt-desktopfile is found and valid
502  */
503  KMoreToolsService(const QString &kmtDesktopfileSubdir,
504  const QString &desktopEntryName,
505  bool isInstalled,
506  KService::Ptr installedService,
507  KService::Ptr kmtDesktopfile);
508 
509  /**
510  * No copy semantic => private and no implementation
511  */
512  KMoreToolsService(const KMoreTools &);
513 
514  KMoreToolsServicePrivate *d;
515 };
516 
517 // --------------------------------------------------------------------------------------
518 // --------------------------------------------------------------------------------------
519 
520 class KMoreToolsMenuItem;
521 class KMoreToolsMenuBuilderPrivate;
522 
523 /**
524  * Define how the default structure of the menu should look like.
525  *
526  * Depending on if the added service is installed or not a "Not installed" section
527  * will be automatically added to the generated menu.
528  *
529  * @since 5.10
530  */
531 class KNEWSTUFF_EXPORT KMoreToolsMenuBuilder
532 {
533  friend class KMoreToolsPrivate;
534  friend class KMoreTools;
535  friend class KMoreToolsTest;
536  friend class KMoreToolsTest2;
537  friend class KMoreToolsTestInteractive;
538 
539 public:
541 
543  KMoreToolsMenuBuilder &operator=(const KMoreToolsMenuBuilder &) = delete;
544 
545  /**
546  * Affects addMenuItem() if called before it.
547  *
548  * see KMoreToolsService::formatString, see KMoreToolsMenuItem::setInitialItemText
549  *
550  * The default template text is "$GenericName".
551  */
552  void setInitialItemTextTemplate(const QString &templateText);
553 
554  /**
555  * Adds a registered service (which can installed or not) to the menu.
556  * If the service is not installed it will be shown in the "Not installed"
557  * section.
558  *
559  * @param registeredService will be added to a the menu. A unique menu
560  * itemId will be generated automatically from the desktopEntryName.
561  * See also KMoreToolsMenuItem::id().
562  *
563  * @param defaultLocation is KMoreTools::MenuSection_Main by default.
564  *
565  * The registeredService->isInstalled() result will be respected. E.g. if the service
566  * is not installed it will be placed in the "Not installed" section in the more
567  * location of the menu even if @p defaultLocation was main location.
568  *
569  * See also KMoreToolsMenuItem ctor
570  *
571  * @sa KMoreToolsMenuItem::action()
572  */
573  KMoreToolsMenuItem *addMenuItem(KMoreToolsService *registeredService, KMoreTools::MenuSection defaultLocation = KMoreTools::MenuSection_Main);
574 
575  /**
576  * Adds an action to the menu which is created and managed by the caller.
577  *
578  * @param action to be added to the menu.
579  *
580  * @param itemId is a unique (for this menu) id for the item. The itemId
581  * _may_ be not unique. Then a unique id is generated automatically by
582  * using some postfix. But it is better if you specify something sensible
583  * because the itemId is used to find the items in the user config.
584  * Otherwise the user config can be messed up if the order or number
585  * of default menu items changes. NOTE, that the QAction::text is NOT
586  * used to generate the unique id because the text is translated and
587  * therefore not stable.
588  *
589  * @sa KMoreToolsMenuItem::action()
590  */
591  KMoreToolsMenuItem *addMenuItem(QAction *action, const QString &itemId, KMoreTools::MenuSection defaultLocation = KMoreTools::MenuSection_Main);
592 
593  /**
594  * Clears all added menu items. This can be useful if the menuBuilder is reused more than once.
595  *
596  * @sa KMoreToolsService::menuBuilder
597  */
598  void clear();
599 
600  /**
601  * Builds the actual menu and appends all items (main items,
602  * more submenu with a potential "not installed" section) to the @p menu.
603  *
604  * @param menu the menu where the items should be appended to
605  *
606  * @param configureDialogAccessibleSetting determines when the
607  * "Configure..." menu item should be added to the menu
608  *
609  * @param moreMenu if not nullptr then it will be set to the pointer to the
610  * "More" menu in case it was created.
611  * Otherwise the pointer will set to nullptr.
612  * This can be used to add some custom items to the @p menu.
613  */
614  void buildByAppendingToMenu(QMenu *menu,
616  QMenu **outMoreMenu = nullptr);
617 
618 private:
619  /**
620  * for unit testing / get as debug string
621  */
622  QString menuStructureAsString(bool mergeWithUserConfig) const;
623 
624  /**
625  * for unit testing
626  */
627  void showConfigDialog(const QString &title);
628 
629  /**
630  * (needed because QMap needs a default ctor)
631  */
633 
634  /**
635  * internal usage
636  */
637  KMoreToolsMenuBuilder(const QString &uniqueId, const QString &userConfigPostfix);
638 
639  /**
640  * No copy semantic => private and no implementation
641  */
643 
644  KMoreToolsMenuBuilderPrivate *d;
645 };
646 
647 // --------------------------------------------------------------------------------------
648 // --------------------------------------------------------------------------------------
649 
650 class KMoreToolsMenuItemPrivate;
651 
652 /**
653  * Represents a menu item of a service (application, tool or variant of the same
654  * service with different parameters).
655  *
656  * The service might be installed or not.
657  *
658  * The corresponding QAction will be created for installed services.
659  *
660  * @note that for not-installed services action() returns nullptr.
661  *
662  * @since 5.10
663  */
664 class KNEWSTUFF_EXPORT KMoreToolsMenuItem
665 {
666  friend class KMoreToolsMenuBuilderPrivate;
667  friend class KMoreToolsMenuBuilder;
668 
669 public:
670  KMoreToolsMenuItem(const KMoreToolsMenuItem &) = delete;
671  KMoreToolsMenuItem &operator=(const KMoreToolsMenuItem &) = delete;
672 
673  /**
674  * Auto-generated unique id that tries to be as stable as possible even if the
675  * menu gets restructured after the user did some customization that was
676  * persisted in a config file.
677  *
678  * @note It is possible to add the same service more than once (and then
679  * hopefully change the action text). When the order of those are changed,
680  * the id will not be consistent (because internally an increasing number is used)
681  * If you have issues with this you can solve this by manually
682  * calling setId (e.g. 'desktopEntryName' + 'x').
683  */
684  QString id() const;
685 
686  /**
687  * (Optional) to help with stable ids (see id())
688  *
689  * todo: make sure that if this is called, uniqueness of ids will be assured.
690  * todo: make sure to show error if the id contains characters other than
691  * alphanumerica, dashes and underscores etc.
692  */
693  void setId(const QString &id);
694 
695  /**
696  * @return the underlying KMoreToolsService instance,
697  * see KMoreToolsMenuBuilder::addMenuItem (with KKmoreToolsService* argument).
698  * Or nullptr when KMoreToolsMenuBuilder::addMenuItem (with QAction* argument
699  * was used).
700  */
701  KMoreToolsService *registeredService() const;
702 
703  /**
704  * see KMoreToolsMenuBuilder::addMenuItem
705  */
706  KMoreTools::MenuSection defaultLocation() const;
707 
708  /**
709  * see setInitialItemText()
710  */
711  QString initialItemText() const;
712 
713  /**
714  * Sets the initial text of a menu item.
715  *
716  * Menu items of a non-installed service will get this text.
717  * If the service is installed and you would like to change the item text,
718  * you can retrieve the created QAction (action())
719  * and modify the text using QAction's methods (QAction::setText()).
720  *
721  * @see
722  * - initialItemText()
723  * - action()
724  * - You can use the static method KMoreToolsService::formatString here.
725  */
726  void setInitialItemText(const QString &itemText);
727 
728  /**
729  * Case 1
730  * ------
731  * KMoreToolsMenuBuilder::addMenuItem was called with KKmoreToolsService* argument.
732  *
733  * the corresponding QAction which will be added to the actual menu when
734  * underlying service is installed or else - if not installed - nullptr.
735  *
736  * So you can change the created action as you desire.
737  *
738  * We return nullptr because not-installed services will get a submenu with
739  * other items like opening a website instead of an single action.
740  *
741  * To change the item's text even for not-installed services use initialItemText()
742  *
743  * Note, that once the method was invoked the first time the action is created
744  * an then reused.
745  *
746  * Case 2
747  * ------
748  * KMoreToolsMenuBuilder::addMenuItem was called with QAction* argument.
749  * The added action will be returned.
750  *
751  * @see KMoreToolsService::isInstalled
752  */
753  QAction *action() const;
754 
755 private: // internal usage
756  /**
757  * Sets the initial item text.
758  */
759  KMoreToolsMenuItem(KMoreToolsService *registeredService, KMoreTools::MenuSection defaultLocation, const QString &initialItemTextTemplate);
760 
761  KMoreToolsMenuItem(QAction *action, const QString &itemId, KMoreTools::MenuSection defaultLocation);
762 
764 
765 private:
766  KMoreToolsMenuItemPrivate *d;
767 };
768 
769 #endif // KMORETOOLS_H
ConfigureDialogAccessibleSetting
Specify if the Configure dialog be accessible from the menu (via a "Configure..." menu item) ...
Definition: kmoretools.h:219
A service described in a .desktop file (kmt-desktopfile) which will be called "registered service"...
Definition: kmoretools.h:357
Define how the default structure of the menu should look like.
Definition: kmoretools.h:531
Represents a menu item of a service (application, tool or variant of the same service with different ...
Definition: kmoretools.h:664
The item is placed in the "More" submenu.
Definition: kmoretools.h:195
by existence of desktop file (discoverable by KService)
Definition: kmoretools.h:174
Always show the "Configure..." menu item (default)
Definition: kmoretools.h:224
ServiceLocatingMode
Specify how should be determined if a service is installed or not.
Definition: kmoretools.h:170
MenuSection
Specify where a menu item be placed by default.
Definition: kmoretools.h:186
Defensively show the "Configure..." menu item.
Definition: kmoretools.h:238
by existence of executable defined in the TryExec or Exec line of the provided kmt-desktopfile ...
Definition: kmoretools.h:180
Helps to create user-configurable menus with tools which are potentially not yet installed.
Definition: kmoretools.h:161
The item is placed in the main section (default)
Definition: kmoretools.h:190
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed May 12 2021 22:41:40 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.