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>