src/ml_toggle_button.h

   1 /* Monolith toggle button 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_toggle_button.h,v 1.2 2002/10/30 21:03:04 rich Exp $
  19  */
  20
  21 #ifndef ML_TOGGLE_BUTTON_H
  22 #define ML_TOGGLE_BUTTON_H
  23
  24 #include "monolith.h"
  25
  26 struct ml_toggle_button;
  27 typedef struct ml_toggle_button *ml_toggle_button;
  28
  29 /* Function: new_ml_toggle_button - monolith toggle button widget
  30  * Function: ml_toggle_button_set_state
  31  * Function: ml_toggle_button_get_state
  32  * Function: ml_toggle_button_set_callback
  33  *
  34  * A toggle button widget is similar to an ordinary button
  35  * (see @ref{new_ml_button(3)}) except that it has two states,
  36  * 0 and non-zero (out, or pushed in respectively). You can
  37  * query or set the current state of the toggle button, and
  38  * you can arrange for a callback function to be called when
  39  * the state changes.
  40  *
  41  * Note that toggle buttons cannot be used as part of forms.
  42  * Use an @code{ml_form_checkbox} instead.
  43  *
  44  * @code{new_ml_toggle_button} creates a new toggle button widget.
  45  *
  46  * The following properties can be changed on toggle buttons (see
  47  * @ref{ml_widget_set_property(3)}):
  48  *
  49  * @code{text}: The HTML text printed
  50  * on the button. Note that the text string must be either
  51  * static, or already allocated in the button's pool, or allocated
  52  * in a pool with a longer lifetime than the button. If the text
  53  * is set to @code{NULL} then this has the same effect as setting
  54  * the text to the empty string, which is not very useful because
  55  * the button can never be pressed.
  56  *
  57  * @code{button.key} (boolean): The "key" property of
  58  * the button. This should be set on buttons where the text is
  59  * a single letter, suitable for, say, calculator keys. All key
  60  * buttons are rendered at a fixed width of "1em", resulting in
  61  * a more pleasing overall effect.
  62  *
  63  * @code{ml_toggle_button_(set|get)_state} updates or queries the
  64  * current state of the button. The state is either 0 (the default)
  65  * meaning the button is out, or non-zero meaning the button is
  66  * pushed in.
  67  *
  68  * @code{ml_toggle_button_set_callback} updates the callback
  69  * function which is invoked when the button changes state
  70  * (either from "out" to "in", or from "in" to "out"). Use
  71  * @code{ml_toggle_button_get_state} to find the new state.
  72  */
  73 extern ml_toggle_button new_ml_toggle_button (pool pool, ml_session, const char *text);
  74 extern void ml_toggle_button_set_state (ml_toggle_button, int state);
  75 extern int ml_toggle_button_get_state (ml_toggle_button);
  76 extern void ml_toggle_button_set_callback (ml_toggle_button, void (*fn)(ml_session, void *), ml_session, void *);
  77
  78 #endif /* ML_TOGGLE_BUTTON_H */