SYNOPSIS

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

DESCRIPTION

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 a parent
AG_Driver(3) which provides a bridge between the Agar GUI system and the user's preferred
graphics platform / backend.

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).

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":

AG_WINDOW_HIDE

Hide the window.
This is the default for named windows created with
AG_WindowNewNamed().

AG_WINDOW_DETACH

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

AG_WINDOW_IGNORE

Ignore the close request.

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.
The standard
AG_EventLoop(3) invokes them internally.

VISIBILITY

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.

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.

voidAG_WindowFocus (AG_Window *win)

intAG_WindowFocusNamed (const char *name)

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

AG_Window *AG_WindowFind (const char *name)

AG_Window *AG_WindowFindFocused (void)

intAG_WindowIsFocused (AG_Window *win)

voidAG_WindowCycleFocus (AG_Window *win, int reverse)

voidAG_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 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.

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

WINDOW MANAGER HINTS

The
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
details.
The values correspond to those specified in Extended Window Manager Hints
(EWMH) version 1.4.

FLAGS

For the
AG_Window object:

AG_WINDOW_TILING

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

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.

AG_WINDOW_NOBACKGROUND

Don't fill the window background prior to rendering 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 WMs, this may imply
AG_WINDOW_NOBORDERS.

AG_WINDOW_NOBORDERS

Don't draw decorative window borders.
Under some WMs, this may imply
AG_WINDOW_NOTITLE.

AG_WINDOW_PLAIN

Create a completely undecorated window (alias for
AG_WINDOW_NOTITLE and
AG_WINDOW_NOBORDERS).

AG_WINDOW_NOHRESIZE

Disable horizontal window resize control.

AG_WINDOW_NOVRESIZE

Disable vertical window resize control.

AG_WINDOW_NORESIZE

Alias for
AG_WINDOW_NO[HV]RESIZE.

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_NOBUTTONS

Alias for
AG_WINDOW_NOCLOSE, AG_WINDOW_NOMINIMIZE and
AG_WINDOW_NOMAXIMIZE.

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_NOCURSORCHG

Deny any cursor change requested by widgets attached to this window.
This flag is automatically set whenever a window hidden, and cleared a
window is made visible.

EVENTS

The GUI system may send
AG_Window objects the following events:

window-close (void)

Request to close the window.
Set by
AG_WindowSetCloseAction(). The default is to
hide the window (for anonymous windows created by
AG_WindowNew()) or to
detach the window (for those created by
AG_WindowNewNamed()). It is safe for a handler to ignore the request or to create new
windows (e.g., confirmation dialogs) in response.

SEE ALSO

HISTORY

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.