Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.
SYNOPSIS
#include <agar/core.h> #include <agar/gui.h> |
DESCRIPTION
|
The
AG_Window object describes an Agar window, the base container widget for other
Agar widgets.
The
AG_Widget(3) objects form a tree structure attached to a parent
AG_Window. Every AG_Window is associated with an AG_Driver(3), which provides an interface to the low-level graphics system (the "Agar driver") in use. If the Agar driver interfaces with some type of window manager (as with so-called "multiple-window" drivers including "glx" and "wgl"), the associated AG_Driver is unique to the window. If there is no underlying window manager (as with so-called "single-window" drivers including "sdlfb" and "sdlgl"), Agar provides a simple built-in window manager. Widgets can be attached directly to the AG_Window object, and AG_Window will behave like a standard, vertical AG_Box(3). Default Agar window dimensions are usually determined automatically (by a recursive query on the window's AG_Widget tree). The widget objects are expected to set a proper default size when it can be determined automatically, or otherwise provide a suitable API so applications can request widget-specific "size hints". Other than AG_Window itself, standard container widgets include AG_Box(3), AG_VBox(3) and AG_HBox(3) for automatic horizontal and vertical packing, AG_Fixed(3) for explicit pixel-precision packing, AG_Pane(3) for dual partitions and AG_Notebook(3) for notebook-style display. |
INHERITANCE HIERARCHY
| AG_Object(3)-> AG_Widget(3)-> AG_Window. |
INTERFACE
|
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 contain 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 applications that wish to use multiple single-window drivers concurrently. The AG_WindowSetCaption() function sets the text displayed by the titlebar (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 window. 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 duplicate the provided surface, which must remain valid until the window is destroyed. The AG_WindowSetCloseAction() function specifies the action that should be performed when the user deletes the window through the window manager.
To set an arbitrary callback routine, simply configure an window-close event handler (see EVENTS). 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 widgets from each other. The default is 2 pixels. Note that fn AG_WindowSetSpacingonly affects the widgets which are directly attached to the window. For widgets that are attached to container 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-specific. 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 position, per the specified alignment. Possible values for the alignment argument are: AG_WINDOW_TL AG_WINDOW_TC AG_WINDOW_TR AG_WINDOW_ML AG_WINDOW_MC AG_WINDOW_MR AG_WINDOW_BL AG_WINDOW_BC AG_WINDOW_BR The special value AG_WINDOW_ALIGNMENT_NONE leaves the choice of the initial window position up to the underlying window manager (possibly Agar itself, or an external window manager). If the cascade argument is 1, the window position is slightly incremented or decremented at each call (depending on the preferred alignment). The AG_WindowSetGeometry() function moves/resizes a window to the specific 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 alignment (see description of AG_WindowSetPosition() for the possible values). The parameters of AG_WindowSetGeometryAlignedPct() are given in percentage 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 compositing 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 seconds). AG_WindowMaximize() and AG_WindowMinimize() maximizes and minimizes the window, respectively. AG_WindowUnmaximize() and AG_WindowUnminimize() does the opposite. The AG_WindowAttach() function arranges for pwin to be the logical parent window of win, such that win is automatically destroyed when pwin is detached (through AG_ObjectDetach(3)). If win has been previously attached to another window, it is reparented accordingly. The AG_WindowDetach() function removes win from its logical parent window pwin. The AG_WindowUpdate() function updates the coordinates and geometries of all widgets attached to win. AG_WindowUpdate() 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_Window structure. When this function is used in the context of a widget implementation, AG_WidgetUpdate(3) is preferred. AG_WindowDraw() renders the window to the display. Calls to AG_WindowDraw() must be made in GUI rendering context (i.e., enclosed between calls to AG_BeginRendering(3) and AG_EndRendering(3)). Typically, this happens in an event loop routine (such as the stock AG_EventLoop(3)). The AG_WindowIntersect() function tests whether the specified display coordinates intersect one or more Agar windows. The function returns the number of overlapping windows at the given coordinates. This function is only useful with single-window drivers. |
VISIBILITY
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. |
FOCUS STATE
|
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.
The AG_WindowFocus() function sets the focus on the given window. If the currently focused window has the AG_WINDOW_KEEPABOVE flag set, this function 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 cancelled. 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 preceeding if reverse is 1) the widget currently holding focus inside of win. By default, Agar maps the "TAB" key to this function. |
STRUCTURE DATA
For the
AG_Window object:
|
FLAGS
For the
AG_Window object:
|
EVENTS
The GUI system may send
AG_Window objects the following events:
|
EXAMPLES
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");
}
AG_WindowShow(win);
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_WindowShow(win); |
SEE ALSO
| AG_Intro(3), AG_Icon(3), AG_Cursor(3), AG_View(3), AG_Widget(3) |
HISTORY
| The AG_Window system first appeared in Agar 1.0. |
