Git commit 232574857df9c48216e99b51f80c958b5a5ea84a by Thomas Friedrichsmeier. Committed on 03/12/2014 at 14:08. Pushed by tfry into branch 'master'.
Document new menu ordering mechanism M +0 -1 ChangeLog M +46 -10 doc/rkwardplugins/index.docbook http://commits.kde.org/rkward/232574857df9c48216e99b51f80c958b5a5ea84a diff --git a/ChangeLog b/ChangeLog index 9eaa4a6..ceb6ba3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,7 +3,6 @@ - Fixed: Freezes when using RKWard-functionality (such as the RK()-device) from tcl/tk (e.g. Rcmdr) - Allow opening RKWard's plugin files (with correct highlighting), and other text files - More robust control over placement of plugins within a menu - - TODO: document, discuss - Fix several issues of excessive printing of digits in plugins' output - Restructure layout of CSV-import dialog - Allow to open (any number of) R script files and rkward://-urls from the command line diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook index 9d59ca0..4984ef5 100644 --- a/doc/rkwardplugins/index.docbook +++ b/doc/rkwardplugins/index.docbook @@ -189,14 +189,14 @@ This is a guide to writing plugins for &rkward;. </para> <programlisting> <hierarchy> - <menu id="analysis" label="Analysis" index="4"> + <menu id="analysis" label="Analysis"> </programlisting> <para> - Right below the <command><hierarchy></command> tag, you start describing, in which <command><menu></command> your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name. The <parameter>index</parameter> attribute says, that the menu (if newly created) should be placed at the fourth position in the menubar. + Right below the <command><hierarchy></command> tag, you start describing, in which <command><menu></command> your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you'd give it its name. Finally, the <parameter>id</parameter> once again identifies this <command><menu></command>. This is needed, so several &pluginmap; files can place their plugins in the same menus. They do this by looking for a <command><menu></command> with the given <parameter>id</parameter>. If the ID does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu. </para> <programlisting> - <menu id="means" label="Means" index="1"> + <menu id="means" label="Means"> </programlisting> <para> Basically the same thing here: Now we define a submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. It is to be called <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>. @@ -205,7 +205,7 @@ This is a guide to writing plugins for &rkward;. <menu id="ttests" label="t-Tests"> </programlisting> <para> - And a final level in the menu hierarchy: A submenu of the submenu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>. Note, that if you omit the <parameter>index</parameter> parameter, the new entry will be placed below any already existing ones. + And a final level in the menu hierarchy: A submenu of the submenu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>. </para> <programlisting> <entry component="t_test_two_vars" /> @@ -226,16 +226,16 @@ This is a guide to writing plugins for &rkward;. <programlisting> [...] </menu> - <entry component="corr_matrix" index="4"/> - <entry component="descriptive" index="3"/> - <entry component="simple_anova" index="5"/> + <entry component="corr_matrix"/> + <entry component="descriptive"/> + <entry component="simple_anova"/> </menu> </programlisting> <para> - These are the final entries visible in the screenshots below. Note, that you don't need to define the entries in the order they should have in the menu. Use the <parameter>index</parameter> attribute instead. + These are the final entries visible in the screenshots below. </para> <programlisting> - <menu id="plots" label="Plots" index="5"> + <menu id="plots" label="Plots"> [...] </menu> </programlisting> @@ -243,7 +243,7 @@ This is a guide to writing plugins for &rkward;. Of course you can also place your plugins in menus other than <menuchoice><guimenu>Analysis</guimenu></menuchoice>. </para> <programlisting> - <menu id="file" label="File" index="0"> + <menu id="file" label="File"> [...] </menu> </programlisting> @@ -271,6 +271,42 @@ This is a guide to writing plugins for &rkward;. <para> Confused? The easiest way to get started is probably taking some of the existing &pluginmap; files shipped with the distribution, and modifying them to your needs. Also, if you need help, don't hesitate to write to the development mailing list. </para> + <sect1 id="pluginmap_grouping"><title>Controlling the order of menu entries</title> + <para>By default, all items (entries / submenus) inside a menu will be sorted alphabetically, automatically. In <emphasis>some</emphasis> cases you may want more control. In this case you can group elements as follows:</para> + <itemizedlist> + <listitem> + <para>You can define groups inside any menu like this. All elements belonging to the same group will be grouped together:</para> + <programlisting> + <group id="somegroup"/> + </programlisting> + </listitem><listitem> + <para>If you want the group to be visually separated from other entries, use:</para> + <programlisting> + <group id="somegroup" separated="true"/> + </programlisting> + </listitem><listitem> + <para>Entries, menus, and groups can be appended to a specified group, using:</para> + <programlisting> + <entry component="..." group="somegroup"/> + </programlisting> + </listitem><listitem> + <para>In fact, it is also possible to define groups (without separator lines) implicitly:</para> + <programlisting> + <entry component="first" group="a"/> + <entry component="third"/> + <entry component="second" group="a"/> + </programlisting> + </listitem><listitem> + <para>Group names are specific to each menu. Group "a" in menu "Data" does not conflict with group "a" in menu "Analysis", for example.</para> + </listitem><listitem> + <para>The most common use case is defining groups at the top, or at the bottom of a menu. For this, there are pre-defined groups "top" and "bottom" in each menu.</para> + </listitem><listitem> + <para>Entries within each group are sorted, alphabetically. Groups appear in the order of declaration (unless appended to another group, of course).</para> + </listitem><listitem> + <para>Menus and entries without group specification logically form a group (""), too.</para> + </listitem> + </itemizedlist> + </sect1> </chapter> <chapter id="mainxml">
