* Bug 16008 fixed [doc]: uimenu_properties was not up-to-date
[scilab.git] / scilab / modules / gui / help / en_US / menus / uimenu_properties.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  *
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="uimenu_properties" xml:lang="en">
20     <refnamediv>
21         <refname>uimenu properties</refname>
22         <refpurpose>Description of uimenu properties.</refpurpose>
23     </refnamediv>
24     <refsection>
25         <title>Description</title>
26         <para>This page lists all available properties for menus in Scilab GUI.</para>
27         <para>
28             These properties can be set at creation through the <link linkend="uimenu">uimenu</link>
29             function, or at any time later with the <literal>handle.property = value</literal>
30             usual syntax.
31         </para>
32         <para>
33             Several properties can also be changed in the same time using the
34             <link linkend="set">set</link>(handle, "propName1",propValue1, "propName2",propValue2, ..)
35             function.
36         </para>
37     </refsection>
38     <refsection>
39         <title>Properties</title>
40         <variablelist>
41             <varlistentry>
42                 <term>Callback</term>
43                 <listitem>
44                     <para>String</para>
45                     <para>
46                         Instruction evaluated by the Scilab interpreter when the menu is activated.
47                         Under MacOSX, the callback will not be executed for a "button menu"
48                         (a menu without children), you must specify at least a child.
49                     </para>
50                     <para>
51                         If any, every occurence of the "[SCILAB_FIGURE_ID]" substring is replaced
52                         in the callback string with the figure_id value of the parent figure,
53                         at calling time .
54                     </para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>Callback_Type</term>
59                 <listitem>
60                     <para>
61                         Scalar. Integer code setting the way the callback string must be interpreted
62                         to perform the action:
63                     </para>
64                     <table>
65                         <tr>
66                             <th>-1</th><td>:</td>
67                             <td>callback disabled.</td>
68                         </tr>
69                         <tr>
70                             <th>0</th><td>:</td>
71                             <td>
72                                 (default) non prioritary (or interruptible) Scilab instructions.
73                                 Example: .callback = "help(""uimenu"")"
74                             </td>
75                         </tr>
76                         <tr>
77                             <th>1</th><td>:</td>
78                             <td>Fortran function</td>
79                         </tr>
80                         <tr>
81                             <th>2</th><td>:</td>
82                             <td>non prioritary (or interruptible) Scilab function.</td>
83                         </tr>
84                         <tr>
85                             <th>3</th><td>:</td>
86                             <td>
87                                 Java reference. Example:
88                                 .callback = "org.scilab.modules.gui.editor.EditorManager.start([SCILAB_FIGURE_ID])"
89                             </td>
90                         </tr>
91                         <tr>
92                             <th>10</th><td>:</td>
93                             <td>prioritary (or non-interruptible) Scilab instructions.</td>
94                         </tr>
95                         <tr>
96                             <th>12</th><td>:</td>
97                             <td>prioritary (or non-interruptible) Scilab function</td>
98                         </tr>
99                     </table>
100                     <para/>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>Checked</term>
105                 <listitem>
106                     <para>on | {off}</para>
107                     <para>
108                         Item check indicator. Setting this property to "on" the first time displays
109                         a checkbox in head of the item's label, and then checks it. Setting "off"
110                         keeps the checkbox and unchecks it. This property can be used to display
111                         items indicating the state of particular options.
112                     </para>
113                     <para>Remarks:
114                         <itemizedlist>
115                             <listitem>
116                                 There is no way to remove the checkbox after its creation, but
117                                 deleting the item.</listitem><listitem>By default, no interactive
118                                 checking or unchecking is possible. Such interactions can be
119                                 implemented through the Callback property.
120                             </listitem>
121                             <listitem>
122                                 This property is ignored for parent menus.
123                             </listitem>
124                         </itemizedlist>
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>Children</term>
130                 <listitem>
131                     <para>vector of handles</para>
132                     <para>
133                         If the current uimenu item is a menu listing subitems, their handles are
134                         gathered in this Children property. All of them should be of type "uimenu".
135                         Otherwise, .Children is the empty matrix [].
136                     </para>
137                 </listitem>
138             </varlistentry>
139             <varlistentry>
140                 <term>Enable</term>
141                 <listitem>
142                     <para>{on} | off</para>
143                     <para>Enable or disable the menu. If this property is set to
144                         <literal>"on"</literal> (default), the menu is operational, but if
145                         this property is set to <literal>"off"</literal>, the menu will not
146                         respond to the mouse actions and will be grayed out.
147                     </para>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term>ForegroundColor</term>
152                 <listitem>
153                     <para>[1,3] real vector or string</para>
154                     <para>
155                         Foreground color of the uimenu (font color). A color is specified as Red,
156                         Green and Blue values. Those values are real in [0,1]. The color can be
157                         given as a real vector, ie [R,G,B] or a string where each value is
158                         separated by a "|", ie "R|G|B".
159                     </para>
160                 </listitem>
161             </varlistentry>
162             <varlistentry>
163                 <term>Handle_visible</term>
164                 <listitem>
165                     <para>on | {off}</para>
166                     <para>
167                         Setting it to "on" forces the uimenu handle to be visible in the list of
168                         its parent children, even if get(0).showhiddenhandles == "off".
169                     </para>
170                     <para>
171                         Setting it to "off" does NOT force it to be hidden:
172                         get(0).showhiddenhandles == "on" is stronger.
173                     </para>
174                 </listitem>
175             </varlistentry>
176             <varlistentry>
177                 <term>Icon</term>
178                 <listitem>
179                     <para>String.</para>
180                     <para>
181                         This property represents the relative
182                         (to <link linkend="pwd">Scilab working directory</link>) or absolute path
183                         of the image file to be used as icon for the menu.
184                     </para>
185                 </listitem>
186             </varlistentry>
187             <varlistentry>
188                 <term>Label</term>
189                 <listitem>
190                     <para>String.</para>
191                     <para>
192                         This property represents the text appearing in the menu.
193                         If the text is enclosed between two $ (dollar sign), then it will be
194                         considered as a LaTeX expression. If it is enclosed between &lt; and &gt;,
195                         it will be considered as a MathML one.
196                     </para>
197                     <para>
198                         If the text value starts with <literal>&lt;html></literal>, then
199                         all HTML-4 tags used in the label afterward are interpreted.
200                         This allows for instance to use HTML styling tags like &lt;b>..&lt;/>
201                         for bold, &lt;span color="red">..&lt;/span> to use a red font, etc.
202                     </para>
203                 </listitem>
204             </varlistentry>
205             <varlistentry>
206                 <term>Tag</term>
207                 <listitem>
208                     <para>String</para>
209                     <para>
210                         This property is generally used to identify the menu. It allows to give
211                         it a "name". Mainly used in conjunction with <literal>findobj()</literal>.
212                     </para>
213                 </listitem>
214             </varlistentry>
215             <varlistentry>
216                 <term>User_data</term>
217                 <listitem>
218                     <para>Any type of data</para>
219                     <para>
220                         This property can be used to store any scilab user or application data.
221                         In order to be easily extensible and portable, using a structure with
222                         fields is advised. [] is set by default.
223                     </para>
224                 </listitem>
225             </varlistentry>
226             <varlistentry>
227                 <term>Visible</term>
228                 <listitem>
229                     <para>{on} | off</para>
230                     <para>
231                         Set the visibility of the uimenu. If this property is set to
232                         <literal>"on"</literal> (default), the uimenu is visible,  but if this
233                         property is set to <literal>"off"</literal>, the uimenu will not appear
234                         in its parent figure.
235                     </para>
236                 </listitem>
237             </varlistentry>
238         </variablelist>
239     </refsection>
240     <refsection role="see also">
241         <title>See also</title>
242         <simplelist type="inline">
243             <member>
244                 <link linkend="uimenu">uimenu</link>
245             </member>
246             <member>
247                 <link linkend="uicontextmenu">uicontextmenu</link>
248             </member>
249             <member>
250                 <link linkend="uicontrol">uicontrol</link>
251             </member>
252             <member>
253                 <link linkend="console_properties">showHiddenHandles</link>
254             </member>
255             <member>
256                 <link linkend="set">set</link>
257             </member>
258             <member>
259                 <link linkend="math_rendering_features_in_graphic">LaTeX and MathML</link>
260             </member>
261         </simplelist>
262     </refsection>
263     <refsection>
264         <title>History</title>
265         <revhistory>
266             <revision>
267                 <revnumber>5.4.0</revnumber>
268                 <revremark>
269                     <literal>Handle_visible</literal> property added.
270                 </revremark>
271             </revision>
272             <revision>
273                 <revnumber>5.5.0</revnumber>
274                 <revremark>
275                     <literal>Icon</literal> property added.
276                 </revremark>
277             </revision>
278         </revhistory>
279     </refsection>
280 </refentry>