Games/lbreakout2/gui/gui_widget.h

   1 /***************************************************************************
   2                           gui_widget.h  -  description
   3                              -------------------
   4     begin                : Fri Oct 11 2002
   5     copyright            : (C) 2002 by Michael Speck
   6     email                : kulkanie@gmx.net
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU General Public License as published by  *
  13  *   the Free Software Foundation; either version 2 of the License, or     *
  14  *   (at your option) any later version.                                   *
  15  *                                                                         *
  16  ***************************************************************************/
  17
  18 #ifndef __GUI_WIDGET_H
  19 #define __GUI_WIDGET_H
  20
  21 #include "list.h"
  22 #include "stk.h"
  23 #include "gui_theme.h"
  24
  25 //#define GUI_DEBUG
  26
  27 #define GUI_ABORT( msg ) \
  28  { fprintf( stderr, "Fatal GUI Error!\n%s\n", msg ); exit( 1 ); }
  29
  30 /*
  31 ====================================================================
  32 GUI events
  33 ====================================================================
  34 */
  35
  36 /* types */
  37 enum {
  38     GUI_NONE = 0,
  39     GUI_DESTROY,            /* widget is deleted */
  40     GUI_ACTIVATED,
  41     GUI_DEACTIVATED,        /* handle _input_ events or not */
  42     GUI_DRAW,               /* draw widget to stk_display */
  43     GUI_TIME_PASSED,        /* msecs since last TIME_PASSED event */
  44     GUI_FOCUS_IN,           /* widget lost focus */
  45     GUI_FOCUS_OUT,          /* widget gained focus */
  46     GUI_MOTION,             /* motion within widget */
  47     GUI_BUTTON_PRESSED,
  48     GUI_BUTTON_RELEASED,    /* mouse button */
  49     GUI_KEY_PRESSED,
  50     GUI_KEY_RELEASED,       /* key */
  51     GUI_CLICKED,            /* mouse button pressed + released */
  52     GUI_CHANGED,            /* type-dependent data changed */
  53     GUI_ITEM_SELECTED,
  54     GUI_ITEM_UNSELECTED     /* list item (un)selected */
  55 };
  56
  57 /* event */
  58 typedef union {
  59     int type;
  60     struct {
  61         int type;
  62         int x, y, button;
  63     } button;
  64     struct {
  65         int type;
  66         int x, y, xrel, yrel;
  67         int button; /* first button pressed */
  68         int state; /* full button mask */
  69     } motion;
  70     struct {
  71         int type;
  72         int keysym;
  73         int unicode;
  74     } key;
  75     struct {
  76         int type;
  77         int x, y;
  78     } item;
  79     struct {
  80         int type;
  81         int ms;
  82     } time;
  83 } GuiEvent;
  84
  85 /*
  86 ====================================================================
  87 Return pointer to simple event (one that doesn't need
  88 additional data)
  89 ====================================================================
  90 */
  91 GuiEvent *gui_event_get_simple( int type );
  92
  93 /*
  94 ====================================================================
  95 Initiate a GUI event from an SDL event.
  96 ====================================================================
  97 */
  98 void gui_event_init( GuiEvent *gui_event, SDL_Event *sdl_event );
  99
 100 /*
 101 ====================================================================
 102 GUI widget
 103 ====================================================================
 104 */
 105
 106 /* types */
 107 enum {
 108     GUI_BOX = 0,
 109     GUI_BUTTON,
 110     GUI_LABEL,
 111     GUI_ICON,
 112     GUI_PROGRESSBAR,
 113     GUI_RADIOGROUP,
 114     GUI_SCROLLBAR,
 115     GUI_EDIT,
 116     GUI_LIST,
 117     GUI_SPINBUTTON
 118 };
 119
 120 /* GUI widget -
 121    for simplicity only one is used for all types */
 122 typedef struct _GuiWidget {
 123     struct _GuiWidget *parent; /* widget's parent */
 124     struct _GuiWidget *root;   /* widget's root (top parent) */
 125     List *widgets;             /* widget's children */
 126     struct _GuiWidget *focused_widget; /* recursivly in widgets */
 127     struct _GuiWidget *default_key_widget;
 128         /* child 'default_key_widget' will grab key input if this
 129            is a root widget that is shown */
 130     int  type;       /* button, label, icon ... */
 131     int  visible;    /* gui_widget_draw() updates screen */
 132     int  active;     /* accept events */
 133     int  focused;    /* mouse pointer somewhere in widget */
 134     int  grab_input; /* deny event handling to lower roots */
 135     int  grab_keys;  /* grab key input if clicked */
 136     int  grab_focus; /* grab focus IF PRESSED thus motion events
 137                         are directly passed to widgets handler.
 138                         the focus is not updated until mouse button
 139                         is released again. */
 140     int  pressed;    /* memorize 'button_pressed' event */
 141     SDL_Rect screen_region; /* absolute region in screen (clipped) */
 142     SDL_Rect parent_region; /* relative region in parent */
 143     /* CALLBACKS */
 144     void (*default_event_handler)(struct _GuiWidget*,GuiEvent*);
 145         /* handles event and updates a widget (graphics etc) */
 146     void (*user_event_handler)(struct _GuiWidget*,GuiEvent*);
 147         /* user's possibility to react on event. is NOT called
 148            from the default_event_handler but from
 149            gui_widget_handle_event() itself. */
 150     /* USED BY ALL WIDGETS BUT TYPE DEPENDANT */
 151     int  border;        /* size of frame around widget */
 152     int  width, height; /* widget's size w/o border */
 153     int  event_mask;    /* events passed to user's event_handler */
 154     SDL_Surface *surface; /* picture of widget */
 155     /* SPECS */
 156     union {
 157         /* LABEL */
 158         struct {
 159             StkFont *font;
 160             int     align; /* alignment of text */
 161             char    *text; /* text */
 162         } label;
 163         /* PROGRESSBAR */
 164         struct {
 165             int max;    /* maximum value */
 166             int value;  /* current value */
 167             int length; /* current length */
 168             SDL_Surface *wallpaper; /* current beam wallpaper */
 169         } progressbar;
 170         /* RADIOGROUP */
 171         struct {
 172             int min; /* minimum selections required */
 173             int max; /* minimum selections allowed */
 174             int size; /* number of items */
 175             int *checks;      /* 'checked' flag for each item */
 176             int check_count;  /* number of selections */
 177             int single_check; /* id of last item selected */
 178             int x, y;   /* position of first checkbox in parent */
 179             int offset; /* offset from one item to next */
 180         } radiogroup;
 181         /* SCROLLBAR */
 182         struct {
 183             int vertical;    /* vertical scrollbar? */
 184             int button_size; /* size of (square) buttons */
 185             int value;       /* current value */
 186             int min, max;    /* range of value */
 187             int step;        /* offset for up/down */
 188             int jump;        /* offset for pgup/pgdown */
 189             struct _GuiWidget *inc;
 190             struct _GuiWidget *dec; /* pointers to 'widgets' */
 191             struct _GuiWidget *track; /* special widget that is NOT
 192                                          in the 'widgets' list */
 193         } scrollbar;
 194         /* EDIT */
 195         struct {
 196             int  filter[SDLK_LAST]; /* characters accepted */
 197             int  multi_line; /* single-line edit or text area? */
 198             int  size;    /* character limit */
 199             char *buffer; /* string of edit */
 200             char *display_buffer; /* contains 'height' lines of
 201                 length 'width' separated by \0 which will be
 202                 displayed when drawing. is rendered by
 203                 gui_edit_adjust_cursor() */
 204             int  length; /* current string length */
 205             int  width;  /* characters per line */
 206             int  height; /* number of lines */
 207             int  x, y;   /* position in visible characters */
 208             int  y_offset; /* used to center single-line edits */
 209             int  pos;    /* position of edit cursor */
 210             int  start;  /* first character displayed */
 211             int  line;   /* first line displayed (start/width) */
 212         } edit;
 213         /* LIST */
 214         struct {
 215             int columns;        /* (fixed) number of columns */
 216             int item_width;
 217             int item_height;    /* item size */
 218             int gap;            /* space between items */
 219             int rows_per_page;  /* number of rows displayed */
 220             int item_count;     /* number of items */
 221             int rows;           /* number of rows */
 222             int select_type;    /* no, single, multi select */
 223             int *checks; /* NO_SELECT:     unused
 224                             SINGLE_SELECT: id of selected item
 225                             MULTI_SELECT:  flags for all items
 226                                            whether they are
 227                                            selected or not */
 228             SDL_Surface
 229                 *render_buffer; /* 'render_item' renders item
 230                                     into this surface*/
 231             int (*render_item)(int,int,SDL_Surface*); /* user
 232                 defined render callback to render item x,y into
 233                 surface. This item is only displayed
 234                 if 'render_item' returns True. */
 235             struct _GuiWidget  *scrollbar; /* pointer to
 236                                               'widgets' */
 237         } list;
 238         /* SPINBUTTON */
 239         struct {
 240             int       min, max, step; /* range of value */
 241             int       value;          /* value */
 242             struct _GuiWidget *edit;  /* pointer to edit */
 243             struct _GuiWidget *inc;
 244             struct _GuiWidget *dec;   /* pointer to buttons */
 245         } spinbutton;
 246     } spec;
 247 } GuiWidget;
 248
 249 /*
 250 ====================================================================
 251 Create a basic widget and setup things all different widget types
 252 have in common. If a parent is specified this widget is added to
 253 it's 'widgets' list. 'x' or 'y' -1 means to center the
 254 widget.
 255 ====================================================================
 256 */
 257 GuiWidget* gui_widget_create(
 258     GuiWidget *parent, int type,
 259     int x, int y, int width, int height,
 260     void (*default_event_handler)(GuiWidget*,GuiEvent*),
 261     void (*user_event_handler)(GuiWidget*,GuiEvent*) );
 262
 263 /*
 264 ====================================================================
 265 This function will delete a root widget including all subwidgets.
 266 Subwidgets can't be directly deleted. Resets the widget
 267 pointer to NULL.
 268 ====================================================================
 269 */
 270 void gui_widget_delete( GuiWidget **widget );
 271
 272 /*
 273 ====================================================================
 274 If button is deactivated no input events (key,button,motion)
 275 are handled.
 276 ====================================================================
 277 */
 278 void gui_widget_set_active( GuiWidget *widget, int active );
 279
 280 /*
 281 ====================================================================
 282 Draw the widget and its children if visible.
 283 ====================================================================
 284 */
 285 void gui_widget_draw( GuiWidget *widget );
 286
 287 /*
 288 ====================================================================
 289 Set 'visible' flag and draw widget (store update rects)
 290 if either parent is visible or it has no parent.
 291 (thus is a root window). If it is a root window add it to the
 292 root window stack. This new window will handle incoming events
 293 first.
 294 ====================================================================
 295 */
 296 void gui_widget_show( GuiWidget *widget );
 297
 298 /*
 299 ====================================================================
 300 Clear 'visible' flag and restore widget if parent is visible.
 301 If there is no parent (thus is a root window) remove it from
 302 stack and redraw the underlying window (which regains control). If
 303 a root widget is hidden the background cannot be restored
 304 as it is unknown.
 305 ====================================================================
 306 */
 307 void gui_widget_hide( GuiWidget *widget );
 308
 309 /*
 310 ====================================================================
 311 Modify the event mask of a widget to define which events will
 312 be passed to user_event_handler. Update timed_stack if
 313 GUI_TIME_PASSED is enabled/disabled.
 314 ====================================================================
 315 */
 316 void gui_widget_enable_event( GuiWidget *widget, int event );
 317 void gui_widget_disable_event( GuiWidget *widget, int event );
 318
 319 /*
 320 ====================================================================
 321 Pass GuiEvent to user defined callback if it has been installed
 322 and the event mask flag is True for this event.
 323 ====================================================================
 324 */
 325 void gui_widget_call_user_event_handler(
 326     GuiWidget *widget, GuiEvent *event );
 327
 328 /*
 329 ====================================================================
 330 Handle the GUI event by calling the default_event_handler()
 331 and the user_event_handler() if one has been installed.
 332 ====================================================================
 333 */
 334 void gui_widget_handle_event( GuiWidget *widget, GuiEvent *event );
 335
 336 /*
 337 ====================================================================
 338 Move widget within parent window by a relative value. If the
 339 widget is visible the changes will be drawn to screen.
 340 ====================================================================
 341 */
 342 void gui_widget_move( GuiWidget *widget, int rel_x, int rel_y );
 343
 344 /*
 345 ====================================================================
 346 Move widget within parent window by an absolute value. If the
 347 widget is visible the changes will be drawn to screen.
 348 ====================================================================
 349 */
 350 void gui_widget_warp( GuiWidget *widget, int abs_x, int abs_y );
 351
 352 /*
 353 ====================================================================
 354 Apply parents background or wallpaper within the frame (if
 355 any) of the widget's surface.
 356 ====================================================================
 357 */
 358 void gui_widget_apply_wallpaper(
 359     GuiWidget *widget, SDL_Surface *wallpaper, int alpha );
 360
 361 /*
 362 ====================================================================
 363 Browse the widget tree and set 'focused' true for all widgets
 364 that have the mouse pointer above them. 'focused_widget'
 365 returns the deepest widget that is focused.
 366 ====================================================================
 367 */
 368 void gui_widget_update_focus(
 369     GuiWidget *widget, int mx, int my, GuiWidget **focused_widget );
 370
 371 /*
 372 ====================================================================
 373 Get direct access to widget's surface.
 374 ====================================================================
 375 */
 376 SDL_Surface *gui_widget_get_surface( GuiWidget *widget );
 377
 378 /*
 379 ====================================================================
 380 That key grabbing child of a root widget.
 381 ====================================================================
 382 */
 383 void gui_widget_set_default_key_widget(
 384     GuiWidget *root, GuiWidget *key_widget );
 385
 386 #endif