add CDATA + role in the gui module
[scilab.git] / scilab / modules / gui / help / en_US / addmenu.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="addmenu">
3   <info>
4     <pubdate>$LastChangedDate$</pubdate>
5   </info>
6   <refnamediv>
7     <refname>addmenu</refname>
8     <refpurpose> interactive button or menu definition</refpurpose>
9   </refnamediv>
10   <refsynopsisdiv>
11     <title>Calling Sequence</title>
12     <synopsis>addmenu(button [,submenus] [,action])
13 addmenu(gwin,button [,submenus] [,action])</synopsis>
14   </refsynopsisdiv>
15   <refsection>
16     <title>Parameters</title>
17     <variablelist>
18       <varlistentry>
19         <term>button</term>
20         <listitem>
21           <para>a character string. The button name. An &amp; can be placed before the character
22   in the name to be used for keyboard shortcut; this character will be
23   underlined on the GUI. Under MacOSX, a sub-menu with the same name is automaticaly added (no button can be added to the menu bar).</para>
24         </listitem>
25       </varlistentry>
26       <varlistentry>
27         <term>submenus</term>
28         <listitem>
29           <para>a vector of character string. The sub_menus items names</para>
30         </listitem>
31       </varlistentry>
32       <varlistentry>
33         <term>action</term>
34         <listitem>
35           <para>a list with 2 elements action=list(flag,proc_name)</para>
36           <variablelist>
37             <varlistentry>
38               <term>flag</term>
39               <listitem>
40                 <para>an integer (default value is 0)</para>
41               </listitem>
42             </varlistentry>
43             <varlistentry>
44               <term>flag==0</term>
45               <listitem>
46                 <para>the action is defined by a scilab instruction</para>
47               </listitem>
48             </varlistentry>
49             <varlistentry>
50               <term>flag==1</term>
51               <listitem>
52                 <para>the action is defined by a C or Fortran procedure</para>
53               </listitem>
54             </varlistentry>
55             <varlistentry>
56               <term>flag==2</term>
57               <listitem>
58                 <para>the action is defined by a scilab function</para>
59               </listitem>
60             </varlistentry>
61             <varlistentry>
62               <term>proc_name</term>
63               <listitem>
64                 <para>a character string which gives the name of scilab variable
65     containing the instruction or the name of procedure to
66     call.</para>
67               </listitem>
68             </varlistentry>
69           </variablelist>
70         </listitem>
71       </varlistentry>
72       <varlistentry>
73         <term>gwin</term>
74         <listitem>
75           <para>integer. The number of graphic window where the button is required to be installed</para>
76         </listitem>
77       </varlistentry>
78     </variablelist>
79   </refsection>
80   <refsection>
81     <title>Description</title>
82     <para>
83     The function allows the user to add new buttons or menus in the main
84     window or graphics windows command panels.
85   </para>
86     <variablelist>
87       <varlistentry>
88         <term>If</term>
89         <listitem>
90           <para><literal>action</literal> argument is not given the action associated
91     with a button must be defined by a scilab instruction given by the
92     character string variable which name is</para>
93           <para> +  <literal>button</literal> for a main window command</para>
94           <para> +  <literal>button_gwin</literal> for a graphic window command</para>
95         </listitem>
96       </varlistentry>
97       <varlistentry>
98         <term>If</term>
99         <listitem>
100           <para><literal>action</literal>  argument is set to 0 <literal>proc_name</literal>
101     should be the name of a Scilab string vector.  Actions associated
102     with the kth sub_menu must be defined by scilab instructions
103     stored in the kth element of the character string variable.</para>
104         </listitem>
105       </varlistentry>
106       <varlistentry>
107         <term>If</term>
108         <listitem>
109           <para><literal>action</literal> argument is set to 1 <literal>proc_name</literal>
110     designes a C or Fortran procedure, this procedure may be
111     interfaced in Fortran subroutine default/fbutn.f or dynamically
112     linked with scilab using the <literal>link</literal> function. The C
113     calling sequence is: <literal>(char* button_name, int* gwin,int *k)</literal></para>
114         </listitem>
115       </varlistentry>
116       <varlistentry>
117         <term>If</term>
118         <listitem>
119           <para><literal>action</literal> argument is set to 2 <literal>proc_name</literal>
120     designes a Scilab function. This function calling sequence should
121     be:</para>
122           <para> +  <literal>proc_name(k)</literal>for a main window command</para>
123           <para> +  <literal>proc_name(k,gwin)</literal>for a graphic window
124     command or a main window command</para>
125         </listitem>
126       </varlistentry>
127     </variablelist>
128   </refsection>
129   <refsection>
130     <title>Examples</title>
131     <programlisting role="example"><![CDATA[ 
132 addmenu('foo')
133 foo='disp(''hello'')'
134
135 addmenu('Hello',['Franck';'Peter'])
136 Hello=['disp(''hello Franck'')';'disp(''hello Peter'')']
137
138 addmenu(0,'Hello',['Franck';'Peter'])
139 Hello_0=['disp(''hello Franck'')';'disp(''hello Peter'')']
140
141 addmenu('Bye',list(0,'French_Bye'))
142 French_Bye='disp(''Au revoir'')'
143
144 //C defined Callback
145 // creating Callback code
146 code=[ '#include ""machine.h""'
147        'void foo(char *name,int *win,int *entry)'
148        '{'
149        '  if (*win==-1) '
150        '    sciprint(""menu %s(%i) in Scilab window selected\r\n"",name,*entry+1);'
151        '  else'
152        '    sciprint(""menu %s(%i) in window %i selected\r\n"",name,*entry+1,*win);'
153        '}'];
154 //creating foo.c file
155 dir=pwd(); chdir(TMPDIR)
156 mputl(code,TMPDIR+'/foo.c');
157 //reating Makefile
158 ilib_for_link('foo','foo.o',[],'c');
159 exec('loader.sce');
160 chdir(dir);
161 //add menu
162 addmenu('foo',['a','b','c'],list(1,'foo'))
163  ]]></programlisting>
164   </refsection>
165   <refsection>
166     <title>See Also</title>
167     <simplelist type="inline">
168       <member>
169         <link linkend="setmenu">setmenu</link>
170       </member>
171       <member>
172         <link linkend="unsetmenu">unsetmenu</link>
173       </member>
174       <member>
175         <link linkend="delmenu">delmenu</link>
176       </member>
177     </simplelist>
178   </refsection>
179 </refentry>