doc/new_ml_form_select.3.html

   1 <html>
   2 <head>
   3 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   4 <meta name="Content-Style" content="text/css">
   5 <title>new_ml_form_select</title>
   6 </head>
   7 <body>
   8
   9 <h1 align=center>new_ml_form_select</h1>
  10 <a href="#NAME">NAME</a><br>
  11 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  12 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  13 <a href="#AUTHOR">AUTHOR</a><br>
  14 <a href="#LICENSE">LICENSE</a><br>
  15 <a href="#VERSION">VERSION</a><br>
  16 <a href="#SEE ALSO">SEE ALSO</a><br>
  17
  18 <hr>
  19 <!-- Creator     : groff version 1.17.2 -->
  20 <!-- CreationDate: Sat Aug 31 18:06:11 2002 -->
  21 <a name="NAME"></a>
  22 <h2>NAME</h2>
  23 <table width="100%" border=0 rules="none" frame="void"
  24        cols="2" cellspacing="0" cellpadding="0">
  25 <tr valign="top" align="left">
  26 <td width="10%"></td><td width="90%">
  27 new_ml_form_select, ml_form_select_set_size, ml_form_select_get_size, ml_form_select_set_multiple, ml_form_select_get_multiple, ml_form_select_push_back, ml_form_select_pop_back, ml_form_select_push_front, ml_form_select_pop_front, ml_form_select_get, ml_form_select_insert, ml_form_select_replace, ml_form_select_erase, ml_form_select_clear, ml_form_select_size, ml_form_select_set_selection, ml_form_select_set_selections, ml_form_select_get_selection, ml_form_select_get_selections - monolith form select box input widget</td></table>
  28 <a name="SYNOPSIS"></a>
  29 <h2>SYNOPSIS</h2>
  30
  31 <table width="100%" border=0 rules="none" frame="void"
  32        cols="2" cellspacing="0" cellpadding="0">
  33 <tr valign="top" align="left">
  34 <td width="10%"></td><td width="90%">
  35 <pre><b>#include &lt;ml_form_select.h&gt;
  36
  37 ml_form_select new_ml_form_select (pool pool, ml_form form);
  38 void ml_form_select_set_size (ml_form_select w, int size);
  39 int ml_form_select_get_size (ml_form_select w);
  40 void ml_form_select_set_multiple (ml_form_select w, int multiple);
  41 int ml_form_select_get_multiple (ml_form_select w);
  42 void ml_form_select_push_back (ml_form_select w, const char *option);
  43 const char *ml_form_select_pop_back (ml_form_select w);
  44 void ml_form_select_push_front (ml_form_select w, const char *option);
  45 const char *ml_form_select_pop_front (ml_form_select w);
  46 const char *ml_form_select_get (ml_form_select w, int option_index);
  47 void ml_form_select_insert (ml_form_select w, int option_index, const char *option);
  48 void ml_form_select_replace (ml_form_select w, int option_index, const char *option);
  49 void ml_form_select_erase (ml_form_select w, int option_index);
  50 void ml_form_select_clear (ml_form_select w);
  51 int ml_form_select_size (ml_form_select w);
  52 void ml_form_select_set_selection (ml_form_select w, int option_index);
  53 void ml_form_select_set_selections (ml_form_select w, vector selected);
  54 int ml_form_select_get_selection (ml_form_select w);
  55 const vector ml_form_select_get_selections (ml_form_select w);
  56 </b></pre></td></table>
  57 <a name="DESCRIPTION"></a>
  58 <h2>DESCRIPTION</h2>
  59
  60 <table width="100%" border=0 rules="none" frame="void"
  61        cols="2" cellspacing="0" cellpadding="0">
  62 <tr valign="top" align="left">
  63 <td width="10%"></td><td width="90%">
  64 This is a select box for use in forms. It can appear in
  65 several ways: either as a drop-down menu, or as a selection
  66 box allowing single or multiple options to be
  67 selected.</td></table>
  68
  69 <table width="100%" border=0 rules="none" frame="void"
  70        cols="2" cellspacing="0" cellpadding="0">
  71 <tr valign="top" align="left">
  72 <td width="10%"></td><td width="90%">
  73 <b>new_ml_form_select</b> creates a new form select box
  74 input widget. The form into which this widget is being
  75 embedded is passed as the <b>form</b> parameter. The select
  76 box is created with no options, in drop-down mode (size 0),
  77 single choice (multiple 0).</td></table>
  78
  79 <table width="100%" border=0 rules="none" frame="void"
  80        cols="2" cellspacing="0" cellpadding="0">
  81 <tr valign="top" align="left">
  82 <td width="10%"></td><td width="90%">
  83 <b>ml_form_select_(set|get)_size</b> sets the size (number
  84 of rows) in the select box. If the size is 0, then the
  85 select box will be rendered as a drop-down menu. If the size
  86 is &gt; 0, then the select box will be rendered as a
  87 scrolling list of choices.</td></table>
  88
  89 <table width="100%" border=0 rules="none" frame="void"
  90        cols="2" cellspacing="0" cellpadding="0">
  91 <tr valign="top" align="left">
  92 <td width="10%"></td><td width="90%">
  93 <b>ml_form_select_(set|get)_multiple</b> sets the multiple
  94 boolean property of the select box. If this is false (the
  95 default), then only a single option can be selected. If this
  96 is true, then multiple options can be selected by the
  97 user.</td></table>
  98
  99 <table width="100%" border=0 rules="none" frame="void"
 100        cols="2" cellspacing="0" cellpadding="0">
 101 <tr valign="top" align="left">
 102 <td width="10%"></td><td width="90%">
 103 To add options to the select box, use the
 104 <b>ml_form_select_push_back</b> and other access functions.
 105 These are modelled on the c2lib <b>vector_*</b>
 106 functions.</td></table>
 107
 108 <table width="100%" border=0 rules="none" frame="void"
 109        cols="2" cellspacing="0" cellpadding="0">
 110 <tr valign="top" align="left">
 111 <td width="10%"></td><td width="90%">
 112 To choose which option is selected first in a single
 113 selection select box, call
 114 <b>ml_form_select_set_selection</b>. For select boxes which
 115 allow multiple selections, prepare a <b>vector</b> of
 116 <b>int</b> which is at least as long as the number of
 117 options. Each element of the vector should be a boolean
 118 value saying whether the corresponding option is selected or
 119 not. Pass this to
 120 <b>ml_form_select_set_selections</b>.</td></table>
 121
 122 <table width="100%" border=0 rules="none" frame="void"
 123        cols="2" cellspacing="0" cellpadding="0">
 124 <tr valign="top" align="left">
 125 <td width="10%"></td><td width="90%">
 126 If the select box allows only single selections, then after
 127 the form has been submitted by the user, you can read back
 128 the index of the option which was selected using
 129 <b>ml_form_select_get_selection</b>. This returns -1 if
 130 nothing was selected.</td></table>
 131
 132 <table width="100%" border=0 rules="none" frame="void"
 133        cols="2" cellspacing="0" cellpadding="0">
 134 <tr valign="top" align="left">
 135 <td width="10%"></td><td width="90%">
 136 If the select box allows multiple selections, then call
 137 <b>ml_form_select_get_selections</b> which returns a vector
 138 of boolean values (<b>vector</b> of <b>int</b>) of exactly
 139 the same length as the number of options. This vector will
 140 contain true corresponding to every selected option. This
 141 function may also return <b>NULL</b>, indicating that
 142 nothing was selected (or the form wasn't
 143 submitted).</td></table>
 144 <a name="AUTHOR"></a>
 145 <h2>AUTHOR</h2>
 146
 147 <table width="100%" border=0 rules="none" frame="void"
 148        cols="2" cellspacing="0" cellpadding="0">
 149 <tr valign="top" align="left">
 150 <td width="10%"></td><td width="90%">
 151 Richard Jones &lt;rich@annexia.org&gt;</td></table>
 152 <a name="LICENSE"></a>
 153 <h2>LICENSE</h2>
 154
 155 <table width="100%" border=0 rules="none" frame="void"
 156        cols="2" cellspacing="0" cellpadding="0">
 157 <tr valign="top" align="left">
 158 <td width="10%"></td><td width="90%">
 159 GNU LGPL (see http://www.gnu.org/)</td></table>
 160 <a name="VERSION"></a>
 161 <h2>VERSION</h2>
 162
 163 <table width="100%" border=0 rules="none" frame="void"
 164        cols="2" cellspacing="0" cellpadding="0">
 165 <tr valign="top" align="left">
 166 <td width="10%"></td><td width="90%">
 167 monolith-1.0.0</td></table>
 168 <a name="SEE ALSO"></a>
 169 <h2>SEE ALSO</h2>
 170
 171 <table width="100%" border=0 rules="none" frame="void"
 172        cols="2" cellspacing="0" cellpadding="0">
 173 <tr valign="top" align="left">
 174 <td width="10%"></td><td width="90%">
 175 <b>new_ml_form(3)</b>, <b>ml_form_input_get_value(3)</b>,
 176 <b>vector_push_back(3)</b>, <b>vector_pop_back(3)</b>,
 177 <b>vector_push_front(3)</b>, <b>vector_pop_front(3)</b>,
 178 <b>vector_get(3)</b>, <b>vector_insert(3)</b>,
 179 <b>vector_replace(3)</b>, <b>vector_erase(3)</b>,
 180 <b>vector_clear(3)</b>, <b>vector_size(3)</b>.</td></table>
 181 <hr>
 182 </body>
 183 </html>