[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / gui / help / en_US / getvalue.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"
3           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
4           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
5           xml:lang="en" xml:id="getvalue">
6     <refnamediv>
7         <refname>getvalue</refname>
8         <refpurpose>xwindow dialog for data acquisition</refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Syntax</title>
12         <synopsis>[ok, x1,..,x14] = getvalue(desc, labels, typ, ini)</synopsis>
13     </refsynopsisdiv>
14     <refsection>
15         <title>Arguments</title>
16         <variablelist>
17             <varlistentry>
18                 <term>desc</term>
19                 <listitem>
20                     <para>
21                        column vector of strings, dialog general comment. Any "&lt;" character
22                        must be replaced with "&amp;lt;".
23                     </para>
24                 </listitem>
25             </varlistentry>
26             <varlistentry>
27                 <term>labels</term>
28                 <listitem>
29                     <para>
30                         n column vector of strings, <literal>labels(i)</literal> is the label of
31                         the ith required value.
32                     </para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>typ</term>
37                 <listitem>
38                     <para>
39                         <literal>list(typ_1,dim_1,..,typ_n,dim_n)</literal>
40                     </para>
41                     <variablelist>
42                         <varlistentry>
43                             <term>typ_i</term>
44                             <listitem>
45                                 <para>defines the type of the ith value. By default, inputs are
46                                   interpreted as decimal numbers. Columns of (rows of) values must
47                                   be separated with ";". typ_i may have the following values:</para>
48                                 <table>
49                                   <tr><th>"mat"</th><td>matrix</td></tr>
50                                   <tr><th>"col"</th><td>column vector</td></tr>
51                                   <tr><th>"row"</th><td>row vector</td></tr>
52                                   <tr><th>"vec"</th><td>vector (free orientation)</td></tr>
53                                   <tr><th>"intvec"</th><td>scalar, vector or matrix of integers.</td></tr>
54                                   <tr><th>"str"</th><td>scalar, vector or matrix of texts, delimited with ".."</td></tr>
55                                   <tr><th>"lis"</th><td>list: not implemented.</td></tr>
56                                 </table>
57                             </listitem>
58                         </varlistentry>
59                         <varlistentry>
60                             <term>dim_i</term>
61                             <listitem>
62                                 <para>
63                                     defines the size of the ith value it must be an integer or
64                                     a 2-vector of integer, -1 stands for undefined dimension.
65                                 </para>
66                             </listitem>
67                         </varlistentry>
68                     </variablelist>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>ini</term>
73                 <listitem>
74                     <para>
75                         n column vector of strings, <literal>ini(i)</literal> gives the suggested
76                         response for the ith required value
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>ok</term>
82                 <listitem>
83                     <para>boolean ,%t if ok button pressed, %f if cancel button pressed</para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>xi</term>
88                 <listitem>
89                     <para>
90                         contains the ith value if ok=%t. If left hand side has one more
91                         <literal>xi</literal> than required values the last  <literal>xi</literal>
92                         contains the vector of answered strings.
93                     </para>
94                 </listitem>
95             </varlistentry>
96         </variablelist>
97     </refsection>
98     <refsection>
99         <title>Description</title>
100         <para>
101             This function encapsulate <literal>x_mdialog</literal> function with error checking,
102             evaluation of numerical response, ...
103         </para>
104         <note>
105           <para>
106               All valid expressions can be used as inputs. For matrices and vectors,
107               <literal>getvalues()</literal> automatically adds [ ] around each group of input
108               before their evaluation.
109           </para>
110         </note>
111     </refsection>
112     <refsection>
113         <title>Examples</title>
114         <programlisting role="example"><![CDATA[
115 labels=["magnitude" ; "frequency" ; "phase    "];
116 [ok,mag,Freq,ph] = getvalue("define sine signal",labels,...
117      list("vec",1,"vec",1,"vec",1), ["0.85";"10^2";"%pi/3"])
118  ]]></programlisting>
119     </refsection>
120     <refsection role="see also">
121         <title>See also</title>
122         <simplelist type="inline">
123             <member>
124                 <link linkend="x_mdialog">x_mdialog</link>
125             </member>
126             <member>
127                 <link linkend="x_matrix">x_matrix</link>
128             </member>
129             <member>
130                 <link linkend="x_dialog">x_dialog</link>
131             </member>
132         </simplelist>
133     </refsection>
134 </refentry>