1 /* Monolith form select box input class.
2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: ml_form_select.h,v 1.3 2002/11/02 18:53:47 rich Exp $
21 #ifndef ML_FORM_SELECT_H
22 #define ML_FORM_SELECT_H
27 struct ml_form_select;
28 typedef struct ml_form_select *ml_form_select;
30 /* Function: new_ml_form_select - monolith form select box input widget
31 * Function: ml_form_select_push_back
32 * Function: ml_form_select_pop_back
33 * Function: ml_form_select_push_front
34 * Function: ml_form_select_pop_front
35 * Function: ml_form_select_get
36 * Function: ml_form_select_insert
37 * Function: ml_form_select_replace
38 * Function: ml_form_select_erase
39 * Function: ml_form_select_clear
40 * Function: ml_form_select_size
41 * Function: ml_form_select_set_selection
42 * Function: ml_form_select_set_selections
43 * Function: ml_form_select_get_selection
44 * Function: ml_form_select_get_selections
46 * This is a select box for use in forms. It can appear in several
47 * ways: either as a drop-down menu, or as a selection box allowing
48 * single or multiple options to be selected.
50 * @code{new_ml_form_select} creates a new form select box input widget. The
51 * form into which this widget is being embedded is passed as the
52 * @code{form} parameter. The select box is created with no options,
53 * in drop-down mode (size 0), single choice (multiple 0).
55 * The following properties can be changed on form select box input widgets
56 * (see @ref{ml_widget_set_property(3)}):
58 * @code{form.select.size}: The size (number of rows)
59 * in the select box. If the size is 0, then the select box will be
60 * rendered as a drop-down menu. If the size is > 0, then the select
61 * box will be rendered as a scrolling list of choices.
63 * @code{form.select.multiple} (boolean): The multiple boolean
64 * property of the select box. If this is false (the default), then
65 * only a single option can be selected. If this is true, then multiple
66 * options can be selected by the user.
68 * To add options to the select box, use the @code{ml_form_select_push_back}
69 * and other access functions. These are modelled on the c2lib @code{vector_*}
72 * To choose which option is selected first in a single selection select
73 * box, call @code{ml_form_select_set_selection}. For select boxes which
74 * allow multiple selections, prepare a @code{vector} of @code{int} which
75 * is at least as long as the number of options. Each element of the
76 * vector should be a boolean value saying whether the corresponding
77 * option is selected or not. Pass this to
78 * @code{ml_form_select_set_selections}.
80 * If the select box allows only single selections, then after the form
81 * has been submitted by the user, you can read back the index of the
82 * option which was selected using @code{ml_form_select_get_selection}.
83 * This returns -1 if nothing was selected.
85 * If the select box allows multiple selections, then call
86 * @code{ml_form_select_get_selections} which returns a vector
87 * of boolean values (@code{vector} of @code{int}) of exactly
88 * the same length as the number of options. This vector will
89 * contain true corresponding to every selected option. This
90 * function may also return @code{NULL}, indicating that
91 * nothing was selected (or the form wasn't submitted).
93 * See also: @ref{new_ml_form(3)}, @ref{ml_form_input_get_value(3)},
94 * @ref{vector_push_back(3)}, @ref{vector_pop_back(3)},
95 * @ref{vector_push_front(3)}, @ref{vector_pop_front(3)},
96 * @ref{vector_get(3)}, @ref{vector_insert(3)}, @ref{vector_replace(3)},
97 * @ref{vector_erase(3)}, @ref{vector_clear(3)}, @ref{vector_size(3)}.
99 extern ml_form_select new_ml_form_select (pool pool, ml_form form);
100 extern void ml_form_select_push_back (ml_form_select w, const char *option);
101 extern const char *ml_form_select_pop_back (ml_form_select w);
102 extern void ml_form_select_push_front (ml_form_select w, const char *option);
103 extern const char *ml_form_select_pop_front (ml_form_select w);
104 extern const char *ml_form_select_get (ml_form_select w, int option_index);
105 extern void ml_form_select_insert (ml_form_select w, int option_index, const char *option);
106 extern void ml_form_select_replace (ml_form_select w, int option_index, const char *option);
107 extern void ml_form_select_erase (ml_form_select w, int option_index);
108 extern void ml_form_select_clear (ml_form_select w);
109 extern int ml_form_select_size (ml_form_select w);
110 extern void ml_form_select_set_selection (ml_form_select w, int option_index);
111 extern void ml_form_select_set_selections (ml_form_select w, vector selected);
112 extern int ml_form_select_get_selection (ml_form_select w);
113 extern const vector ml_form_select_get_selections (ml_form_select w);
115 #endif /* ML_FORM_SELECT_H */