Controls

OBJECTS

  struct Control {
    Rect            area;           /* rectangle on parent */
    Point           offset;         /* to window's co-ordinates */
    Window *        win;            /* parent window, if any */
    Control *       parent;         /* parent control, if any */
    int             num_children;   /* list of child controls */
    Control **      children;
    Colour          bg;             /* background fill colour */
    Colour          fg;             /* foreground drawing colour */
    int             state;          /* VISIBLE, CHECKED, etc */
    Region *        visible;        /* in window co-ords */
    void *          data;           /* user-defined pointer */
    char *          text;           /* text to display */
    void *          extra;          /* internal pointer */
    long            value;          /* internal integer value */
    Image *         img;            /* internal image pointer */
    Font *          font;           /* internal image pointer */
    ControlFunc     resize;         /* event handlers */
    DrawFunc        redraw;
    MouseFunc       mouse_down;
    MouseFunc       mouse_up;
    MouseFunc       mouse_drag;
    MouseFunc       mouse_move;
    KeyFunc         key_down;
    KeyFunc         key_action;
    ControlFunc     action;
    ControlFunc     update;
    ControlFunc     refocus;
    ControlFunc     del;
  };

  typedef void (*ControlFunc)  (Control *c);

FUNCTIONS

  Control *new_control(Window *parent, Rect r);
  Control *add_control(Ctronol *parent, Rect r);
  void     del_control(Control *c);

  int      remove_control(Control *c);
  int      attach_to_window(Window *parent, Control *c);
  int      attach_to_control(Control *parent, Control *c);
  int      bring_control_to_front(Control *c);
  int      send_control_to_back(Control *c);

  Window * parent_window(Control *c);

NOTES

A Control is a area on a window which responds to user's actions, such as mouse clicks and the keyboard, to perform some function. Functions which create controls take as an argument a rectangle, which specifies where on the current window the control should be placed. The rectangle is measured in pixels, relative to the top-left point of the window which is the point (0,0).

Buttons, check boxes, text fields, etc are all kinds of Controls, so many of the functions described in the following sections apply equally to those objects, as they do to custom-made controls.

The new_control function creates and returns a generic control of the requested size and attaches it to the given window. The control can have call-backs added to it using on_control_redraw, ap_on_control_mouse_down etc (see later sections), to allow the control to respond to events.

The add_control function behaves much the same, except the created control is attached to the given parent control. Controls can have other controls attached to their surfaces. These child controls will appear inside the parent control, and cannot move outside of the parent's boundary.

The del_control function destroys a control and removes it from any window to which it is attached. Normally this function is not used, since destroying a window will destroy all of its child controls.

The remove_control function removes a control from its parent window or control. A side-effect of this function is that the control will become invisible since the parent window or control will be redrawn. Such a removed control can be re-attached to a window or control's surface using attach_to_window or attach_to_control.

A control's position in the stacking hierarchy can be manipulated. The bring_control_to_front function moves a control in front of its siblings, while send_control_to_back places it behind its siblings.

The parent_window function returns the window where the control resides. If a control is a child of another control, this function looks up the parent window of the parent controls until it finds the enclosing window. If the control or its parents are not currently attached to any window, this function returns NULL.