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 is the basic container for Agar widgets; it is
itself derived from the
AG_Widget(3) structure, and is attached to a parent
AG_Driver(3) which provides an interface to the low-level graphics system in use.
Where the low-level graphics system actually involves a window manager
(e.g., when using X Windows), each
AG_Window object is attached to a dedicated
AG_Driver instance.
Where there are no underlying window managers involved (e.g., when writing
to a plain framebuffer), Agar provides an internal "window manager" for the
framebuffer, and multiple
AG_Window objects can attach to a single
AG_Driver instance representing the framebuffer.
Similarly to AG_Box(3), AG_Window acts like a general-purpose widget container. When Agar provides an internal window manager, a AG_Titlebar(3) widget is attached by default to the window when it is created. It not usually necessary to provide explicit dimensions in pixels when creating new Agar windows. Widgets are queried for preferred dimensions when the window is first displayed. In cases where the "best" widget dimensions cannot be guessed properly at initialization time, it is customary for Agar widgets to provide one or more "size hint" routine. Commonly used containers 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() allocates, initializes and attach a new window. The AG_WindowNewNamed() variant creates a new named window. 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 " / ". See FLAGS for available flags options. 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_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)). |
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:
|
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. |
