src/ml_widget.h

   1 /* Monolith widget 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_widget.h,v 1.8 2002/11/29 10:43:03 rich Exp $
  19  */
  20
  21 #ifndef ML_WIDGET_H
  22 #define ML_WIDGET_H
  23
  24 #include <stdarg.h>
  25
  26 #include <pthr_iolib.h>
  27
  28 struct ml_session;
  29
  30 /* Best to treat widgets as opaque, except in ml_widget.c itself where
  31  * we know that they in fact contain a pointer to the list of widget
  32  * operations.
  33  */
  34 typedef void *ml_widget;
  35
  36 /* Widget property. */
  37 struct ml_widget_property
  38 {
  39   const char *name;             /* Name of the property. */
  40   int offset;                   /* Offset into widget structure. */
  41   int type;                     /* Property type. */
  42 #define ML_PROP_STRING    1
  43 #define ML_PROP_INT       2
  44 #define ML_PROP_BOOL      ML_PROP_INT
  45 #define ML_PROP_CHAR      3
  46 #define ML_PROP_WIDGET    4
  47   void (*on_set) (ml_widget w); /* Called after property is set. */
  48   void (*on_get) (ml_widget w); /* Called before property is got. */
  49   int flags;                    /* Flags. */
  50 #define ML_PROP_READ_ONLY  1
  51 #define ML_PROP_WRITE_ONLY 2
  52 };
  53
  54 /* A pointer to this struct must occupy the first slot in every
  55  * widget-type structure we define elsewhere.
  56  */
  57 struct ml_widget_operations
  58 {
  59   /* All widgets must have a repaint function. */
  60   void (*repaint) (void *widget, struct ml_session *session,
  61                    const char *windowid, io_handle io);
  62
  63   /* List of properties (NULL = no properties). */
  64   struct ml_widget_property *properties;
  65 };
  66
  67 /* Function: ml_widget_repaint - Operations on generic monolith widgets.
  68  * Function: ml_widget_get_properties
  69  * Function: ml_widget_set_property
  70  * Function: ml_widget_get_property
  71  * Function: _ml_widget_get_property
  72  *
  73  * @code{ml_widget_repaint} calls the repaint function on a generic
  74  * widget.
  75  *
  76  * The @code{*property} functions are concerned with widget properties.
  77  * Properties are generic attributes of a widget which can be read and
  78  * updated using @code{ml_widget_set_property} and
  79  * @code{ml_widget_get_property}.
  80  *
  81  * @code{ml_widget_get_properties} returns a list of the properties
  82  * available to be changed in the current widget. The list returned
  83  * can be @code{NULL} meaning that this widget does not support
  84  * properties. @code{struct ml_widget_property} is defined in
  85  * @code{<ml_widget.h>}.
  86  *
  87  * Properties have consistent names. These are some of the property
  88  * names defined so far:
  89  *
  90  * @code{button.style}: For buttons, sets the style of the button,
  91  * either @code{"default"}, @code{"key"}, @code{"compact"} or
  92  * @code{"link"}.
  93  *
  94  * @code{class}: Many widgets support this. It sets or overrides the
  95  * class of the top-level HTML element. You can use this, in conjunction
  96  * with a stylesheet, to dramatically change the look and feel of a
  97  * particular widget. In fact, this is the recommended method for changing
  98  * the style for all widgets except text labels.
  99  *
 100  * @code{color}: The color style (text color).
 101  *
 102  * @code{font.size}: Font size for text displayed on a label or
 103  * button. Common sizes are @code{"small"}, @code{"medium"} or
 104  * @code{"large"}.
 105  *
 106  * @code{font.weight}: Font weight for text displayed on a label or
 107  * button. Common weights are @code{"normal"} and @code{"bold"}.
 108  *
 109  * @code{form.select.size}: On form select input boxes, the numbers of
 110  * rows.
 111  *
 112  * @code{form.select.multiple}: On form select input boxes, whether
 113  * the input is single- or multiple-select.
 114  *
 115  * @code{image}: On images, the path to the image.
 116  *
 117  * @code{text}: The text displayed on a label or button.
 118  *
 119  * @code{text.align}: Alignment of text displayed on a label or
 120  * button. Possible values are: @code{"left"}, @code{"right"},
 121  * @code{"justify"}.
 122  *
 123  * @code{title}: Many widgets support this to give the widget a
 124  * title or "tooltip".
 125  *
 126  */
 127 extern void ml_widget_repaint (ml_widget widget, struct ml_session *, const char *windowid, io_handle);
 128 extern const struct ml_widget_property *ml_widget_get_properties (ml_widget widget);
 129 extern void ml_widget_set_property (ml_widget widget, const char *property_name, ...);
 130 #define ml_widget_get_property(widget,property_name,var) (_ml_widget_get_property ((widget), (property_name), &(var)))
 131 extern void _ml_widget_get_property (ml_widget widget, const char *property_name, void *varptr);
 132
 133 #endif /* ML_WIDGET_H */