new_ml_form_select

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
LICENSE
VERSION
SEE ALSO

NAME

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

SYNOPSIS

#include <ml_form_select.h>

ml_form_select new_ml_form_select (pool pool, ml_form form);
void ml_form_select_set_size (ml_form_select w, int size);
int ml_form_select_get_size (ml_form_select w);
void ml_form_select_set_multiple (ml_form_select w, int multiple);
int ml_form_select_get_multiple (ml_form_select w);
void ml_form_select_push_back (ml_form_select w, const char *option);
const char *ml_form_select_pop_back (ml_form_select w);
void ml_form_select_push_front (ml_form_select w, const char *option);
const char *ml_form_select_pop_front (ml_form_select w);
const char *ml_form_select_get (ml_form_select w, int option_index);
void ml_form_select_insert (ml_form_select w, int option_index, const char *option);
void ml_form_select_replace (ml_form_select w, int option_index, const char *option);
void ml_form_select_erase (ml_form_select w, int option_index);
void ml_form_select_clear (ml_form_select w);
int ml_form_select_size (ml_form_select w);
void ml_form_select_set_selection (ml_form_select w, int option_index);
void ml_form_select_set_selections (ml_form_select w, vector selected);
int ml_form_select_get_selection (ml_form_select w);
const vector ml_form_select_get_selections (ml_form_select w);

DESCRIPTION

This is a select box for use in forms. It can appear in several ways: either as a drop-down menu, or as a selection box allowing single or multiple options to be selected.

new_ml_form_select creates a new form select box input widget. The form into which this widget is being embedded is passed as the form parameter. The select box is created with no options, in drop-down mode (size 0), single choice (multiple 0).

ml_form_select_(set|get)_size sets the size (number of rows) in the select box. If the size is 0, then the select box will be rendered as a drop-down menu. If the size is > 0, then the select box will be rendered as a scrolling list of choices.

ml_form_select_(set|get)_multiple sets the multiple boolean property of the select box. If this is false (the default), then only a single option can be selected. If this is true, then multiple options can be selected by the user.

To add options to the select box, use the ml_form_select_push_back and other access functions. These are modelled on the c2lib vector_* functions.

To choose which option is selected first in a single selection select box, call ml_form_select_set_selection. For select boxes which allow multiple selections, prepare a vector of int which is at least as long as the number of options. Each element of the vector should be a boolean value saying whether the corresponding option is selected or not. Pass this to ml_form_select_set_selections.

If the select box allows only single selections, then after the form has been submitted by the user, you can read back the index of the option which was selected using ml_form_select_get_selection. This returns -1 if nothing was selected.

If the select box allows multiple selections, then call ml_form_select_get_selections which returns a vector of boolean values (vector of int) of exactly the same length as the number of options. This vector will contain true corresponding to every selected option. This function may also return NULL, indicating that nothing was selected (or the form wasn't submitted).

AUTHOR

Richard Jones <rich@annexia.org>

LICENSE

GNU LGPL (see http://www.gnu.org/)

VERSION

monolith-1.0.0