server/menuitem.h

   1 /*
   2  * menuitem.h
   3  * This file is part of LCDd, the lcdproc server.
   4  *
   5  * This file is released under the GNU General Public License. Refer to the
   6  * COPYING file distributed with this package.
   7  *
   8  * Copyright (c) 1999, William Ferrell, Scott Scriven
   9  *               2004, F5 Networks, Inc. - IP-address input
  10  *               2005, Peter Marschall - error checks, ...
  11  *
  12  * Defines all the menuitem data and actions.
  13  *
  14  * There are a few different menuitems:
  15  * - action
  16  * - checkbox (on/off and optionally open)
  17  * - slider (the user can increase/decrease a value)
  18  * - numeric input
  19  * - alphanumeric input (in short: alpha)
  20  * - menu (a menu is a menuitem itself too)
  21  *
  22  * The slider, numeric & string input and menu have their own screen,
  23  * that comes to front when the items are selected.
  24  * One menuitem is in a different file: Menu data is in menu,h.
  25  */
  26
  27 #ifndef MENUITEM_H
  28 #define MENUITEM_H
  29
  30 #include "shared/LL.h"
  31
  32 #ifndef bool
  33 # define bool short
  34 # define true 1
  35 # define false 0
  36 #endif
  37
  38 #define max(a,b) (((a) > (b)) ? (a) : (b))
  39
  40 /*********************************************************************
  41  * Data definitions of the menustuff
  42  */
  43
  44 /** These values are used in the function tables in menuitem.c ! */
  45 typedef enum MenuItemType {
  46         MENUITEM_MENU = 0,
  47         MENUITEM_ACTION = 1,
  48         MENUITEM_CHECKBOX = 2,
  49         MENUITEM_RING = 3,
  50         MENUITEM_SLIDER = 4,
  51         MENUITEM_NUMERIC = 5,
  52         MENUITEM_ALPHA = 6,
  53         MENUITEM_IP = 7,
  54         NUM_ITEMTYPES = 8
  55 } MenuItemType;
  56
  57 typedef enum CheckboxValue {
  58         CHECKBOX_OFF = 0, CHECKBOX_ON, CHECKBOX_GRAY
  59 } CheckboxValue;
  60
  61 /** Recognized input token codes */
  62 typedef enum MenuToken {
  63         MENUTOKEN_MENU,
  64         MENUTOKEN_ENTER,
  65         MENUTOKEN_UP,
  66         MENUTOKEN_DOWN,
  67         MENUTOKEN_LEFT,
  68         MENUTOKEN_RIGHT,
  69         MENUTOKEN_OTHER
  70 } MenuToken;
  71
  72 /** Return codes from an input handler */
  73 typedef enum MenuResult {
  74         MENURESULT_ERROR = -1,  /**< Something has gone wrong */
  75         MENURESULT_NONE = 0,    /**< Token handled OK, no extra action */
  76         MENURESULT_ENTER,       /**< Token handled OK, enter the selected
  77                                  * menuitem now */
  78         MENURESULT_CLOSE,       /**< Token handled OK, close the current
  79                                  * menuitem now */
  80         MENURESULT_QUIT,        /**< Token handled OK, close ALL menus now */
  81         MENURESULT_PREDECESSOR, /**< Token handled OK, goto registered
  82                                  * predecessor */
  83         MENURESULT_SUCCESSOR    /**< Token handled OK, goto registered
  84                                  * successor */
  85 } MenuResult;
  86
  87 /** Events caused by a menuitem */
  88 typedef enum MenuEventType {
  89         MENUEVENT_SELECT = 0,   /**< Item has been selected
  90                                 (action chosen) */
  91         MENUEVENT_UPDATE = 1,   /**< Item has been modified
  92                                 (checkbox, numeric, alphanumeric) */
  93         MENUEVENT_PLUS = 2,     /**< Item has been modified in positive direction
  94                                  (slider moved) */
  95         MENUEVENT_MINUS = 3,    /**< Item has been modified in negative direction
  96                                 (slider moved) */
  97         MENUEVENT_ENTER = 4,    /**< Menu has been entered */
  98         MENUEVENT_LEAVE = 5,    /**< Menu has been left */
  99         NUM_EVENTTYPES = 6
 100 } MenuEventType;
 101
 102 #define MenuEventFunc(f) int (f) (struct MenuItem *item, MenuEventType event)
 103
 104 /** I've used a union in the struct below. Why? And why not for Widget?
 105  *
 106  * There are different types of menuitems. There are also types of widgets.
 107  * Menuitems have, just like widgets, different datafields per subtype.
 108  * The difference is that menuitems have, unlike widgets _many__different_
 109  * attributes. Widgets share many attributes like x, y, text.
 110  * The code would become unreadable if we used the 'widget way', or it would
 111  * get large if we define datafields that we use for only one type of
 112  * menuitem. (Joris)
 113  */
 114 typedef struct MenuItem {
 115         MenuItemType type;      /**< Type as defined above */
 116         char *id;               /**< Internal name for client supplied menus */
 117         char *successor_id;     /**< next menuitem after hitting "Enter" on
 118                                  * this one. (Special values are "_quit_",
 119                                  * "_close_", "_none_"). */
 120         char *predecessor_id;   /**< next menuitem after hitting "Escape" on
 121                                  * this one. (Special values are "_quit_",
 122                                  * "_close_", "_none_"). */
 123         struct MenuItem *parent; /**< Parent of this menuitem */
 124         MenuEventFunc (*event_func);
 125                         /**< Defines event_func to be an event function */
 126         char *text;     /**< Visible name of the item */
 127         void* client;   /**< The owner of this menuitem. */
 128         bool is_hidden; /**< If the item currently should not appear in a menu. */
 129         union data {
 130                 struct menu {
 131                         int selector_pos;       /**< At what menuitem is the
 132                                                    selector (0 for first) */
 133                         int scroll;             /**< How much has the menu been
 134                                                    scrolled down */
 135                         void *association;      /**< To associate an object
 136                                                    with this menu */
 137                         LinkedList *contents;   /**< What's in this menu */
 138                 } menu;
 139                 struct action {
 140                         /* nothing */
 141                 } action;
 142                 struct checkbox {
 143                         bool allow_gray;        /**< Is CHECKBOX_GRAY allowed ? */
 144                         CheckboxValue value;    /**< Current value */
 145                 } checkbox;
 146                 struct ring {
 147                         LinkedList *strings;    /**< The selectable strings */
 148                         short value;            /**< Current index */
 149                 } ring;
 150                 struct slider {
 151                         char *mintext;          /**< Text at minimal value */
 152                         char *maxtext;          /**< Text at minimal value */
 153                         int minvalue;
 154                         int maxvalue;
 155                         int stepsize;
 156                         int value;              /**< Current value */
 157                 } slider;
 158                 struct numeric {
 159                         int maxvalue;
 160                         int minvalue;
 161                         //short allowed_decimals; /**< Number of numbers behind dot */
 162                         int value;              /**< Current value */
 163                         char *edit_str;         /**< Value while being edited */
 164                         short edit_pos;         /**< Position while editing */
 165                         short edit_offs;        /**< Offset while editing */
 166                         short error_code;
 167                 } numeric;
 168                 struct alpha {
 169                         char password_char;     /**< For passwords */
 170                         short minlength;
 171                         short maxlength;
 172                         bool allow_caps;        /**< Caps allowed ? */
 173                         bool allow_noncaps;     /**< Non-caps allowed ? */
 174                         bool allow_numbers;     /**< Numbers allowed ? */
 175                         char *allowed_extra;    /**< Allowed extra characters */
 176                         char *value;            /**< Current value */
 177                         char *edit_str;         /**< Value while being edited */
 178                         short edit_pos;         /**< Position while editing */
 179                         short edit_offs;        /**< Offset while editing */
 180                         short error_code;
 181                 } alpha;
 182                 struct ip {
 183                         char *value;            /**< Current value */
 184                         char *edit_str;         /**< Value while being edited */
 185                         short maxlength;
 186                         bool v6;                /**< true if editing ipv6 addr */
 187                         short edit_pos;         /**< Position while editing */
 188                         short edit_offs;        /**< Offset while editing */
 189                         short error_code;
 190                 } ip;
 191         } data;
 192 } MenuItem;
 193
 194
 195 #include "screen.h"
 196
 197 /*********************************************************************
 198  * Functions to use the menustuff
 199  */
 200
 201 /** translates a predecessor_id into a MenuResult. */
 202 MenuResult menuitem_predecessor2menuresult(char *predecessor_id, MenuResult default_result);
 203
 204 /** translates a successor_id into a MenuResult. */
 205 MenuResult menuitem_successor2menuresult(char *successor_id, MenuResult default_result);
 206
 207 MenuItem *menuitem_search(char *menu_id, Client *client);
 208
 209 /** YOU SHOULD NOT CALL THIS FUNCTION BUT THE TYPE SPECIFIC ONE INSTEAD */
 210 MenuItem *menuitem_create(MenuItemType type, char *id,
 211                 MenuEventFunc(*event_func), char *text, Client *client);
 212
 213 /* For all constructor functions below the following:
 214  *
 215  * id:          internal name of the item. Never visible. String will be
 216  *              copied.
 217  * event_func:  the event function that should be called upon actions on this
 218  *              item.
 219  * text:        the displayed text.
 220  *
 221  * All strings will be copied !
 222  *
 223  * Return value: the new item, or NULL on error.
 224  *
 225  * To create a Menu (which is also an ItemType), call menu_create.
 226  *
 227  */
 228
 229 /** Creates a an action item (a string only).  Generated events:
 230  * MENUEVENT_SELECT when user selects the item.
 231  */
 232 MenuItem *menuitem_create_action(char *id, MenuEventFunc(*event_func),
 233         char *text, Client *client, MenuResult menu_result);
 234
 235 /** Creates a checkbox.
 236  * Generated events: MENUEVENT_UPDATE when user changes value (immediately).
 237  */
 238 MenuItem *menuitem_create_checkbox(char *id, MenuEventFunc(*event_func),
 239         char *text, Client *client, bool allow_gray, bool value);
 240
 241 /** Creates a ring with the given string, separated by tabs.
 242  * value is the (initial) index in the strings.
 243  * eg: if strings="abc\\tdef" the value=1 means that "def" is selected.
 244  * Generated events: MENUEVENT_UPDATE when user changes value (immediately).
 245  */
 246 MenuItem *menuitem_create_ring(char *id, MenuEventFunc(*event_func),
 247         char *text, Client *client, char *strings, short value);
 248
 249 /** Creates a slider with the given min and max values.
 250  * If the display is big enough the mintext and maxtext will be placed
 251  * at the end positions of the slider.
 252  * You can set the step size. Make it 0 to disable the automatic value chaning,
 253  * and update the value yourself.
 254  * MENUEVENT_PLUS, MENUEVENT_MINUS when slider is moved (immediately).
 255  */
 256 MenuItem *menuitem_create_slider(char *id, MenuEventFunc(*event_func),
 257         char *text, Client *client, char *mintext, char *maxtext,
 258         int minvalue, int maxvalue, int stepsize, int value);
 259
 260 /** Creates a numeric value box.
 261  * Value can range from minvalue to maxvalue.
 262  * MENUEVENT_UPDATE when user finishes the value (no immediate update).
 263  */
 264 MenuItem *menuitem_create_numeric(char *id, MenuEventFunc(*event_func),
 265         char *text, Client *client, int minvalue, int maxvalue, int value);
 266
 267 /** Creates a string value box.
 268  * Value should have given minimal and maximal length. You can set whether
 269  * caps, non-caps and numbers are allowed. Also you can alow other characters.
 270  * If password char is non-zero, you will only see this char, not the actual
 271  * input.
 272  * MENUEVENT_UPDATE when user finishes the value (no immediate update).
 273  */
 274 MenuItem *menuitem_create_alpha(char *id, MenuEventFunc(*event_func),
 275         char *text, Client *client, char password_char, short minlength, short maxlength,
 276         bool allow_caps, bool allow_noncaps, bool allow_numbers,
 277         char *allowed_extra, char *value);
 278
 279 /** Creates an ip value box.  can be either v4 or v6
 280  * MENUEVENT_UPDATE when user finishes the value (no immediate update).
 281  */
 282 MenuItem *menuitem_create_ip(char *id, MenuEventFunc(*event_func),
 283         char *text, Client *client, bool v6, char *value);
 284
 285 /** Deletes item from memory.
 286  * All allocated extra data (like strings) will be freed.
 287  */
 288 void menuitem_destroy(MenuItem *item);
 289
 290 /** Resets the item to the initial state.
 291  * You should call menuitem_update after this to see the effects.
 292  * This call is useless on items that have immediate effect, like a slider.
 293  * Those items do not keep temporary data.
 294  */
 295 void menuitem_reset(MenuItem *item);
 296
 297 /** (Re)builds the selected menuitem on screen using widgets.
 298  * Should be re-called if menuitem data has been changed.
 299  * There are a few (logical) exceptions to this:
 300  * - the values
 301  * - the menu scroll and menu index
 302  */
 303 void menuitem_rebuild_screen(MenuItem *item, Screen *s);
 304
 305 /** Updates the widgets of the selected menuitem
 306  * Fills all widget attributes with the corrrect values.
 307  */
 308 void menuitem_update_screen(MenuItem *item, Screen *s);
 309
 310 /** Does something with the given input.
 311  * key is only used if token is MENUTOKEN_OTHER.
 312  */
 313 MenuResult menuitem_process_input(MenuItem *item, MenuToken token, const char *key, bool extended);
 314
 315 /** returns the Client that owns the MenuItem. item must not be null */
 316 Client *menuitem_get_client(MenuItem *item);
 317
 318 /** Converts a tab-separated list to a LinkedList. */
 319 LinkedList *tablist2linkedlist(char *strings);
 320
 321 MenuItemType menuitem_typename_to_type(char *name);
 322
 323 char *menuitem_type_to_typename(MenuItemType type);
 324
 325 MenuEventType menuitem_eventtypename_to_eventtype(char *name);
 326
 327 char *menuitem_eventtype_to_eventtypename(MenuEventType type);
 328
 329 #endif