Agar

<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

AG_Widget is the base class for GUI widgets (and windows) in Agar GUI. Instances of AG_Widget can be attached (using AG_ObjectAttach(3)) to any other AG_Widget (known as the container widget). General-purpose container widgets include AG_Window(3) and AG_Box(3).

The class registration interface of AG_Object(3) allows new widgets to be implemented (or derived from existing classes). Widgets use the object system's AG_Event(3) to handle (and deliver) events. AG_Variable(3) provides the basis for memory bindings (see BINDINGS section).

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget.

CLASS OPERATIONS

Object operations specific to the AG_Widget class are defined as follows: 
typedef struct ag_widget_class {
	struct ag_object_class _inherit;
	void (*draw)(AG_Widget *w);
	void (*size_request)(AG_Widget *w, AG_SizeReq *req);
	int  (*size_allocate)(AG_Widget *w, const AG_SizeAlloc *alloc);
} AG_WidgetClass;

draw() renders the widget to the graphics display. The code under draw() is referred to as the Rendering Context. Some functions (such as AG_WidgetBlitSurface()) are unsafe to call outside Rendering Context.

size_request() should return an initial, preferred geometry in px (without any guarantee that the request will be satisfied). For example, an AG_Label(3), might return the expected size of a rendered text label.

size_allocate() is called once the widget has been successfully allocated a new size or position within its parent (as described by the w, h, x and y members of the AG_SizeAlloc argument). Container widgets allocate the position and size of their children in size_allocate().

size_allocate() should return 0 on success and -1 if the allocation is not satisfactory for draw() to work at all (in which case the UNDERSIZE flag will be set and draw() will not run).

SIZING


void AG_Expand (AG_Widget *widget)

void AG_ExpandHoriz (AG_Widget *widget)

void AG_ExpandVert (AG_Widget *widget)

void AG_WidgetSizeReq (AG_Widget *widget, AG_SizeReq *req)

void AG_WidgetSizeAlloc (AG_Widget *widget, AG_SizeAlloc *alloc)

void AG_WidgetSetPosition (AG_Widget *widget, int x, int y)

void AG_WidgetSetSize (AG_Widget *widget, int w, int h)

void AG_WidgetSetGeometry (AG_Widget *widget, AG_Rect rect)

void AG_WidgetUpdate (AG_Widget *widget)


AG_Expand() makes the widget fill all available space in the parent. AG_ExpandHoriz() and AG_ExpandVert() makes the widget fill the available space horizontally or vertically.

Note: Most widget constructors accept EXPAND, HFILL and VFILL as option flags. Setting them is equivalent to calling AG_Expand(), AG_ExpandHoriz() and AG_ExpandVert().

AG_WidgetSizeReq() invokes the size_request() operation of the widget and returns its size requisition into req. AG_WidgetSizeAlloc() allocates the given position and geometry of the widget. If the w or h argument is <= 0, the AG_WIDGET_UNDERSIZE flag is set, preventing the widget from subsequent rendering.

AG_WidgetSizeReq() and AG_WidgetSizeAlloc() are meant to be called only from within the size_request() and size_allocate() functions of a container widget implementation, in order to size and position the child widgets attached to the container (if you must set widget geometries explicitely, use either the AG_Fixed(3) container, or create your own container widget).

The AG_SizeReq and AG_SizeAlloc structures are defined as follows: 
typedef struct ag_size_req {
	int w, h;			/* Requested geometry in pixels */
} AG_SizeReq;

typedef struct ag_size_alloc {
	int w, h;			/* Allocated geometry in pixels */
	int x, y;			/* Allocated position in pixels */
} AG_SizeAlloc;

AG_WidgetSetPosition() sets the effective position of the widget relative to its parent container. AG_WidgetSetSize() sets the size of the widget in pixels. AG_WidgetSetGeometry() sets both position and size of a widget from the specified AG_Rect. These functions are typically only used in the context of the size_request() and size_allocate() routines of container widgets.

AG_WidgetUpdate() requests an update of the computed coordinates and geometries of all widgets attached to the widget's current window. The widget may or may not be attached to a parent window (the actual update will be performed later, before rendering starts in AG_WindowDraw()). AG_WidgetUpdate() should be called following AG_ObjectAttach(3) or AG_ObjectDetach(3) calls made in event context, or manual modifications of the x, y, w, h fields of the AG_Widget structure.

INPUT STATE


void AG_WidgetEnable (AG_Widget *widget)

void AG_WidgetDisable (AG_Widget *widget)

int AG_WidgetEnabled (AG_Widget *widget)

int AG_WidgetDisabled (AG_Widget *widget)


The "enabled" flag of a widget determines whether the user is allowed to modify whatever data the widget is accessing. The interpretation of this flag is widget-specific. AG_WidgetEnable() sets the flag, AG_WidgetDisable() clears it. These functions will raise the widget-enabled and widget-disabled events accordingly.

The functions AG_WidgetEnabled() and AG_WidgetDisabled() return the current "enabled" state of the widget. The AG_Widget object must be locked when the call is made.

FOCUS STATE

The focus state of widgets enables the reception of specific types of events which are filtered by default. The focus state also affects the behavior and appearance of some widgets. A widget holding focus (in a currently focused window) will receive mouse events mouse-motion(), mouse-button-up(), as well as keyboard events key-up() and key-down() (note that unfocused widgets can be configured to receive those events unfiltered as well using the AG_WIDGET_UNFOCUSED_* options).


int AG_WidgetSetFocusable (AG_Widget *widget, int enable)

int AG_WidgetFocus (AG_Widget *widget)

void AG_WidgetUnfocus (AG_Widget *widget)

int AG_WidgetIsFocused (AG_Widget *widget)

int AG_WidgetIsFocusedInWindow (AG_Widget *widget)

void AG_WidgetForwardFocus (AG_Widget *widget, AG_Widget *widgetToFocus)


AG_WidgetSetFocusable() sets the AG_WIDGET_FOCUSABLE flag which allows the widget to receive focus (0 = ignore, 1 = accept focus). Returns the previous setting.

AG_WidgetFocus() gives focus to the specified widget and all of its parent widgets including the parent AG_Window(3). Returns 1 on success and 0 if the widget is not accepting focus.

AG_WidgetUnfocus() removes the focus state from the given widget (including its child widgets, if any).

AG_WidgetIsFocused() returns 1 if the widget is currently holding focus (i.e., the widget has the focus flag set, and its parent window, if any, is focused as well). AG_WidgetIsFocusedInWindow() returns 1 if the widget has the focus flag set (without evaluating the focus state of any parent windows).

AG_WidgetForwardFocus() arranges automatic forwarding of the focus to a specified widget. Whenever AG_WidgetFocus will be invoked on widget, the focus will be given to widgetToFocus instead.

COORDINATES


int AG_WidgetArea (AG_Widget *widget, int x, int y)

int AG_WidgetRelativeArea (AG_Widget *widget, int x, int y)


The AG_WidgetArea() routine tests whether view coordinates x and y lie inside of the widget's allocated space. The AG_WidgetRelativeArea() variant accepts widget coordinates.

BLITTING SURFACES

These routines allow graphical surfaces to be managed (mapped in hardware or software) and efficiently copied. They must be called from Rendering Context (i.e., the draw() operation of AG_Widget) only.


void AG_WidgetBlit (AG_Widget *widget, AG_Surface *src, int x, int y)

int AG_WidgetMapSurface (AG_Widget *widget, AG_Surface *su)

int AG_WidgetMapSurfaceNODUP (AG_Widget *widget, AG_Surface *su)

void AG_WidgetReplaceSurface (AG_Widget *widget, int surface_id, AG_Surface *newSurface)

void AG_WidgetReplaceSurfaceNODUP (AG_Widget *widget, int surface_id, AG_Surface *newSurface)

void AG_WidgetUnmapSurface (AG_Widget *widget, int surface_id)

void AG_WidgetUpdateSurface (AG_Widget *widget, int surface_id)

void AG_WidgetBlitFrom (AG_Widget *dstWidget, AG_Widget *srcWidget, int surface_id, AG_Rect *rs, int x, int y)

void AG_WidgetBlitSurface (AG_Widget *widget, int surface_id, int x, int y)


The AG_WidgetBlit() function performs a software->hardware blit from the surface src to the video display at the given widget coordinates. AG_WidgetBlit() must invoked in Rendering Context. See AG_Surface(3) for more information on the Agar surface structure.

Software to hardware blits are slow, so the widget system provides an interface to efficiently take advantage of graphics hardware where it is available. AG_WidgetMapSurface() registers the specified AG_Surface(3) with the widget, returning an integer handle to that surface. The surface can be subsequently rendered by calling AG_WidgetBlitSurface() or AG_WidgetBlitFrom() using this handle. The exact manner in which the surface is rendered depends on the Agar driver in use. For OpenGL-based drivers, a matching hardware texture will typically be generated for the surface on the first call to AG_WidgetBlitSurface(), and cached.

By default, mapped surfaces are automatically freed once the widget is destroyed. The AG_WidgetMapSurfaceNODUP() variant sets the "NODUP" flag on the given surface, so the widget system will never attempt to free the surface.

Note that AG_WidgetMapSurface() will never duplicate the surface. The function merely registers the provided surface pointer with the widget structure. The surface pointer must remain valid for the lifetime of the widget (if in doubt, use AG_SurfaceDup(3)).

Under multithreading, AG_WidgetMapSurface() may be invoked from any context, but the returned name is only valid as long as the widget is locked (see AG_ObjectLock(3)).

AG_WidgetReplaceSurface() replaces the contents of a previously-mapped surface with the contents of newSurface. The AG_WidgetReplaceSurfaceNODUP() variant avoids duplicating the surface.

AG_WidgetUnmapSurface() destroys the given surface mapping. It is equivalent to invoking AG_WidgetReplaceSurface() with a NULL surface. The function is safe to use from any context.

It is important to note that in OpenGL mode, AG_WidgetReplaceSurface() and AG_WidgetUnmapSurface() will not immediately delete any previous texture associated with the previous surface. Instead, it will queue the delete operation for future execution from Rendering Context, as required by thread safety.

The AG_WidgetUpdateSurface() function should be invoked whenever a mapped surface is changed. If hardware surfaces are supported, it will cause an upload of the software surface to the hardware (otherwise it is a no-op).

The AG_WidgetBlitFrom() function renders a previously mapped (possibly hardware) surface from the source widget srcWidget (using source rectangle rs) onto the destination widget dstWidget, at coordinates x, y. This function must be invoked in Rendering Context.

The AG_WidgetBlitSurface() variant invokes AG_WidgetBlitFrom with the same argument for both srcWidget and dstWidget (and rs set to NULL).

BINDINGS

Widget states can be bound to memory locations containing data in a supported format. For example, the "state" binding of AG_Button(3) can be tied to an integer (or bits in an integer), such that the user pressing the button directly manipulates the integer value in memory.

Bindings are documented under the BINDINGS section of the widget's manual page. For instance, AG_Slider(3) mentions "value" bindings to integers. Therefore, to control a byte of memory, one might use: 
	static Uint8 myByte = 0;

	AG_Slider *slider = AG_SliderNew(window, AG_SLIDER_HORIZ, 0);
	AG_BindUint8(slider, "value", &myByte);

Or alternatively, using a shorthand constructor: 
	AG_SliderNewUint8(window, AG_SLIDER_HORIZ, 0, &myByte, NULL, NULL);

This method is not limited to primitive data types. For example, AG_Textbox(3) can bind to a fixed-size memory buffer containing a C string in ASCII, UTF-8 or other supported encoding.

The AG_Bind<Type>() family of functions bind widget states to memory data. The AG_Bind<Type>Mp() variants accept a pointer to a mutex which will be acquired prior to accessing the data. The AG_Bind<Type>Fn() variants accept a pointer to a function instead of a memory location (the widget state will then be obtained by evaluating that function).

Note: The AG_Variable(3) API is actually part of AG_Object(3), and is not GUI-specific. It can be useful in non-GUI applications as well.

Since the state of a widget can influence its appearance (e.g., AG_Button(3) is drawn as a pressed button if its "state" is 1), it may be necessary to monitor the value and redraw when it changes. AG_RedrawOnChange() arranges for this to occur automatically (see below).

CONTROLLING REDRAW


void AG_Redraw (AG_Widget *widget)

void AG_RedrawOnChange (AG_Widget *widget, int refresh_ms, const char *binding_name)

void AG_RedrawOnTick (AG_Widget *widget, int refresh_ms)


The AG_Redraw() function signals that the widget must be redrawn to the video display. It is equivalent to setting the dirty variable of the widget's parent window to 1. If called from Rendering Context, AG_Redraw() is a no-op.

The AG_RedrawOnChange() function arranges for the widget to be automatically redrawn whenever the value associated with the existing binding binding_name changes. The value of the binding will be checked at the specified interval refresh_ms in milliseconds. If a refresh_ms argument of -1 is passed, the effect of any previous AG_RedrawOnChange() call with the specified binding is disabled.

The AG_RedrawOnTick() function arranges for the widget to be unconditionally redrawn at the specified interval in milliseconds. If a refresh_ms argument of -1 is passed, the effect of any previous AG_RedrawOnTick() call is disabled.

WIDGET QUERIES


AG_Window * AG_ParentWindow (AG_Widget *widget)

AG_Widget * AG_WidgetFind (AG_Driver *drv, const char *path)

AG_Widget * AG_WidgetFindFocused (AG_Window *win)

AG_Widget * AG_WidgetFindPoint (const char *className, int x, int y)

AG_Widget * AG_WidgetFindRect (const char *className, int x, int y, int w, int h)


AG_ParentWindow() returns a pointer to the parent AG_Window(3) for the given widget instance. The pointer is valid only as long as the parent VFS remains locked. If the widget is not attached, NULL is returned.

AG_WidgetFind() locates a widget instance by name, where path is a " / " separated path name relative to the AG_Driver(3) VFS root, for example: "My Window/Box #1/My button". If the widget exists, the function returns a pointer to the AG_Widget instance. The returned pointer is valid only as long as the parent VFS remains locked.

AG_WidgetFindFocused() returns the top-most focused widget under win.

AG_WidgetFindPoint() returns the top-most widget at display coordinates x, y, which also is an instance of a the given className (see AG_ObjectClass(3), AG_OfClass(3)). The AG_WidgetFindRect() variant requires that the widget enclose the whole given rectangle.

Similarly to AG_WidgetFind(), the AG_Widget pointer returned by AG_WidgetFindFocused(), AG_WidgetFindPoint() and AG_WidgetFindRect() should be considered valid only for as long as the parent VFS is locked.

RENDERING CONTROL


void AG_PushClipRect (AG_Widget *widget, AG_Rect r)

void AG_PopClipRect (AG_Widget *widget)

void AG_WidgetDraw (AG_Widget *widget)

void AG_BeginRendering (AG_Driver *drv)

void AG_EndRendering (AG_Driver *drv)

void AG_WidgetHide (AG_Widget *widget)

void AG_WidgetShow (AG_Widget *widget)

void AG_WidgetHideAll (AG_Widget *widget)

void AG_WidgetShowAll (AG_Widget *widget)

int AG_WidgetVisible (AG_Widget *widget)

AG_Surface * AG_WidgetSurface (AG_Widget *widget)


The AG_PushClipRect() function pushes a rectangle (in widget coordinates) onto the stack of clipping rectangles, and AG_PopClipRect() pops the last entry from the clipping rectangle stack. The effective clipping rectangle will be the intersection of all rectangles on this stack. AG_PushClipRect() and AG_PopClipRect() must be invoked in Rendering Context.

The AG_WidgetDraw() routine renders a widget to the display. It is typically invoked from an event loop routine (such as AG_EventLoop(3)), to recursively draw the hierarchy of visible GUI elements.

In the event loop, AG_WidgetDraw() invocations must be enclosed between calls to AG_BeginRendering() and AG_EndRendering().

The AG_WidgetHide() and AG_WidgetShow() functions toggle the visibility of the specified widget (setting the AG_WIDGET_HIDE flag as appropriate).

The AG_WidgetHideAll() and AG_WidgetShowAll() routines toggle the visibility of the specified widget and its children by setting the AG_WIDGET_VISIBLE flag (which works independently of AG_WIDGET_HIDE). These routines are intended to be used by container widgets (for example, AG_Notebook(3) which needs to show or hide tabbed containers).

AG_WidgetVisible() returns 1 if the widget is currently visible (equivalent to checking the AG_WIDGET_VISIBLE flag).

The AG_WidgetSurface() routine renders the widget to a newly-allocated AG_Surface(3). This surface should be freed after use.

STYLE PROPERTIES

Presentation settings such as fonts and colors are stored as named AG_Variable(3) properties (e.g., "font-size", "color", "color#hover", etc.) Those properties should be set using the following functions:


void AG_SetFont (AG_Widget *widget, const AG_Font *font)

void AG_SetStyle (AG_Widget *widget, const char *which, const char *value)


The AG_SetFont() function sets the widget's default font attributes to match those of the specified font object.

The AG_SetStyle() function sets the specified style attribute to the given value. Accepted attributes are as follows:
font-familyFont face specification ("Courier", "Terminal").
font-sizeFont size in points ("10pts") or ratio ("50%").
font-weightFont weight, either "bold" or "normal".
font-styleFont style, either "italic" or "normal".
colorMain color of the widget. Colors may be specified as unsigned 8-bit components with "rgb(r,g,b[,a])", or floating-point HSV parameters with "hsv(h,s,v[,a])". In either mode, components may be expressed as a ratio to the parent widget's color components by appending a "%".
text-colorColor for rendered text.
line-colorColor for line drawings.
shape-colorColor for polygons and other filled shapes.
border-colorColor for cosmetic borders.

An optional selector may be appended to the attribute names. Accepted selectors include "#disabled", "#hover" and "#selected". Selectors may be interpreted differently on a per-widget basis.

STANDARD WIDGET ACTIONS

User-generated events such as key presses or mouse button events can be tied to actions, such as executing a specified routine or controlling a boolean variable. Registered actions are described by the AG_Action structure.

Where the conditions for execution of an Action are fixed (e.g., a specific mouse button was clicked, or a specific key was pressed), use of AG_ActionOn*() is preferred over low-level event handlers (such as "key-down" or "mouse-button-down"), because it allows keyboard and mouse bindings to be configured by the end-user in a standard way. AG_Menu(3) also provides interfaces for working with widget actions.


AG_Action * AG_ActionFn (AG_Widget *widget, const char *action, void (*fn)(AG_Event *), const char *fnArgs, ...)

AG_Action * AG_ActionSetInt (AG_Widget *widget, const char *action, int *variable, int value)

AG_Action * AG_ActionSetFlag (AG_Widget *widget, const char *action, Uint *variable, Uint bitmask, int value)

AG_Action * AG_ActionToggleInt (AG_Widget *widget, const char *action, int *variable)

AG_Action * AG_ActionToggleFlag (AG_Widget *widget, const char *action, Uint *variable, Uint bitmask)

void AG_ActionOnButtonDown (AG_Widget *widget, int button, const char *action)

void AG_ActionOnButtonUp (AG_Widget *widget, int button, const char *action)

void AG_ActionOnKeyDown (AG_Widget *widget, AG_KeySym sym, AG_KeyMod mod, const char *action)

void AG_ActionOnKeyUp (AG_Widget *widget, AG_KeySym sym, AG_KeyMod mod, const char *action)

void AG_ActionOnKey (AG_Widget *widget, AG_KeySym sym, AG_KeyMod mod, const char *action)

int AG_ExecMouseAction (AG_Widget *widget, AG_ActionEventType type, int button, int x, int y)

int AG_ExecKeyAction (AG_Widget *widget, AG_ActionEventType type, AG_KeySym sym, AG_KeyMod mod)

int AG_ExecAction (AG_Widget *widget, AG_Action *a)


AG_ActionFn() registers a new widget action which is to invoke a callback function fn, with arguments fnArgs. See AG_Event(3) for a description of the fnArgs format.

AG_ActionSetInt() registers a new action which is to set an integer variable to a specified value. Instead of an integer variable, AG_ActionSetFlag() sets the bits specified by bitmask to the specified value (of 1 or 0). The AG_ActionToggleInt() and AG_ActionToggleFlag() variants do not take an explicit value argument, and toggle the current value instead.

AG_ActionOnButtonDown() and AG_ActionOnButtonUp() tie an action to a button press and a button release event, respectively. The button argument specifies the button index (see AG_MouseButton(3)). AG_ActionOnKeyDown() and AG_ActionOnKeyUp() tie an action to a key press and key release event, respectively. The sym argument specifies the key (see AG_KeySym(3)), and mod specifies the modifier keys which must be in effect. To match any key or any modifier state, AG_KEY_ANY or AG_KEYMOD_ANY can be used.

With AG_ActionOnKeyDown() and AG_ActionOnKeyUp(), the action is triggered once immediately on key press or key release. The AG_ActionOnKey() variant ties an action to a key press, but with "key repeat" behavior. The action is triggered immediately once after an initial key press. If the key combination is held longer than the "key delay" (by default 250ms), the event is repeated with the "key repeat" interval (by default 30ms).

If there are currently no event handlers registered for "key-up", "key-down", "mouse-button-up" and "mouse-button-down", the AG_ActionOn*() functions automatically register event handlers which will invoke AG_ExecMouseAction() or AG_ExecKeyAction() as appropriate (see below).

AG_ExecMouseAction() executes any action associated with mouse button events. It is typically invoked from the "mouse-button-down" and "mouse-button-up" event handlers of the widget. Accepted type values are AG_ACTION_ON_BUTTONDOWN and AG_ACTION_ON_BUTTONUP. button is the pressed button index (see AG_MouseButton(3)). x and y is the position of the cursor in the widget's coordinate system.

AG_ExecKeyAction() executes any action associated with keyboard events. It is typically invoked from the "key-down" and "key-up" event handlers of the widget. Accepted type values are AG_ACTION_ON_KEYDOWN and AG_ACTION_ON_KEYUP. sym and mod specify the key index and modifier state (see AG_KeySym(3) and AG_KeyMod(3)).

AG_ExecAction() executes the specified action. AG_ExecAction() is rarely used directly, but it is invoked internally by the AG_ExecFooAction() functions.

EVENTS

The GUI system may send AG_Widget objects the following events:
widget-shown (void)
The widget is now visible. NOTE: Handlers for this event should be set using AG_AddEvent(3) as opposed to AG_SetEvent(3).
widget-hidden (void)
The widget is no longer visible. NOTE: Handlers for this event should be set using AG_AddEvent(3) as opposed to AG_SetEvent(3).
widget-enabled (void)
Input state has been enabled with AG_WidgetEnable(3).
widget-disabled (void)
Input state has been disabled with AG_WidgetDisable(3).
widget-moved (void)
The widget (or one of its parents) has been moved.
widget-gainfocus (void)
The widget now holds focus inside its parent container.
widget-lostfocus (void)
The widget no longer holds focus.
widget-reshape (void)
Widget size has changed and USE_OPENGL is set (and the GL_PROJECTION or GL_MODELVIEW matrices may need to be updated).
widget-overlay (void)
Invoked following the draw() operation; requires USE_OPENGL.
widget-underlay (void)
Invoked prior to the draw() operation; requires USE_OPENGL.
font-changed (void)
The default font associated with the widget has changed. The new font may be accessed via the font structure member.

The following events are usually generated by input devices:
mouse-motion (int x, int y, int xRel, int yRel, int buttons)
The widget is receiving mouse motion events, and the cursor has been moved. x and y are the coordinates of the cursor in the widget's local coordinate system (these coordinates may be negative or exceed the widget's dimensions if the cursor is not in the widget's area). xRel and yRel represent the displacement relative to the last position of the mouse cursor. The buttons argument is a bitmask representing the state of mouse buttons (see AG_MouseButton(3)).
mouse-button-up (int button, int x, int y)
The widget is receiving mouse button release events, and button has been released. x and y are the cursor coordinates in the widget's local coordinate system.
mouse-button-down (int button, int x, int y)
The widget is receiving mouse button events, and button has been pressed. x and y are the cursor coordinates in the widget's local coordinate system.
mouse-over (void)
The cursor has entered or is leaving the widget's allocated area and the AG_WIDGET_USE_MOUSEOVER option is set.
key-down (int key, int mod, Ulong unicode)
The widget is receiving keyboard events and key has been pressed. The mod argument is a bitmask representing the state of the current key modifiers and unicode is the corresponding Unicode character in UCS-4 format (or 0 if there are none). See AG_KeySym(3) for details.
key-up (int key, int mod, Ulong unicode)
The widget is receiving keyboard events and key has been released. The mod argument is a bitmask representing the state of the current key modifiers and unicode is the corresponding Unicode character in UCS-4 format (or 0 if there are none). See AG_KeySym(3) for details.

STRUCTURE DATA

For the AG_Widget object:
Uint flags Option flags (see FLAGS section below).
int x, y Pixel coordinates of the widget relative to its parent.
int w, h Dimensions of the widget in pixels.
AG_Rect2 rView Absolute view coordinates of the widget (relative to the parent driver device).
AG_Font *font Pointer to the effective font associated with the widget (see AG_Font(3)). This setting is read-only (use AG_SetFont() to change).

FLAGS

The flags member of the AG_Widget structure accepts the following flags:
AG_WIDGET_HFILLHint to container widgets that in a vertical packing, this widget can expand to fill all remaining space.
AG_WIDGET_VFILLHint to container widgets that in a horizontal packing, this widget can expand to fill all remaining space.
AG_WIDGET_HIDEDisable rendering of this widget.
AG_WIDGET_VISIBLEThis widget and its parent window are both currently visible (read-only).
AG_WIDGET_UNDERSIZEDisable rendering of this widget because it was determined to have a zero-valued geometry (read-only, set by AG_WidgetSizeAlloc()).
AG_WIDGET_DISABLEDAdvise that widget is not accepting user input. The effect of this option is widget-dependent (read-only; see INPUT STATE section). This flag may affect the way the widget is rendered.
AG_WIDGET_MOUSEOVERA mouse cursor currently intersects the widget's area (read-only; updated internally if the AG_WIDGET_USE_MOUSEOVER flag is set). This flag may affect the way the widget is rendered.
AG_WIDGET_FOCUSABLEThe widget is allowed to grab the focus; normally set by AG_WidgetSetFocusable(). Note that the widget may still become "focused" if child widgets are attached to it and one of them happens to grab focus.
AG_WIDGET_UNFOCUSED_MOTIONReceive mouse-motion events unconditionally (focus is required by default).
AG_WIDGET_UNFOCUSED_BUTTONUPReceive all mouse-button-up() (mouse button release) events unconditionally.
AG_WIDGET_UNFOCUSED_BUTTONDOWNReceive all mouse-button-up() (mouse button press) events unconditionally.
AG_WIDGET_UNFOCUSED_KEYDOWNReceive key-down() (key press) events unconditionally (focus is required by default).
AG_WIDGET_UNFOCUSED_KEYUPReceive key-up() (key release) events unconditionally (focus is required by default).
AG_WIDGET_CATCH_TABWhen the user presses the TAB key, generate normal key-down() and key-up() events. Without this flag, TAB is used to change the focus to the next widget.
AG_WIDGET_NOSPACINGAdvise parent container to disable spacing and padding (per standard box model), for this widget.
AG_WIDGET_USE_TEXTAllow draw(), size_request() and size_allocate() to use AG_TextRender(3) and AG_TextSize(3). Agar will automatically save/restore the font engine state according to the widget's computed style settings. Enables reception of the "font-changed" event.
AG_WIDGET_USE_OPENGLEstablish a separate OpenGL context for the widget. Before the draw() routine is invoked, Agar will automatically save/restore the GL_PROJECTION, GL_MODELVIEW and GL_TEXTURE matrices along with GL attributes GL_TRANSFORM_BIT, GL_VIEWPORT_BIT and GL_TEXTURE_BIT. Enables reception of "widget-reshape", "widget-overlay" and "widget-underlay" events.
AG_WIDGET_USE_MOUSEOVERDetect cursor motion over the widget's area; update the AG_WIDGET_MOUSEOVER flag and generate "mouse-over" events accordingly.

SEE ALSO

AG_Cursor(3), AG_KeyMod(3), AG_KeySym(3), AG_Rect(3), AG_StyleSheet(3), AG_Surface(3), AG_Variable(3), AG_WidgetPrimitives(3), AG_Window(3)

HISTORY

The AG_Widget interface first appeared in Agar 1.0. Widget-level variable bindings have been replaced by generic AG_Variable(3) pointers in Agar 1.3.4. The Actions interface first appeared in Agar 1.4. The AG_WIDGET_USE_OPENGL feature first appeared in Agar 1.5.

Csoft.net ElectronTubeStore.com