Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_WIDGET(3)	       FreeBSD Library Functions Manual		  AG_WIDGET(3)

NAME
     AG_Widget -- agar widget framework

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

DESCRIPTION
     An	Agar graphical user interface is described as a	tree of	widgets	(i.e.,
     structures	derived	from AG_Widget).

     A widget object is	always attached	(via AG_ObjectAttach(3)) to a parent
     container widget.	Some container widgets (such as	AG_Box(3) or
     AG_Window(3)) are designed	as general-purpose container widgets.  Other
     widgets (such as AG_FileDlg(3)) will internally create, attach and	posi-
     tion a specific set of child widgets to create a complex, easily re-us-
     able dialog (Agar developers are encouraged to create custom widgets us-
     ing this technique).

     The AG_Widget structure is	derived	from AG_Object(3).  Using Agar's Ob-
     ject system, custom widgets are easily implemented	(or derived from ex-
     isting widget classes) as part of user applications.  Agar	widgets	are
     extensively re-used.  The Object system also provides the AG_Event(3)
     system and	the AG_Variable(3) interface which is the basis	of widget
     bindings (see BINDINGS section below).

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;

     The draw()	operation renders the widget to	the display.  Throughout the
     documentation, the	draw() operation is referred to	as the `rendering
     context', and some	functions (such	as AG_WidgetBlitSurface()) are not
     safe to invoke in any other context.

     The size_request()	option queries the widget for an initial, preferred
     geometry, without any guarantee that the request will be satisfied.  For
     example, a	AG_Label(3) widget might return	the expected size in pixels of
     the rendered label's text.

     The size_allocate() function is called whenever the widget	has been allo-
     cated a new size or position within its parent container.	The
     AG_SizeAlloc parameter specifies the new allocation.  It is also safe to
     assume that when size_allocate is invoked,	the w, h, x, y members of the
     AG_Widget structure are already set to the	new allocated position and
     size.

     The size_allocate() routine of a container	widget is responsible for po-
     sitioning and dimensioning	of child widgets attached to it	(by calling
     AG_WidgetSizeAlloc() on them -- see SIZING	section	below).	 The function
     should return 0 on	success	or -1 to flag the widget as "undersize", dis-
     abling further calls to draw().

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)

     The AG_Expand() function arranges for the widget to expand, filling all
     available area in its parent container widget.  AG_ExpandHoriz() and
     AG_ExpandVert() cause the widget to expand	to fill	available space	hori-
     zontally or vertically.

     Note that most widget constructors	recognize AG_FOO_EXPAND, AG_FOO_HFILL
     and AG_FOO_VFILL option flags.  Setting these flags is equivalent to
     calling AG_Expand(), AG_ExpandHoriz() and AG_ExpandVert(),	respectively.

     The AG_WidgetSizeReq() function 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 con-
     tainer widget implementation, in order to size and	position the child
     widgets attached to the container (if you must set	widget geometries ex-
     plicitely,	use either the AG_Fixed(3) container, or create	your own con-
     tainer 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 wid-
     get from the specified AG_Rect.  These functions are typically only used
     in	the context of the size_request() and size_allocate() routines of con-
     tainer widgets.

     AG_WidgetUpdate() requests	an update of the computed coordinates and ge-
     ometries 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 cur-
     rent "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).

     void 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() specifies whether the widget should be allowed to
     receive focus (1 =	accept focus, 0	= reject focus).  The default is to
     reject focus.  Further AG_WidgetFocus() calls on a	widget rejecting focus
     will return 0.

     The AG_WidgetFocus() function gives focus to the given widget (and	all of
     its parent	widgets, up to the parent window if there is one).
     AG_WidgetFocus() returns 1	on success and 0 if the	widget cannot gain fo-
     cus (i.e.,	AG_WIDGET_FOCUSABLE is not set).  If the widget	is already fo-
     cused, the	function is a no-op and	returns	1.

     AG_WidgetUnfocus()	removes	the focus state	from the given widget and its
     children (but not the parent window 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 wid-
     get 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 functions manage blitting of	graphical surfaces.  They are designed
     specifically for use in GUI widgets.  The AG_WidgetBlit*()	routines must
     all be invoked from rendering context (i.e., the draw operation of	wid-
     gets), and	may not	be used	in any other context.

     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 in-
     terface 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	sur-
     face 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 con-
     text, 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	equiv-
     alent 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 tex-
     ture 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 rectan-
     gle 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
     Agar widgets can be configured to directly	access data of specific	types.
     For example, AG_Slider(3) provides	a binding called `value', which	(in
     the current implementation) supports the standard integer and floating-
     point types.  Connecting `value' to an integer or floating	point variable
     allows the	user to	directly set the value of the variable with the	need
     for tedious callback routines.  Similarly,	AG_Textbox(3) connects to a
     text buffer.  It is also possible to configure `function' bindings	such
     that the value is evaluated from a	provided function every	time the vari-
     able is retrieved.

     Widget bindings are established using the AG_BindFoo(), AG_BindFooFn()
     and AG_BindFooMp()	functions, see AG_Variable(3) for more information.

     Bindings are specifically documented in the API reference.	 Manual	pages
     for standard Agar widgets include a "BINDINGS" section with a list	of
     bindings supported	by each	widget,	their supported	data types and ef-
     fects.

     Since the value of	bindings associated with a widget often	dictates the
     way the widget is rendered	(e.g., AG_Button(3) is drawn as	a pressed but-
     ton if its	`state'	binding	is 1), Agar provides a built-in	facility to
     monitor binding values and	request	a video	update whenever	the value
     changes:

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 automati-
     cally 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 uncondition-
     ally 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_Display *view, const char *name)

     AG_Widget * AG_WidgetFindFocused(AG_Window	*win)

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

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

     AG_ParentWindow() returns a pointer to the	parent AG_Window(3) for	the
     given widget.  If the widget is unattached, NULL is returned.  The
     pointer is	only valid as long as the widget's parent VFS is locked.

     The AG_WidgetFind() function searches for a given widget by name, given
     an	absolute path, and returns a pointer to	the widget, or NULL.
     AG_WidgetFind() works differently from the	generic	AG_ObjectFind(3) func-
     tion, in that widgets not effectively attached to the VFS may be included
     in	the search (for	example, widgets attached to AG_Notebook(3) tabs).

     AG_WidgetFindFocused() recursively	searches win for a widget holding fo-
     cus.  Where multiple widgets may be holding focus,	widgets	found deepest
     in	the tree have priority over their parents.  AG_WidgetFindFocused() re-
     turns NULL	if no widget is	focused.

     AG_WidgetFindPoint() searches for a widget	matching the given class mask
     enclosing the point specified in display (pixel) coordinates.  The
     AG_WidgetFindRect() variant requires that the widget enclose the speci-
     fied rectangle.

     The pointer returned by AG_WidgetFind*(), should be considered valid only
     as	long as	the parent VFS remains 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 rectan-
     gle will be the intersection of all rectangles on this stack.
     AG_PushClipRect() and AG_PopClipRect() must be invoked in rendering con-
     text.

     The AG_WidgetDraw() routine renders a widget to the display.  It is typi-
     cally 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 visi-
     bility 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 (equiva-
     lent 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-family   Font	face specification ("Courier", "Terminal").
     font-size	   Font	size in	points ("10pts") or ratio ("50%").
     font-weight   Font	weight,	either "bold" or "normal".
     font-style	   Font	style, either "italic" or "normal".
     color	   Main	color of the widget.  Colors may be specified as un-
		   signed 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-color	   Color for rendered text.
     line-color	   Color for line drawings.
     shape-color   Color for polygons and other	filled shapes.
     border-color  Color 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	spe-
     cific 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 bind-
     ings 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 but-
     ton 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 ef-
     fect.  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() vari-
     ant 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 lo-
	 cal 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 posi-
	 tion of the mouse cursor.  The	buttons	argument is a bitmask repre-
	 senting 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_HFILL		      Hint to container	widgets	that in	a ver-
				      tical packing, this widget can expand to
				      fill all remaining space.

     AG_WIDGET_VFILL		      Hint to container	widgets	that in	a hor-
				      izontal packing, this widget can expand
				      to fill all remaining space.

     AG_WIDGET_HIDE		      Disable rendering	of this	widget.

     AG_WIDGET_VISIBLE		      This widget and its parent window	are
				      both currently visible (read-only).

     AG_WIDGET_UNDERSIZE	      Disable rendering	of this	widget because
				      it was determined	to have	a zero-valued
				      geometry (read-only, set by
				      AG_WidgetSizeAlloc()).

     AG_WIDGET_DISABLED		      Advise 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_MOUSEOVER	      A	mouse cursor currently intersects the
				      widget's area (read-only;	updated	inter-
				      nally if the AG_WIDGET_USE_MOUSEOVER
				      flag is set).  This flag may affect the
				      way the widget is	rendered.

     AG_WIDGET_FOCUSABLE	      The 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_MOTION	      Receive `mouse-motion' events uncondi-
				      tionally (focus is required by default).

     AG_WIDGET_UNFOCUSED_BUTTONUP     Receive all mouse-button-up() (mouse
				      button release) events unconditionally.

     AG_WIDGET_UNFOCUSED_BUTTONDOWN   Receive all mouse-button-up() (mouse
				      button press) events unconditionally.

     AG_WIDGET_UNFOCUSED_KEYDOWN      Receive key-down() (key press) events
				      unconditionally (focus is	required by
				      default).

     AG_WIDGET_UNFOCUSED_KEYUP	      Receive key-up() (key release) events
				      unconditionally (focus is	required by
				      default).

     AG_WIDGET_CATCH_TAB	      When the user presses the	TAB key, gen-
				      erate normal key-down() and key-up()
				      events.  Without this flag, TAB is used
				      to change	the focus to the next widget.

     AG_WIDGET_NOSPACING	      Advise parent container to disable spac-
				      ing and padding (per standard box
				      model), for this widget.

     AG_WIDGET_USE_TEXT		      Allow draw(), size_request() and
				      size_allocate() to use AG_TextRender(3)
				      and AG_TextSize(3).  Agar	will automati-
				      cally save/restore the font engine state
				      according	to the widget's	computed style
				      settings.	 Enables reception of the
				      "font-changed" event.

     AG_WIDGET_USE_OPENGL	      Establish	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_MOUSEOVER	      Detect 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 vari-
     able 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.

FreeBSD	13.0			August 20, 2002			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | CLASS OPERATIONS | SIZING | INPUT STATE | FOCUS STATE | COORDINATES | BLITTING SURFACES | BINDINGS | CONTROLLING REDRAW | WIDGET QUERIES | RENDERING CONTROL | STYLE PROPERTIES | STANDARD WIDGET ACTIONS | EVENTS | STRUCTURE DATA | FLAGS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Widget&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help