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