src/ml_form.h

   1 /* Monolith form class.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *
  18  * $Id: ml_form.h,v 1.5 2002/11/23 16:46:05 rich Exp $
  19  */
  20
  21 #ifndef ML_FORM_H
  22 #define ML_FORM_H
  23
  24 #include "monolith.h"
  25 #include "ml_form_input.h"
  26
  27 struct ml_form;
  28 typedef struct ml_form *ml_form;
  29
  30 /* Function: new_ml_form - monolith form widget
  31  * Function: ml_form_set_callback
  32  * Function: ml_form_pack
  33  *
  34  * A monolith form widget is a low-level widget for handling input of
  35  * text fields, check buttons, radio buttons and so on, collected together
  36  * into a single form on a page.
  37  *
  38  * A form should contain a mixture of input widgets and ordinary widgets.
  39  * Since the form widget itself can only be packed with a single widget,
  40  * normally you would pack a layout widget directly into the form, and
  41  * then a mixture of labels and input widgets into the layout widget.
  42  *
  43  * One or more of the widgets packed into the form can be a submit
  44  * button (see @ref{new_ml_form_submit(3)}). Pressing on the submit
  45  * button causes the form's callback function to be called, and in this
  46  * function the values entered into the other input widgets can be
  47  * read. It is recommended that all forms contain at least one submit
  48  * button, because the effect of creating a form with no submit buttons
  49  * is browser-dependent, and can mean that the form cannot be submitted.
  50  *
  51  * Forms cannot be nested (a form widget cannot contain another form
  52  * widget inside itself). This is a limitation of HTML.
  53  *
  54  * Forms are low-level entities. To do seriously interesting things with
  55  * forms such as self-validation, use one of the higher-level form-type
  56  * abstractions that monolith provides (XXX will provide, not now - RWMJ).
  57  *
  58  * @code{new_ml_form} creates a new form widget.
  59  *
  60  * @code{ml_form_set_callback} sets the callback function which is
  61  * called when the form is submitted. The callback function is invoked
  62  * as @code{void callback_fn (ml_session session, void *data)}. The
  63  * values that the user entered in the input fields are available
  64  * by calling (for example) @ref{ml_form_input_get_value(3)} on each
  65  * input widget within the form.
  66  *
  67  * @code{ml_form_pack} packs a widget into the form. A form can only
  68  * store a single widget, so if you call pack subsequent times, the
  69  * earlier widgets are forgotten.
  70  *
  71  * The following properties can be changed on forms (see
  72  * @ref{ml_widget_set_property(3)}):
  73  *
  74  * @code{method}: This is an esoteric property that you will
  75  * probably never need to use. It changes the behaviour of the
  76  * HTML form to use either @code{"GET"} or @code{"POST"} - the
  77  * default being @code{"POST"}.
  78  *
  79  * @code{form.name}: A read-only property containing the name of
  80  * the form. It is unlikely that you will ever need to know this.
  81  *
  82  * See also: @ref{new_ml_form_input(3)}, @ref{new_ml_form_textarea(3)},
  83  * @ref{new_ml_form_submit(3)}.
  84  */
  85 extern ml_form new_ml_form (pool pool);
  86 extern void ml_form_set_callback (ml_form, void (*callback_fn) (ml_session, void *), ml_session session, void *data);
  87 extern void ml_form_pack (ml_form, ml_widget);
  88
  89 /* Form input widgets must call this function during their 'new' phase
  90  * to register themselves with the form. The function returns a unique
  91  * name for the form input field.
  92  */
  93 extern const char *_ml_form_register_widget (ml_form f, ml_form_input w);
  94
  95 #endif /* ML_FORM_H */