Git commit 12388e7222ac1727dcb376b42d6601771efc2760 by Burkhard L?ck. Committed on 23/09/2013 at 19:18. Pushed by lueck into branch 'KDE/4.11'.
KMenuedit documentation - improve introduction chapter and add use case section (cherry picked from commit 8d526e154d45c001010576f5c671bcbc5eb22bbf) REVIEW:112575 backport to 4.11.3 M +148 -11 doc/kmenuedit/index.docbook http://commits.kde.org/kde-workspace/12388e7222ac1727dcb376b42d6601771efc2760 diff --git a/doc/kmenuedit/index.docbook b/doc/kmenuedit/index.docbook index f62b55a..c15f1db 100644 --- a/doc/kmenuedit/index.docbook +++ b/doc/kmenuedit/index.docbook @@ -35,7 +35,7 @@ <legalnotice>&FDLNotice;</legalnotice> -<date>2013-06-19</date> +<date>2013-09-07</date> <releaseinfo>0.9 (&kde; 4.11)</releaseinfo> <abstract><para>&kmenuedit; allows editing one of the &kde; application launchers: &kickoff;, the classic &kmenu; or Lancelot Launcher. @@ -56,7 +56,7 @@ <chapter id="introduction"> <title>Introduction</title> -<para>&kmenuedit; allows editing of &kde; application launchers: &kickoff;, classic &kmenu; or Lancelot Launcher.</para> +<para>&kmenuedit; allows editing the menu of &kde; application launchers: &kickoff;, classic &kmenu; or Lancelot Launcher.</para> <para>&kmenuedit; can be started either by &RMB; clicking the application launcher button on the panel and choosing <guimenuitem>Edit @@ -66,12 +66,136 @@ by typing <userinput>kmenuedit</userinput> in the &krunner; line.</para> <para>&kmenuedit; allows you to:</para> <itemizedlist> -<listitem><para>View and edit the current application launcher (&kickoff;, classic menu or Lancelot Launcher)</para></listitem> +<listitem><para>View and edit the menu used by the current application launcher (&kickoff;, classic menu or Lancelot Launcher)</para></listitem> <listitem><para><guimenuitem>Cut</guimenuitem>, <guimenuitem>Copy</guimenuitem> -and <guimenuitem>Paste</guimenuitem> menu items</para></listitem> -<listitem><para>Create and delete submenus</para></listitem> +and <guimenuitem>Paste</guimenuitem> submenus and items</para></listitem> +<listitem><para>Create and delete submenus and items</para></listitem> +<listitem><para>Change the order of submenus and items</para></listitem> +<listitem><para>Hide items and add new submenus and items</para></listitem> </itemizedlist> +<para>By default all applications installed on the computer appear in the application launchers menu of all users. +Applications may appear more than once in several different menus. +Empty submenu categories defined in the desktop menu specification will show up as well, +but are not visible in application launchers unless you install applications belonging to these categories. +</para> + +<para>The tree view has three different entry types:</para> +<itemizedlist> +<listitem><para>Submenu: Only <guilabel>Name</guilabel>, <guilabel>Comment</guilabel> and +<guilabel>Description</guilabel> fields and the button to select an icon +are enabled, the <guilabel>Advanced</guilabel> tab is disabled. +Any submenu can hold additional submenus and/or items. +</para></listitem> +<listitem><para>Items: Use this entry to enter the data for the application you want to add. +For detailed information see <link linkend="using-kmenuedit">Using &kmenuedit;</link>. +</para></listitem> +<listitem><para>Separator: A visual entry to structure the menu. It cannot be modified +and all editing actions are disabled. +</para></listitem> +</itemizedlist> + +<para>&kmenuedit; has two tree view modes - normal and with hidden entries. To see the latter check the option +<guilabel>Show hidden entries</guilabel> in the configuration dialog on the <guilabel>General options</guilabel> page. +</para> +<para>Many additional entries appear in hidden view mode in the tree. Several hidden entries seem to be just duplicates +but have different command options. Usually you should never change these hidden entries or you risk to break some +functionality of the system. +</para> +<para>In hidden mode you will have a special submenu <guilabel>.hidden [Hidden]</guilabel> as top level +item in the tree. This special submenu is not editable. In this submenu all deleted items will be shown at the next +start of &kmenuedit;.</para> +<para>It is not possible to delete entries using the &GUI; in this special submenu. They will reappear at the +next start of &kmenuedit;. +</para> + +<sect1 id="use-cases"> +<title>Use Cases</title> + +<sect2 id="use-cases-adapt"> +<title>Adapt the Menu for a User</title> + +<sect3 id="use-cases-adapt-order"> +<title>Reorder Items</title> + +<para>This should be done in hidden view mode where only the submenus and items visible in the application +launcher menu are displayed. +</para> +<para>By default the menu is sorted alphabetically using the English names or descriptions. Using another language +than English some submenus and items therefor will appear in an unsorted order. +</para> +<para>Use the options in <menuchoice><guimenu>Edit</guimenu><guimenuitem>Sort</guimenuitem></menuchoice> +to sort either by name or description. If you use the classic application launcher you have to select the +corresponding <guilabel>Format</guilabel> option in the settings dialog. In the &kickoff; launcher check +<guilabel>Show applications by name</guilabel> if you sort them by name here. +</para> +<para>Grouping your frequently used submenus or items together ⪚ at the top of the menu makes selecting them easier. +To change the order of single items or submenus in the tree use the <guibutton>Move Up</guibutton> or +<guibutton>Move Down</guibutton> button in the toolbar or these actions in the menu. +</para> +<para>All application launchers will use the order of submenus defined in &kmenuedit;. +</para> +</sect3> + +<sect3 id="use-cases-adapt-hide"> +<title>Remove Items from the Menu View</title> + +<para>Having all applications installed on a computer may be confusing for some users so you may +want to hide some less frequently used items or submenus. There are two different ways to do that: +</para> + +<para>Switch to normal view mode without hidden entries. If you delete items they are moved to the +<guilabel>.hidden [Hidden]</guilabel> submenu. You can move them back into the tree to have them in the menu again. +</para> +<para>If you delete a submenu it will be really deleted with all its submenus and items. +To recreate them you can use <menuchoice><guimenu>Edit</guimenu><guimenuitem>Restore to System +Settings</guimenuitem></menuchoice>, but this will remove all your custom submenus and items +and the corresponding <filename class="extension">.desktop</filename> files are deleted too. This action cannot be reverted. +</para> + +<para>The preferred way to remove submenus and items in the menu of an application launcher is to check <guilabel>Hide +entry</guilabel> on the <guilabel>General</guilabel> tab and switch to the hidden view mode. +In this mode it is easy to revert changes without destroying the menu structure. +The only drawback is that you have to hide all entries in a submenu manually to +hide the whole submenu from the view. +</para> +</sect3> + +</sect2> + +<sect2 id="use-cases-additems"> +<title>Adding Custom Items</title> + +<para>To add custom items (submenu, item or separator) use the actions in the menu or toolbar. +Items need a Name and a Command, without a command entry an item will not be saved and your addition gets lost. +</para> +<para>If you add an entry it is inserted as sub entry at the actual highlighted position in the tree. +Move an entry by dragging it with the mouse or using the <guibutton>Move Down</guibutton> button +to the bottom of the tree to make it a top level entry. +</para> + +</sect2> + +<sect2 id="use-cases-transfer"> +<title>Transfer application launcher settings</title> + +<para>There is no way to transfer menu settings using the &GUI;, you have to do that manually +and copy the following files to the target user:</para> +<para>&kmenuedit; stores the menu hierarchy in +<filename class="directory">$<envar>HOME</envar>/.config/menus/applications-kmenuedit.menu</filename> +and <filename class="directory">$<envar>HOME</envar>/.local/share/desktop-directories</filename> +contains desktop files for submenus you created. +In <filename class="directory">$<envar>HOME</envar>/.local/share/applications/</filename> you +find the desktop files for the custom items you created. +</para> +<para>The shortcuts for each application are stored in <filename>~/.kde/share/config/kglobalshortcutsrc</filename>, +but export/import does not work because the UUIDs of the shortcuts do not match up between systems, even though the +<filename class="extension">.desktop</filename> files are the same. You have to assign all shortcuts manually again. +</para> + +</sect2> + +</sect1> </chapter> <chapter id="quickstart"> @@ -126,7 +250,14 @@ Press return, and you should see something like the picture below in the main wi </screenshot></para> <para> - Now lets fill in the <guilabel>Description:</guilabel>, in this case type <userinput>Web Browser</userinput>. <note><para>The description and name will be displayed on the application launcher as <quote>Web Browser (Firefox)</quote>.</para></note> We will need to fill in the executable name in the <guilabel>Command:</guilabel> field, in this instance we will type <userinput><command>firefox</command></userinput>.</para> +Now lets fill in the <guilabel>Description:</guilabel>, in this case type <userinput>Web Browser</userinput>. +<note><para>The appearance how description and name will be displayed depends on the settings in the application +launcher ⪚ <quote>Web Browser (Firefox)</quote> or <quote>Firefox (Web Browser)</quote>.</para></note> +We will need to fill in the executable name in the <guilabel>Command:</guilabel> field, in this instance we will type <userinput><command>firefox</command></userinput>.</para> +<para>The command has to be in your <envar>PATH</envar> variable or you have to specify the full path to the executable. +If you do not know the executable name of an application use the <userinput><command>locate</command></userinput> +command to search for the desktop file and enter the string from the Exec line as command here. +</para> <note><para>Following the command, you can have several place holders which will be replaced with actual values when the program is run: <simplelist> <member>%f - a single file name</member> @@ -168,11 +299,10 @@ To see all options for an application launch <userinput><command><replaceable>ap </mediaobject> </screenshot></para> -<para>The place of the new menu item can now be changed using <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons on the &kmenuedit; toolbar.</para> - +<para>The place of the new menu item can now be changed using <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton> buttons on the &kmenuedit; toolbar or by dragging with the mouse.</para> <para>The submenu items can be sorted using <guibutton>Sort</guibutton> button on the &kmenuedit; toolbar or <menuchoice><guimenu>Edit</guimenu><guisubmenu>Sort</guisubmenu></menuchoice> submenu items.</para> -<para>Click <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>, wait for the <guilabel>Updating System Configuration</guilabel> dialog to get finished, you should find &firefox; in the application launcher <guisubmenu>Internet</guisubmenu> submenu!</para> +<para>Click <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>, wait for the <guilabel>Updating System Configuration</guilabel> dialog to get finished, you should find &firefox; in the application launcher <guisubmenu>Internet</guisubmenu> submenu.</para> </chapter> @@ -226,6 +356,10 @@ application. <listitem><para>When checked, the application entry will only be visible in all &kde; application launchers but not in other desktops environments. </para></listitem> </varlistentry> +<varlistentry> +<term><guilabel>Hidden entry</guilabel></term> +<listitem><para>Remove an entry from the menu view in the application launcher. </para></listitem> +</varlistentry> </variablelist> </sect1> @@ -285,6 +419,9 @@ fileref="reset.png" format="PNG"/></imageobject></inlinemediaobject>. <chapter id="menu-reference"> <title>Menu Reference</title> +<para>Most actions in the menubar are also available in the context menu opened with a &RMB; +click on an item in the tree view.</para> + <variablelist> <varlistentry id="file-new-item"> <term><menuchoice> @@ -375,7 +512,7 @@ Edit</guimenu> <guimenuitem>Copy</guimenuitem> </menuchoice></term> <listitem><para><action>Copies the current menu item to the clipboard</action>. You can later use the <guimenuitem>Paste</guimenuitem> -function to paste the copied menu itemfrom the clipboard to its destination. You +function to paste the copied menu item from the clipboard to its destination. You can paste the same item many times.</para></listitem> </varlistentry> @@ -387,7 +524,7 @@ can paste the same item many times.</para></listitem> <guimenu>Edit</guimenu> <guimenuitem>Paste</guimenuitem> </menuchoice></term> <listitem><para><action>Paste menu item from the clipboard</action> to currently -selected place in the <guimenu>Main</guimenu> menu. You must first use +selected place in the main menu. You must first use <guimenuitem>Cut</guimenuitem> or <guimenuitem>Copy</guimenuitem> before you can <guimenuitem>Paste</guimenuitem>.</para></listitem> </varlistentry>
