ug.h


ug.h

int ug_init (void)

Initialise the UG subsystem.


void ug_shutdown (void)

Shutdown the UG subsystem.


typedef struct ug_widget_class ug_widget_class_t

Opaque data type representing a widget class.


typedef struct ug_widget ug_widget_t

Opaque data type representing a widget.


void ug_widget_dirty (ug_widget_t *)

Mark a widget as "dirty", to be redrawn later. Currently, this marks the widget's dialog as dirty, so the entire dialog is redrawn, but you should not depend on that.


void ug_widget_focus (ug_widget_t *)

Give a widget input focus, within its own dialog. This is equivalent to calling ug_dialog_focus(dialog, widget), if you know what the dialog should be.

See also: ug_dialog_focus.



int ug_widget_x (ug_widget_t *)

Return the absolute x position of a widget.


int ug_widget_y (ug_widget_t *)

Return the absolute y position of a widget.


int ug_widget_w (ug_widget_t *)

Return the width of a widget, in pixels.


int ug_widget_h (ug_widget_t *)

Return the height of a widget, in pixels.


char *ug_widget_id (ug_widget_t *)

Return the id string of a widget.


typedef enum ug_event ug_event_t

An UG event number.


typedef enum ug_signal ug_signal_t

An UG signal number. Not to be confused with Unix signals.


typedef void ug_event_data_t

An opaque data type, used when dealing with event (or signal) data. To retrieve information from this data type, you must use the correct ug_event_* functions.



void ug_widget_send_event (ug_widget_t *, ug_event_t, ug_event_data_t *)

Send an event (including event data) to a widget. Events are messages handled by a widget's class.


void ug_widget_emit_signal (ug_widget_t *, ug_event_t, ug_event_data_t *)

Emit a signal (including event data) to a widget. Signals are like events, but are handled by user-defined slots, rather than the widget's class.


void ug_widget_send_event_key (ug_widget_t *, ug_event_t, int key)

Send an event to a widget, with keyboard event data.


void ug_widget_emit_signal_key (ug_widget_t *, ug_signal_t, int key)

Emit a signal to a widget, with keyboard event data.


int ug_event_data_key (ug_event_data_t *)

Return the key in a keyboard event.


void ug_widget_send_event_mouse (ug_widget_t *, ug_event_t, int x, int y, int b, int bstate)

Send an event to a widget, with mouse event data.


void ug_widget_emit_signal_mouse (ug_widget_t *, ug_signal_t, int x, int y, int b, int bstate)

Emit a signal to a widget, with mouse event data.


int ug_event_data_mouse_x (ug_event_data_t *)

Return the x position of a mouse event.


int ug_event_data_mouse_y (ug_event_data_t *)

Return the y position of a mouse event.


int ug_event_data_mouse_rel_x (ug_event_data_t *)

Return the relative x position of a mouse event.


int ug_event_data_mouse_rel_y (ug_event_data_t *)

Return the relative y position of a mouse event.


int ug_event_data_mouse_b (ug_event_data_t *)

Return the mouse button of a mouse event.


int ug_event_data_mouse_bstate (ug_event_data_t *)

Return the mouse button state of a mouse event.


void ug_widget_send_event_draw (ug_widget_t *, ug_event_t, struct BITMAP *bmp)

Send an event to a widget, with drawing event data.


void ug_widget_emit_signal_draw (ug_widget_t *, ug_signal_t, struct BITMAP *bmp)

Emit a signal to a widget, with drawing event data.


struct BITMAP *ug_event_data_draw_bmp (ug_event_data_t *)

Return the bitmap address of a draw event.


int ug_event_data_draw_x (ug_event_data_t *)

Return the x position of a draw event.


int ug_event_data_draw_y (ug_event_data_t *)

Return the y position of a draw event.


int ug_event_data_draw_w (ug_event_data_t *)

Return the width of a draw event.


int ug_event_data_draw_h (ug_event_data_t *)

Return the height of a draw event.


typedef struct ug_dialog_layout

An array of this structure type tells UG about the layout of widgets that make up a dialog. The structure contains the following fields:

- CLASS: the widget class to use.

- W: the width of the widget. This may be negative, in which case it will be interpreted as a percentage of the full dialog's width (e.g. -50 means 50% of its parent).

- H: the height of the widget.

- DATA: extra data for the widget class. For example, buttons would have a string here for the text label.

- SLOT: a function with the prototype:

void slot (ug_widget_t *w, ug_signal_t sig, void *data);

The function will be called whenever the widget emits a signal. It may be NULL if unneeded.

- ID: a string, which can be used to search through a dialog for a particular widget. It may be NULL if unneeded.

The array must be terminated with a UG_DIALOG_LAYOUT_END sentinel, and where you want the layout engine to create a new row, you need to put a special marker, UG_DIALOG_LAYOUT_BR.

Example:

    ug_dialog_layout_t my_dlg[] = {
        { ug_button, -100, 16, "button one", slot1, "b1" },
        { UG_DIALOG_LAYOUT_BR },
        { ug_button, -50, 16, "button two", NULL, NULL },
        { ug_button, -50, 16, "button three", slot3, "b3" },
        { UG_DIALOG_LAYOUT_END }
    };


ug_dialog_layout_t *ug_dialog_layout_create (void)

Create a dynamic dialog layout and return a pointer to it. If possible, you should use a static dialog layout instead of this.


void ug_dialog_layout_destroy (ug_dialog_layout_t *)

Free the memory associated with a dynamic dialog layout.


ug_dialog_layout_t *ug_dialog_layout_insert (ug_dialog_layout_t *dialog, ug_dialog_layout_t *newitem)

Add a layout item onto the back of a dynamic dialog layout, and return the new address of the dialog.


typedef struct ug_dialog ug_dialog_t

Opaque data type for holding dialogs.


ug_dialog_t *ug_dialog_create (struct gui_window *, ug_dialog_layout_t *, int border)

Create a dialog with the specified layout in a window, and with a specified border.


void ug_dialog_destroy (ug_dialog_t *)

Free memory associated with a dialog.


void ug_dialog_dirty (ug_dialog_t *)

Mark the window that a dialog occupies for redrawing.


void ug_dialog_focus (ug_dialog_t *, ug_widget_t *)

Give the focus to the specified widget in the dialog.

See also: ug_widget_focus.



int ug_dialog_x (ug_dialog_t *)

Return the x position of a dialog.


int ug_dialog_y (ug_dialog_t *)

Return the y position of a dialog.


int ug_dialog_w (ug_dialog_t *)

Return the width of a dialog.


int ug_dialog_h (ug_dialog_t *)

Return the height of a dialog.


ug_widget_t *ug_dialog_widget (ug_dialog_t *, char *id)

Return the widget in the dialog with the specified id.


extern ug_widget_class_t ug_blank

A dummy widget class that takes up space, but does nothing.


extern ug_widget_class_t ug_button

A widget class that implements a push button. The `data' field is the text label on the button. When clicked, it emits a UG_SIGNAL_CLICKED signal, with mouse event data.


void ug_button_set_extra (ug_widget_t *, void *extra)

Buttons have an `extra' field, which can point to anything you want. This sets the `extra' field of a button to EXTRA.


void *ug_button_extra (ug_widget_t *)

Return the data stored in a ug_button widget's `extra' field.


extern ug_widget_class_t ug_menu

A widget class implementing popup menus. The `data' field points to a ug_menu_root_t structure. When any one of the items in the menu is clicked, it emits a UG_SIGNAL_CLICKED signal. The data parameter of the slot function will be passed the contents of the selected menu item's `data' field.

See also: ug_menu_item_t, ug_menu_root_t.



typedef struct ug_menu_item

Holds infomation about a single menu item. The two fields are:

- LABEL: the label to use for the menu item

- DATA: arbitrary data to be associated with this menu item. This will be passed to the slot function if this item is selected.

Example:

    ug_menu_item_t items[] = {
        { "Foo Item", foodata },
        { "Bar Item", bardata },
        { NULL, NULL }
    };


typedef struct ug_menu_root

Holds information about a menu. It has two fields:

- LABEL: the label to use for the menu root button

- ITEM: a pointer to an array of ug_menu_item_t's. The array must be terminated with a ug_menu_item_t containing NULL for both the `label' and the `data' fields.

Example:

    ug_menu_root_t the_menu = { "Quux label", items };



Generated by mtfm.lua on Thu Dec 19 01:56:25 2002