[kde-doc-english] [rkward] /: Document new menu ordering mechanism
Thomas Friedrichsmeier
thomas.friedrichsmeier at ruhr-uni-bochum.de
Wed Dec 3 14:20:54 UTC 2014
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">
More information about the kde-doc-english
mailing list