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

FreeBSD Manual Pages


home | help
AG_WINDOW(3)		 BSD Library Functions Manual		  AG_WINDOW(3)

     AG_Window -- agar window system

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

     The AG_Window object describes an Agar window, the	base container for
     Agar widgets.  The	AG_Widget(3) objects form a tree structure attached to
     a parent AG_Window.  Agar windows are attached to some parent
     AG_Driver(3) which	provides a bridge between the Agar GUI system and the
     user's preferred graphics platform	/ backend.

     Widgets can be attached to	the AG_Window object itself (it	will behave
     like a standard, vertical AG_Box(3)).  Agar's standard toolkit includes a
     variety of	other container	widgets, such as AG_Box(3), AG_Fixed(3),
     AG_Pane(3), AG_Notebook(3)	and AG_Scrollview(3).

     The dimensions of new Agar	windows	is best	determined automatically (us-
     ing recursive widget size requests	which take resolution, font sizes,
     etc. into account).  Agar widgets are expected to set a proper default
     size whenever it can be determined	automatically, or otherwise provide a
     suitable application-level	API for	"size hints".

     Newly created windows (as returned	by AG_WindowNew()) must	be made	visi-
     ble using AG_WindowShow().

     Windows are destroyed by a	single call to AG_ObjectDetach(3).  The	detach
     operation actually	places the window on a queue, and actual freeing will
     occur after the end of the	current	event processing cycle.	 After a win-
     dow has been successfully detached, the `window-detached' event is

     AG_Object(3) -> AG_Widget(3) -> AG_Window.

     AG_Window * AG_WindowNew(Uint flags)

     AG_Window * AG_WindowNewNamed(Uint	flags, const char *format, ...)

     AG_Window * AG_WindowNewNamedS(Uint flags,	const char *name)

     AG_Window * AG_WindowNewSw(AG_DriverSw *drv, Uint flags)

     void AG_WindowSetCaption(AG_Window	*win, const char *format, ...)

     void AG_WindowSetCaptionS(AG_Window *win, const char *text)

     void AG_WindowSetIcon(AG_Window *win, AG_Surface *surface)

     void AG_WindowSetIconNODUP(AG_Window *win,	AG_Surface *surface)

     void AG_WindowSetCloseAction(AG_Window *win, eum ag_window_close_action

     void AG_WindowSetPadding(AG_Window	*win, int paddingLeft, int
     paddingRight, int paddingTop, int paddingBottom)

     void AG_WindowSetSpacing(AG_Window	*win, int spacing)

     void AG_WindowSetSideBorders(AG_Window *win, int pixels)

     void AG_WindowSetBottomBorder(AG_Window *win, int pixels)

     void AG_WindowSetPosition(AG_Window *win, enum ag_window_alignment
     alignment,	int tiling)

     void AG_WindowSetGeometry(AG_Window *win, int x, int y, int w, int	h)

     void AG_WindowSetGeometryRect(AG_Window *win, AG_Rect rect, int bounded)

     void AG_WindowSetGeometryAligned(AG_Window	*win, enum ag_window_alignment
     alignment,	int w, int h)

     void AG_WindowSetGeometryAlignedPct(AG_Window *win, enum
     ag_window_alignment alignment, int	wPct, int hPct)

     void AG_WindowSetGeometryBounded(AG_Window	*win, int x, int y, int	w, int

     void AG_WindowSetGeometryMax(AG_Window *win)

     void AG_WindowSetMinSize(AG_Window	*win, int w, int h)

     void AG_WindowSetMinSizePct(AG_Window *win, int pct)

     int AG_WindowSetOpacity(AG_Window *win, float opacity)

     void AG_WindowSetFadeIn(AG_Window *win, float fadeTime, float fadeIncr)

     void AG_WindowSetFadeOut(AG_Window	*win, float fadeTime, float fadeIncr)

     void AG_WindowSetZoom(AG_Window *win, int zoomLvl)

     void AG_ZoomIn(void)

     void AG_ZoomOut(void)

     void AG_ZoomReset(void)

     void AG_WindowMaximize(AG_Window *win)

     void AG_WindowUnmaximize(AG_Window	*win)

     void AG_WindowMinimize(AG_Window *win)

     void AG_WindowUnminimize(AG_Window	*win)

     void AG_WindowAttach(AG_Window *winParent,	AG_Window *winChld)

     void AG_WindowDetach(AG_Window *winParent,	AG_Window *winChld)

     void AG_WindowMakeTransient(AG_Window *winParent, AG_Window *winTrans)

     void AG_WindowPin(AG_Window *winParent, AG_Window *winToPin)

     void AG_WindowUnpin(AG_Window *win)

     void AG_WindowUpdate(AG_Window *win)

     The AG_WindowNew()	function creates a new Agar window using the default
     AG_Driver(3), returning a pointer to the newly created AG_Window or NULL
     on	failure.  If the default driver	is a single-window driver, the new
     Agar window is attached to	the AG_Driver object.  If the default driver
     is	a multiple-window driver, a new	AG_Driver object instance is created
     for the new window.  See the FLAGS	section	below for a description	of the
     available flags options.

     The AG_WindowNewNamed() variant creates an	Agar window with a unique name
     identifier.  If a window of the same name exists, AG_WindowNewNamed()
     only moves	the focus to that window, and returns NULL.  The name may con-
     tain any printable	character, except `/'.

     The AG_WindowNewSw() variant creates a new	window and attaches it to the
     specified AG_DriverSw(3) object.  This function is	only useful to appli-
     cations that wish to use multiple single-window drivers concurrently.

     The AG_WindowSetCaption() function	sets the text displayed	by the title-
     bar (if there is one).  If	the string exceeds AG_LABEL_MAX	bytes in
     length, it	is truncated.

     The AG_WindowSetIcon() function configures	an alternate icon for the win-
     dow.  This	icon will be used by Agar's internal window manager whenever
     the window	is minimized.  The given surface will be duplicated and
     rescaled if necessary.  The AG_WindowSetIconNODUP() variant does not du-
     plicate the provided surface, which must remain valid until the window is

     The AG_WindowSetCloseAction() function specifies the action to perform
     when the window is	requested to be	closed.	 Accepted arguments include:

     AG_WINDOW_HIDE	Hide the window.  This is the default action for win-
			dows created with AG_WindowNewNamed().

     AG_WINDOW_DETACH	Detach and destroy the window.	This is	the default
			action for windows created with	AG_WindowNew().

     AG_WINDOW_IGNORE	Ignore the close request.

     To	perform	a different action, an event handler can be configured for the
     `window-close' and	`window-modal-close' events (see the EVENTS section).

     The AG_WindowSetPadding() function	defines	the space in pixels separating
     the widgets from the edges	of the window.

     The AG_WindowSetSpacing() function	defines	the space separating the wid-
     gets from each other.  The	default	is 2 pixels.

     Note that AG_WindowSetSpacing() only affects the widgets which are	di-
     rectly attached to	the window.  For widgets that are attached to con-
     tainer widgets, it	is the container widgets that define spacing, as well
     as	other aspects of widget	organization.  For instance, the AG_Box(3)
     container widget provides a AG_BoxSetSpacing() function .

     AG_WindowSetSideBorders() sets the	thickness of the left and right	window
     borders in	pixels.	 AG_WindowSetBottomBorder() sets the thickness of the
     bottom border.  The exact interpretation of this setting is theme-spe-
     cific.  The default for side borders is 0 (no side	borders).  If the win
     argument is NULL, the defaults are	set.

     The AG_WindowSetPosition()	function moves a window	to a standard posi-
     tion, per the specified alignment.	 Possible values for the alignment ar-
     gument are:


     The special value AG_WINDOW_ALIGNMENT_NONE	leaves the choice of the ini-
     tial window position up to	the underlying window manager (possibly	Agar
     itself, or	an external window manager).

     If	the tiling argument is 1, the AG_WINDOW_TILING flag is set (see	FLAGS
     section).	With tiling enabled, the window	manager	will attempt to	avoid
     overlap between existing windows.

     The AG_WindowSetGeometry()	function moves/resizes a window	to the spe-
     cific position and	geometry, given	in pixels.  If a value of -1 is	passed
     for w or h, the window's default (or current) geometry is preserved.

     The AG_WindowSetGeometryRect() variant of AG_WindowSetGeometry() accepts
     a AG_Rect(3) argument.  The bounded argument specifies whether the	window
     should be limited to the available	view area.

     The AG_WindowSetGeometryAligned() variant assigns the window a specific
     size in pixels and	positions it according to the specified	window align-
     ment (see description of AG_WindowSetPosition() for the possible values).
     The parameters of AG_WindowSetGeometryAlignedPct()	are given in percent-
     age of current view area instead of pixels.  Calling these	functions with
     an	argument of AG_WINDOW_ALIGNMENT_NONE is	a no-op.

     The AG_WindowSetGeometryBounded() variant limits the window to the	view
     area (by default, windows can lie outside of the visible area).

     The AG_WindowSetGeometryMax() variant sets	the geometry to	the size of
     the display (without setting the AG_WINDOW_MAXIMIZED flag).

     The AG_WindowSetMinSize() routine sets the	minimum	window size in pixels.
     AG_WindowSetMinSizePct() sets the minimum window size in percentage of
     the requested (computed) size.

     AG_WindowSetOpacity() configures an overall per-window opacity (for com-
     positing window managers).	 The argument can range	from 0.0 (transparent)
     to	1.0 (opaque).

     For windows with the AG_WINDOW_FADEIN or AG_WINDOW_FADEOUT	flags,
     AG_WindowSetFadeIn() and AG_WindowSetFadeOut() can	be used	to configure
     the fade timing parameters.  During fade-in, the window opacity will be
     repeatedly	incremented by fadeIncr, over a	total period of	fadeTime (in

     The AG_WindowSetZoom() function sets the zoom level of the	window.	 The
     AG_ZoomIn(), AG_ZoomOut() and AG_ZoomReset() functions set	the zoom level
     for the currently focused window.	It is customary	to assign
     AG_GlobalKeys(3) shortcuts	to these functions.

     AG_WindowMaximize() and AG_WindowMinimize() maximizes and minimizes the
     window, respectively.  AG_WindowUnmaximize() and AG_WindowUnminimize()
     does the opposite.

     The AG_WindowAttach() function registers winChld as a child window	depen-
     dent of winParent.	 Detaching the parent window (using
     AG_ObjectDetach(3)) will cause dependent child windows to be detached im-
     plicitely.	 Child windows also inherit the	style properties from their
     parent.  The AG_WindowDetach() function detaches the window from its par-
     ent window.

     AG_WindowMakeTransient() registers	winTrans as a dependent	and transient
     window for	winParent.  The	effects	of transient window state are depen-
     dent on the underlying window system and window manager.  Under Motif,
     transient windows have no titlebar	buttons.  Under	TWM, transient windows
     are created without requesting that the user select an initial geometry.
     Detaching winParent (using	AG_ObjectDetach(3)) will cause winTrans	to be
     detached implicitely.

     The AG_WindowPin()	function "pins"	winToPin to the	parent window
     winParent.	 If the	parent window is moved,	the pinned window will be dis-
     placed along with it.  AG_WindowUnpin() unpins the	given window.

     The AG_WindowUpdate() function updates the	coordinates and	geometries of
     all widgets attached to win.  AG_WindowUpdate() should be called follow-
     ing 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_Window struc-
     ture.  Note: In widget implementation code, one should use
     AG_WidgetUpdate(3)	instead	of this	function.

     The following functions should be called only from	application-specific
     event loops, or low-level driver code.  The standard AG_EventLoop(3) in-
     vokes them	internally.

     void AG_WindowDraw(AG_Window *win)

     void AG_WindowDrawQueued(void)

     void AG_WindowProcessQueued(void)

     The AG_WindowDraw() function renders the specified	window (by calling the
     renderWindow() operation of the associated	AG_Driver(3)).	Calls to
     AG_WindowDraw() must be made in GUI rendering context, between
     AG_BeginRendering(3) and AG_EndRendering(3).

     AG_WindowDrawQueued() redraws any window marked as	dirty since the	last

     The AG_WindowProcessQueued() routine processes any	queued
     AG_ObjectDetach(3), AG_WindowShow(3) or AG_WindowHide(3) operation.

     void AG_WindowShow(AG_Window *win)

     void AG_WindowHide(AG_Window *win)

     int AG_WindowIsVisible(AG_Window *win)

     Newly created windows are invisible by default.  The AG_WindowShow()
     function makes the	specified window visible.  AG_WindowHide() makes a
     window invisible.

     Note that AG_WindowHide() only hides a window, without destroying its
     contents.	To properly detach and free a window, AG_ObjectDetach(3)
     should be used.

     AG_WindowIsVisible() returns the current visibility status	of a window.
     A value of	0 means	the window is invisible, 1 means it is visible.

     The focus state controls the default filtering of events as well as the
     behavior and cosmetic appearance of some widgets.	See the	"FOCUS STATE"
     section of	AG_Widget(3) for details.

     void AG_WindowFocus(AG_Window *win)

     int AG_WindowFocusNamed(const char	*name)

     int AG_WindowFocusAtPos(AG_DriverSw *drv, int x, int y)

     AG_Window * AG_WindowFindFocused(void)

     int AG_WindowIsFocused(AG_Window *win)

     void AG_WindowCycleFocus(AG_Window	*win, int reverse)

     void AG_CloseFocusedWindow(void)

     The AG_WindowFocus() function sets	the focus on the given window.	If the
     currently focused window has the AG_WINDOW_KEEPABOVE flag set, this func-
     tion becomes a no-op.  The	focus change may not be	immediate depending on
     the underlying graphics system.  A	`window-gainfocus' event is posted to
     the window	object after the focus change has occured.  If an argument of
     NULL is passed to AG_WindowFocus(), any planned change in focus is	can-

     AG_WindowFocusNamed() calls AG_WindowFocus() on the window	of the given
     name and returns 0	on success or -1 if the	window was not found.

     AG_WindowFocusAtPos() looks for a window at the specified coordinates in
     pixels, in	the video display associated with the given single-display
     driver drv	(see AG_DriverSw(3)).  If a window is found, AG_WindowFocus()
     is	called on it and 1 is returned.	 Otherwise, 0 is returned.

     AG_WindowFindFocused() returns a pointer to the window currently holding
     input focus, or NULL if there are none.  AG_WindowIsFocused() returns 1
     if	the window is currently	holding	focus, otherwise 0.

     AG_WindowCycleFocus() places the focus over the widget following (or pre-
     ceeding if	reverse	is 1) the widget currently holding focus inside	of
     win.  By default, Agar maps the "TAB" key to this function.

     The AG_CloseFocusedWindow() routine requests closure of the currently fo-
     cused window, if any.

     For the AG_Window object:

     Uint flags		 Option	flags (see FLAGS section below).

     int wmType		 Window	manager	hint describing	window function	(see

     int visible	 Visibility flag (1 = visible, 0 = hidden).  Read-only
			 (see AG_WindowShow() and AG_WindowHide()).

     int dirty		 Redraw	flag.  If set to 1, the	window will be redrawn
			 as soon as possible.

     AG_Titlebar *tbar	 Pointer to the	associated AG_Titlebar(3) widget, or
			 NULL if the window has	no titlebar.  Read-only.

     int wReq, hReq	 Ideal window geometry in pixels, as last computed
			 from the size_request() operation of its attached
			 widgets.  Read-only (see AG_WidgetSizeReq(3)).

     int wMin, hMin	 Suggested minimum window geometyry in pixels.	Read-
			 only (use AG_WindowSetMinSize()).

     AG_Window *parent	 Pointer to parent window, or NULL if there isn't any.
			 Read-only (see	AG_WindowAttach() and

     TAILQ subwins	 List of dependent child windows.  Read-only (see
			 AG_WindowAttach() and AG_WindowDetach()).

     AG_Icon *icon	 Pointer to the	floating AG_Icon(3) object if we are
			 using Agar's internal window manager, NULL otherwise.

     The wmType	field of AG_Window hints at the	function of the	window.	 This
     setting is	used by	underlying window managers to tweak window appearance
     and behavior details.  The	values correspond to those specified in	Ex-
     tended Window Manager Hints (EWMH)	version	1.4.

     enum ag_window_wm_type {
	     AG_WINDOW_WM_NORMAL,	 /* Normal, top-level window */
	     AG_WINDOW_WM_DESKTOP,	 /* Desktop feature */
	     AG_WINDOW_WM_DOCK,		 /* Dock or panel feature */
	     AG_WINDOW_WM_TOOLBAR,	 /* Toolbar torn off from main window */
	     AG_WINDOW_WM_MENU,		 /* Pinnable menu window */
	     AG_WINDOW_WM_UTILITY,	 /* Persistent utility window (e.g.,
					    a palette or a toolbox). */
	     AG_WINDOW_WM_SPLASH,	 /* Introductory splash	screen */
	     AG_WINDOW_WM_DIALOG,	 /* Dialog window */
	     AG_WINDOW_WM_DROPDOWN_MENU, /* Menubar-triggered drop-down	menu */
	     AG_WINDOW_WM_POPUP_MENU,	 /* Contextual popup menu */
	     AG_WINDOW_WM_TOOLTIP,	 /* Mouse hover	triggered tooltip */
	     AG_WINDOW_WM_NOTIFICATION,	 /* Notification bubble	*/
	     AG_WINDOW_WM_COMBO,	 /* Combo-box triggered	window */
	     AG_WINDOW_WM_DND		 /* Draggable object */

     For the AG_Window object:

     AG_WINDOW_TILING	      If no explicit window position is	specified,
			      choose a default position	using a	tiling window
			      manager algorithm.  This method honors the pre-
			      ferred window alignment, and also	attempts to
			      avoid overlap with other tiling windows.	Non-
			      tiling windows are ignored in the	calculation.

     AG_WINDOW_FADEIN	      Enable smooth fade-in for	compositing window

     AG_WINDOW_FADEOUT	      Enable smooth fade-out for compositing window
			      managers.	 Only effective	with AG_WindowHide()
			      (i.e., windows destroyed with AG_ObjectDetach(),
			      are not faded out).

     AG_WINDOW_MAXIMIZED      Window is	currently maximized (read-only).

     AG_WINDOW_MINIMIZED      Window is	currently minimized (read-only).

     AG_WINDOW_KEEPABOVE      Stay on top of other windows.

     AG_WINDOW_KEEPBELOW      Stay below other windows.

     AG_WINDOW_DENYFOCUS      Don't automatically grab focus in	response to a
			      `mouse-button-down' event	in the window area.

     AG_WINDOW_MODAL	      Place window in foreground and prevent other
			      windows from receiving input events until	the
			      modal window is closed.  If the modal window is
			      transient	(see AG_WindowMakeTransient()),	then
			      it is modal for its parent window, otherwise it
			      is application-modal.  If	a click	or touch event
			      is detected outside of the window	area, a
			      `window-modal-close' event will be raised.

     AG_WINDOW_NOBACKGROUND   Don't fill the window background prior to	ren-
			      dering its contents.

     AG_WINDOW_MAIN	      Break from AG_EventLoop(3) if this window	gets
			      destroyed.  Multiple windows may set this	flag,
			      in which case the	break will occur whenever the
			      last window is closed.

     AG_WINDOW_NOUPDATERECT   Disable automatic	updating of the	video region
			      corresponding to the window area (applicable to
			      framebuffer-based	graphics drivers only)

     AG_WINDOW_NOTITLE	      Create a window without a	titlebar.  Under some
			      window managers, this option may imply

     AG_WINDOW_NOBORDERS      Don't draw decorative window borders.  Under
			      some window managers, this option	may imply

     AG_WINDOW_PLAIN	      Create a completely undecorated window (alias

     AG_WINDOW_NOHRESIZE      Disable horizontal window	resize control.

     AG_WINDOW_NOVRESIZE      Disable vertical window resize control.


     AG_WINDOW_NOCLOSE	      Disable window close button in titelbar.

     AG_WINDOW_NOMINIMIZE     Disable minimize button in titlebar.

     AG_WINDOW_NOMAXIMIZE     Disable maximize button in titlebar.


     AG_WINDOW_HMAXIMIZE      Keep window scaled to the	display	width.

     AG_WINDOW_VMAXIMIZE      Keep window scaled to the	display	height.

     AG_WINDOW_NOMOVE	      User is not allowed to move the window.

     AG_WINDOW_NOCLIPPING     Disable the clipping rectangle over the window
			      area (enabled by default).

     AG_WINDOW_MODKEYEVENTS   Deliver discrete events to widget	when modifier
			      keys (CTRL, ALT, SHIFT) are pressed.

     AG_WINDOW_NOCURSORCHG    Deny any cursor change requested by widgets at-
			      tached to	this window.  This flag	is automati-
			      cally set	whenever a window hidden, and cleared
			      a	window is made visible.

     The GUI system may	send AG_Window objects the following events:

	 Request to close the window (sent by the user / underlying window
	 system).  The default behavior	is to hide named windows and detach
	 unnamed windows.  It is safe for an event handler to ignore the re-
	 quest,	or to create new windows (e.g.,	a confirmation dialog) in re-

     window-modal-close(int x, int y)
	 The window is modal (the AG_WINDOW_MODAL option is set), and a	click
	 or touch event	was detected outside of	its area (at given coordi-
	 nates).  By default, the request is ignored.

	 The window has	been successfully detached (as per a previous
	 AG_ObjectDetach(3) request).

	 The window is now visible.

	 The window is no longer visible.

	 The cursor has	entered	the window area.

	 The cursor has	left the window	area.

     The following code	fragment creates an Agar window	containing a row of
     buttons.  The window will be positioned and dimensioned automatically:

	   AG_Window *win;
	   AG_Box *box;
	   AG_Button *b[3];

	   win = AG_WindowNew(0);
	   box = AG_BoxNewHoriz(win, AG_BOX_EXPAND);
		   b[0]	= AG_ButtonNew(box, 0, "Foo");
		   b[1]	= AG_ButtonNew(box, 0, "Bar");
		   b[2]	= AG_ButtonNew(box, 0, "Baz");

     The following code	fragment creates an empty Agar window, centers it and
     sets an explicit size of 320x240:

	   AG_Window *win;

	   win = AG_WindowNew(0);
	   AG_WindowSetGeometryAligned(win, AG_WINDOW_MC, 320, 240);

     AG_Cursor(3), AG_Icon(3), AG_Intro(3), AG_View(3),	AG_Widget(3)

     The AG_Window system first	appeared in Agar 1.0.

BSD				August 21, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help