AG_Window object describes an Agar window, the base container for Agar widgets.
AG_Widget(3) objects form a tree structure attached to a parent
AG_Window. Agar windows are attached to a 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 (using 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 visible using AG_WindowShow().
Windows are destroyed by a single call to AG_ObjectDetach(3). This effectively puts the window in a garbage-collection queue (the actual freeing of resources will occur only after the end of the current event processing cycle).
|AG_Object(3)-> AG_Widget(3)-> AG_Window.|
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_WindowNewUnder() variant creates a new window and attaches it to an alternate AG_Driver(3) instance drv.
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.
AG_WindowSetCloseAction() sets the action to perform on "window-close":
To perform a different action, a custom event handler routine can be set for the "window-close" event (see the EVENTS section).
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:
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 WM).
If the tiling argument is 1, the AG_WINDOW_TILING flag is set (see FLAGS section). With tiling enabled, the WM will try to avoid overlap between existing windows.
AG_WindowMove() moves the window to a new position xRel, yRel relative to the window's current position.
AG_WindowSetGeometry() 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_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 WMs). The argument can range from 0.0 (transparent) to 1.0 (opaque). This function is not available in integer-only builds.
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). This feature is not available in integer-only builds.
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 dependent of winParent. Detaching the parent window (using AG_ObjectDetach(3)) will cause dependent child windows to be detached implicitely. Child windows also inherit the style properties from their parent. The AG_WindowDetach() function detaches the window from its parent window.
AG_WindowMakeTransient() registers winTrans as a dependent and transient window for winParent. The effects of transient window state are dependent 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 displaced 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 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. Also see: AG_WidgetUpdate(3).
DRIVER / EVENT LOOP INTERFACE
The following functions should be called only from application-specific
event loops, or low-level driver code.
AG_EventLoop(3) invokes them internally.
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 redraw.
The AG_WindowProcessQueued() routine processes any queued AG_ObjectDetach(3), AG_WindowShow(3) or AG_WindowHide(3) operation.
AG_WindowShow() makes a window visible and broadcasts the "widget-shown" event to win and its children.
AG_WindowHide() makes a window invisible and broadcasts the "widget-hidden" event to win and its children.
Note that AG_WindowHide() keeps the window and its resources in memory. To destroy a window and release its resources, one should use AG_ObjectDetach(3).
AG_WindowIsVisible() returns the current visibility status of a window. A value of 0 means the window is invisible, 1 means it is visible.
AG_WindowLower() lowers the window to the bottom of the stack.
AG_WindowRaise() raises the window to the top of the stack so that it is not obscured by other sibling windows.
The focus state controls the default filtering of events as well as the
behavior and cosmetic appearance of some widgets.
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 occurred. 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_WindowFind() searches all AG_Driver(3) instances for a named window a returns a pointer to it on success or NULL if none was found.
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.
The AG_CloseFocusedWindow() routine requests closure of the currently focused window, if any.
WINDOW MANAGER HINTS
wmType field of
AG_Window hints at the function of the window.
This setting is used by underlying WMs to tweak window appearance and behavior
The values correspond to those specified in Extended Window Manager Hints
(EWMH) version 1.4.
The GUI system may send
AG_Window objects the following events:
The following code fragment creates an Agar window containing a label
and a row of buttons.
It will be positioned and dimensioned automatically:
The following code fragment creates an empty Agar window with a green background, centers it and sets an explicit size of 320x240:
|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. In Agar 1.6.0, the AG_WindowFind() call was added and AG_WindowNewSw() was renamed AG_WindowNewUnder(). AG_WindowSetPadding() and AG_WindowSetSpacing() were deprecated in favor of the "padding" and "spacing" style attributes.|