src/ml_button.h

   1 /* Monolith 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_button.h,v 1.6 2002/11/08 23:19:14 rich Exp $
  19  */
  20
  21 #ifndef ML_BUTTON_H
  22 #define ML_BUTTON_H
  23
  24 #include "monolith.h"
  25
  26 struct ml_button;
  27 typedef struct ml_button *ml_button;
  28
  29 /* Function: new_ml_button - monolith button widget
  30  * Function: ml_button_set_callback
  31  * Function: ml_button_set_popup
  32  * Function: ml_button_set_popup_size
  33  *
  34  * A button widget is a simple button which calls a function when clicked.
  35  *
  36  * @code{new_ml_button} creates a new button widget.
  37  *
  38  * The following properties can be changed on buttons (see
  39  * @ref{ml_widget_set_property(3)}):
  40  *
  41  * @code{text}: The text on the button. The string must have a
  42  * lifetime as long as or longer than the button's pool.  Setting this
  43  * to @code{NULL} has the same effect as setting it to the empty
  44  * string, which is to say not very useful because the button cannot
  45  * be pressed.
  46  *
  47  * @code{title}: If not @code{NULL}, then this string will be
  48  * displayed as a tool tip (bubble) when the mouse is held over the
  49  * button. Note that this sort of information hiding rarely scores
  50  * highly in usability tests, so you should make sure important
  51  * information is always visible in the interface.
  52  *
  53  * @code{button.style}: The style may be: @code{NULL} or @code{"default"}
  54  * meaning the default look and feel; @code{"key"} meaning that the
  55  * button has a fixed width of @code{1em}, resulting in a more
  56  * pleasing effect for calculator key buttons; @code{"compact"}
  57  * meaning a compact @code{[text]} look; @code{"link"} meaning that
  58  * the button will look like a hyperlink.
  59  *
  60  * @code{color}: The button's color property.
  61  *
  62  * @code{class}: The stylesheet class.
  63  *
  64  * @code{ml_button_set_callback} updates the callback
  65  * function which is invoked when the button is pressed.
  66  *
  67  * @code{ml_button_set_popup} sets the popup property of the
  68  * button. When the user clicks on a popup button, a new popup
  69  * window opens on the screen. To make a button into a popup
  70  * button, the popup property should be a non-@code{NULL} string
  71  * which is the name of the new browser window (note that because
  72  * of limitations in HTML, browser window names are global, so
  73  * it is recommended that names be "@code{appname}_@code{name}").
  74  * To change a popup button back to an ordinary button, set the
  75  * popup property to @code{NULL}.
  76  *
  77  * The callback used by a popup button must create a top-level
  78  * window, otherwise you will get an internal server error.
  79  *
  80  * @code{ml_button_set_popup_size} changes the size of the popup
  81  * window. The default is width 0, height 0, which usually creates a
  82  * popup window which is the same size and shape as the current
  83  * browser window.
  84  */
  85 extern ml_button new_ml_button (pool pool, const char *text);
  86 extern void ml_button_set_callback (ml_button, void (*fn)(ml_session, void *), ml_session, void *);
  87 extern void ml_button_set_popup (ml_button, const char *name);
  88 extern void ml_button_set_popup_size (ml_button, int width, int height);
  89
  90 #endif /* ML_BUTTON_H */