.\" Copyright (c) 2002-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_WINDOW 3 .Os Agar 1.7 .Sh NAME .Nm AG_Window .Nd agar window system .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_DriverGLX.png, "Multiple Agar windows") The .Nm object describes an Agar window, the base container for Agar widgets. The .Xr AG_Widget 3 objects form a tree structure attached to a parent .Nm . Agar windows are attached to a parent .Xr AG_Driver 3 which provides a bridge between the Agar GUI system and the user's preferred graphics platform / backend. .Pp Widgets can be attached to the .Nm object itself (it will behave like a standard, vertical .Xr AG_Box 3 ) . Agar's standard toolkit includes a variety of other container widgets, such as .Xr AG_Box 3 , .Xr AG_Fixed 3 , .Xr AG_Pane 3 , .Xr AG_Notebook 3 and .Xr AG_Scrollview 3 . .Pp 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". .Pp Newly created windows must be made visible by calling .Fn AG_WindowShow . .Pp Windows are destroyed by a single call to .Xr AG_ObjectDetach 3 . This effectively puts the window in a garbage-collection queue (to be freed later at the end of the current event-processing cycle). .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_Widget 3 -> .Nm . .Sh INTERFACE .nr nS 1 .Ft "AG_Window *" .Fn AG_WindowNew "Uint flags" .Pp .Ft "AG_Window *" .Fn AG_WindowNewNamed "Uint flags" "const char *format" "..." .Pp .Ft "AG_Window *" .Fn AG_WindowNewNamedS "Uint flags" "const char *name" .Pp .Ft "AG_Window *" .Fn AG_WindowNewUnder "AG_Driver *drv" "Uint flags" .Pp .Ft "void" .Fn AG_WindowSetCaption "AG_Window *win" "const char *format" "..." .Pp .Ft "void" .Fn AG_WindowSetCaptionS "AG_Window *win" "const char *text" .Pp .Ft "void" .Fn AG_WindowSetIcon "AG_Window *win" "AG_Surface *surface" .Pp .Ft "void" .Fn AG_WindowSetCloseAction "AG_Window *win" "AG_WindowCloseAction action" .Pp .Ft "void" .Fn AG_WindowSetSideBorders "AG_Window *win" "int pixels" .Pp .Ft "void" .Fn AG_WindowSetBottomBorder "AG_Window *win" "int pixels" .Pp .Ft "void" .Fn AG_WindowSetPosition "AG_Window *win" "enum ag_window_alignment alignment" "int tiling" .Pp .Ft "int" .Fn AG_WindowMove "AG_Window *win" "int xRel" "int yRel" .Pp .Ft "void" .Fn AG_WindowSetGeometry "AG_Window *win" "int x" "int y" "int w" "int h" .Pp .Ft "void" .Fn AG_WindowSetGeometryRect "AG_Window *win" "AG_Rect rect" "int bounded" .Pp .Ft "void" .Fn AG_WindowSetGeometryAligned "AG_Window *win" "enum ag_window_alignment alignment" "int w" "int h" .Pp .Ft "void" .Fn AG_WindowSetGeometryAlignedPct "AG_Window *win" "enum ag_window_alignment alignment" "int wPct" "int hPct" .Pp .Ft "void" .Fn AG_WindowSetGeometryMax "AG_Window *win" .Pp .Ft "void" .Fn AG_WindowSetMinSize "AG_Window *win" "int w" "int h" .Pp .Ft "void" .Fn AG_WindowSetMinSizePct "AG_Window *win" "int pct" .Pp .Ft "int" .Fn AG_WindowSetOpacity "AG_Window *win" "float opacity" .Pp .Ft "void" .Fn AG_WindowSetFadeIn "AG_Window *win" "float fadeTime" "float fadeIncr" .Pp .Ft "void" .Fn AG_WindowSetFadeOut "AG_Window *win" "float fadeTime" "float fadeIncr" .Pp .Ft "void" .Fn AG_WindowSetZoom "AG_Window *win" "int zoomLvl" .Pp .Ft "void" .Fn AG_ZoomIn "void" .Pp .Ft "void" .Fn AG_ZoomOut "void" .Pp .Ft "void" .Fn AG_ZoomReset "void" .Pp .Ft "void" .Fn AG_WindowMaximize "AG_Window *win" .Pp .Ft "void" .Fn AG_WindowUnmaximize "AG_Window *win" .Pp .Ft "void" .Fn AG_WindowMinimize "AG_Window *win" .Pp .Ft "void" .Fn AG_WindowUnminimize "AG_Window *win" .Pp .Ft void .Fn AG_WindowAttach "AG_Window *winParent" "AG_Window *winChld" .Pp .Ft void .Fn AG_WindowDetach "AG_Window *winParent" "AG_Window *winChld" .Pp .Ft void .Fn AG_WindowMakeTransient "AG_Window *winParent" "AG_Window *winTrans" .Pp .Ft void .Fn AG_WindowPin "AG_Window *winParent" "AG_Window *winToPin" .Pp .Ft void .Fn AG_WindowUnpin "AG_Window *win" .Pp .Ft void .Fn AG_WindowUpdate "AG_Window *win" .Pp .nr nS 0 The .Fn AG_WindowNew function creates a new Agar window using the default .Xr AG_Driver 3 . It returns a pointer to the newly created .Nm on success, or NULL on failure. See the .Sx FLAGS section below for a description of the available .Fa flags options. .Pp If the default driver is a single-window driver then .Fn AG_WindowNew attaches the newly created .Nm to its .Ft AG_Driver instance. If the default driver is a multiple-window driver, one unique .Ft AG_Driver instance is created and assigned to each window. .Pp The .Fn AG_WindowNewNamed variant creates an Agar window with a unique name identifier. If a window of the same name exists then .Fn AG_WindowNewNamed moves the focus to the existing window and returns NULL. The name may contain any printable character, except .Sq / . .Pp The .Fn AG_WindowNewUnder variant creates a new window and attaches it to an alternate .Xr AG_Driver 3 instance .Fa drv . .Pp .Fn AG_WindowSetCaption sets the title text (shown on the titlebar). .Pp .Fn AG_WindowSetIcon sets a custom icon for the window when iconified. It will be used by Agar's internal WM in single-window mode. It may be used by some multi-window drivers that support the feature. .Pp .Fn AG_WindowSetCloseAction sets the action to perform on "window-close": .Bl -tag -compact -width "AG_WINDOW_IGNORE " .It AG_WINDOW_DETACH Destroy the window. Default for anonymous windows. .It AG_WINDOW_HIDE Just hide the window. Default for named windows. .It AG_WINDOW_IGNORE Ignore the close request. .El .Pp To perform a different action, a custom event handler routine can be set for the "window-close" event (see the .Sx EVENTS section). .Pp .Fn AG_WindowSetSideBorders sets the thickness of the left and right window borders in pixels. .Fn AG_WindowSetBottomBorder sets the thickness of the bottom border. The default for side borders is 0 (no side borders). If the .Fa win argument is NULL then set global defaults to the given values. .Pp .Fn AG_WindowSetPosition defines an initial alignment for the window with respect to the desktop. Allowed values for .Fa alignment include: .Bd -literal .\" SYNTAX(c) 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 .Ed .Pp or the special value .Dv AG_WINDOW_ALIGNMENT_NONE , which lets the window manager choose a default position (the default). If .Fa tiling is 1 then .Fn AG_WindowSetPosition sets the .Dv AG_WINDOW_TILING flag such that the WM will attempt to avoid overlap between windows (see .Sx FLAGS section). .Pp .Fn AG_WindowMove moves the window to a new position .Fa xRel , .Fa yRel relative to the window's current position. .Pp .Fn AG_WindowSetGeometry moves/resizes a window to the specific position and geometry, given in pixels. If a value of -1 is passed for .Fa w or .Fa h , the window's default (or current) geometry is preserved. .Pp The .Fn AG_WindowSetGeometryRect variant of .Fn AG_WindowSetGeometry accepts a .Xr AG_Rect 3 argument. The .Fa bounded argument specifies whether the window should be limited to the available view area. .Pp The .Fn AG_WindowSetGeometryAligned variant assigns the window a specific size in pixels and positions it according to the specified window alignment (see description of .Fn AG_WindowSetPosition for the possible values). .Pp The .Fn AG_WindowSetGeometryAlignedPct variant accepts an argument given in percent of current view area (as opposed to absolute pixel coordinates). .Pp The .Fn AG_WindowSetGeometryMax variant sets the geometry to the size of the display (without setting the .Dv AG_WINDOW_MAXIMIZED flag). .Pp The .Fn AG_WindowSetMinSize routine sets the minimum window size in pixels. .Fn AG_WindowSetMinSizePct sets the minimum window size in percentage of the requested (computed) size. .Pp .Fn AG_WindowSetOpacity sets the overall per-window opacity (for compositing WMs). The argument can range from 0.0 (transparent) to 1.0 (opaque). .Pp For windows with the .Dv AG_WINDOW_FADEIN or .Dv AG_WINDOW_FADEOUT flags, .Fn AG_WindowSetFadeIn and .Fn AG_WindowSetFadeOut can be used to configure the fade timing. During fade-in, the opacity will be repeatedly incremented by .Fa fadeIncr over a total period of .Fa fadeTime seconds. .Pp .Fn AG_WindowSetZoom sets the zoom level of the window (and any of its child windows with the .Dv AG_WINDOW_INHERIT_ZOOM option set). .Pp The .Fn AG_ZoomIn , .Fn AG_ZoomOut and .Fn AG_ZoomReset routines call .Fn AG_WindowSetZoom to increase, decrease or reset the zoom level of the currently focused window. It is customary to assign .Xr AG_GlobalKeys 3 shortcuts to these routines. .Pp .Fn AG_WindowMaximize and .Fn AG_WindowMinimize maximizes and minimizes the window, respectively. .Fn AG_WindowUnmaximize and .Fn AG_WindowUnminimize does the opposite. .Pp The .Fn AG_WindowAttach call makes .Fa winChld a child window dependent of .Fa winParent . Detaching the parent window will cause the child window to be detached implicitely. Child windows also inherit the style properties from their parent. .Fn AG_WindowDetach removes .Fa winChld from .Fa winParent . .Pp .Fn AG_WindowMakeTransient registers .Fa winTrans as a dependent and transient window for .Fa 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 .Fa winParent will cause .Fa winTrans to be detached implicitely. .Pp The .Fn AG_WindowPin function "pins" .Fa winToPin to the parent window .Fa winParent . If the parent window is moved, the pinned window will be displaced along with it. .Fn AG_WindowUnpin unpins the given window. .Pp The .Fn AG_WindowUpdate routine updates the coordinates and geometries of all widgets attached to .Fa win . This routine should be called following .Xr AG_ObjectAttach 3 or .Xr AG_ObjectDetach 3 calls made in event context, or manual modifications of the .Va x , .Va y , .Va w , .Va h fields of the .Nm structure. See also: .Xr AG_WidgetUpdate 3 . .Sh DRIVER / EVENT LOOP INTERFACE The following calls are intended only for use by driver code and custom event loops. The standard .Xr AG_EventLoop 3 invokes them internally. .Pp .nr nS 1 .Ft void .Fn AG_WindowDraw "AG_Window *win" .Pp .Ft void .Fn AG_WindowDrawQueued "void" .Pp .Ft void .Fn AG_WindowProcessQueued "void" .Pp .nr nS 0 .Fn AG_WindowDraw renders window .Fa win (calling the .Fn renderWindow method of its .Xr AG_Driver 3 ) . This should be called only from GUI rendering context (between calls to .Xr AG_BeginRendering 3 and .Xr AG_EndRendering 3 ) . .Pp .Fn AG_WindowDrawQueued redraws any window previously marked as .Va dirty . .Pp .Fn AG_WindowProcessQueued processes any queued .Xr AG_ObjectDetach 3 , .Xr AG_WindowShow 3 or .Xr AG_WindowHide 3 operation. .Sh VISIBILITY .nr nS 1 .Ft void .Fn AG_WindowShow "AG_Window *win" .Pp .Ft void .Fn AG_WindowHide "AG_Window *win" .Pp .Ft int .Fn AG_WindowIsVisible "AG_Window *win" .Pp .Ft void .Fn AG_WindowLower "AG_Window *win" .Pp .Ft void .Fn AG_WindowRaise "AG_Window *win" .Pp .nr nS 0 .Fn AG_WindowShow makes a window visible and broadcasts the "widget-shown" event to .Fa win and its children. .Pp .Fn AG_WindowHide makes a window invisible and broadcasts the "widget-hidden" event to .Fa win and its children. .Pp Note that .Fn AG_WindowHide keeps the window and its resources in memory. To destroy a window and release its resources, one should use .Xr AG_ObjectDetach 3 . .Pp .Fn AG_WindowIsVisible returns the current visibility status of a window. A value of 0 means the window is invisible, 1 means it is visible. .Pp .Fn AG_WindowLower lowers the window to the bottom of the stack. .Pp .Fn AG_WindowRaise raises the window to the top of the stack so that it is not obscured by other sibling windows. .Sh FOCUS STATE The focus state controls the default filtering of events as well as the behavior and cosmetic appearance of some widgets. See the .Dq FOCUS STATE section of .Xr AG_Widget 3 for details. .Pp .nr nS 1 .Ft void .Fn AG_WindowFocus "AG_Window *win" .Pp .Ft int .Fn AG_WindowFocusNamed "const char *name" .Pp .Ft int .Fn AG_WindowFocusAtPos "AG_DriverSw *drv" "int x" "int y" .Pp .Ft "AG_Window *" .Fn AG_WindowFind "const char *name" .Pp .Ft "AG_Window *" .Fn AG_WindowFindFocused "void" .Pp .Ft "int" .Fn AG_WindowIsFocused "AG_Window *win" .Pp .Ft "void" .Fn AG_WindowCycleFocus "AG_Window *win" "int reverse" .Pp .Ft "void" .Fn AG_CloseFocusedWindow "void" .Pp .nr nS 0 .Fn AG_WindowFocus focuses on window .Fa win . A .Sq window-gainfocus event is posted to the window object after the focus change has occurred. If the currently focused window has the .Dv AG_WINDOW_KEEPABOVE flag set then this is a no-op. If an argument of NULL is given, then the previous request for focus change (if any) will be cancelled. .Pp .Fn AG_WindowFocusNamed calls .Fn AG_WindowFocus on the window of the given name and returns 0 on success or -1 if the window was not found. .Pp .Fn AG_WindowFocusAtPos looks for a window at the specified coordinates in pixels, in the video display associated with the given single-display driver .Fa drv (see .Xr AG_DriverSw 3 ) . If a window is found, .Fn AG_WindowFocus is called on it and 1 is returned. Otherwise, 0 is returned. .Pp .Fn AG_WindowFind searches all .Xr AG_Driver 3 instances for a named window a returns a pointer to it on success or NULL if none was found. .Pp .Fn AG_WindowFindFocused returns a pointer to the window currently holding input focus, or NULL if there are none. .Fn AG_WindowIsFocused returns 1 if the window is currently holding focus, otherwise 0. .Pp .Fn AG_WindowCycleFocus places the focus over the widget following (or preceeding if .Fa reverse is 1) the widget currently holding focus inside of .Fa win . By default, Agar maps the TAB key to this function. The .Va agDrivers VFS must be locked. .Pp The .Fn AG_CloseFocusedWindow routine requests closure of the currently focused window, if any. .Sh MISCELLANEOUS .nr nS 1 .Ft "AG_Window *" .Fn AG_About "void" .Pp .Ft "void" .Fn AG_ViewCapture "void" .Pp .nr nS 0 .Fn AG_About generates an "About Agar GUI" dialog box with copyright information for the Agar GUI library and core fonts (from .Pa gui/license.txt ) . .Pp .Fn AG_ViewCapture is only available with single-window drivers. It dumps the contents of the display surface to .Pa ~/./screenshot/. .Sh STRUCTURE DATA For the .Ft AG_Window object: .Bl -tag -width "AG_Window *parent " .It Ft Uint flags Option flags (see .Sx FLAGS section below). .It Ft int wmType Window manager hint describing window function (see .Sx WINDOW MANAGER HINTS below). .It Ft int visible Visibility flag (1 = visible, 0 = hidden). Read-only (see .Fn AG_WindowShow and .Fn AG_WindowHide ) . .It Ft int dirty Redraw flag. If set to 1, the window will be redrawn as soon as possible. .It Ft AG_Titlebar *tbar Pointer to the associated .Xr AG_Titlebar 3 widget, or NULL if the window has no titlebar. Read-only. .It Ft int wReq, hReq Ideal window geometry in pixels, as last computed from the .Fn size_request operation of its attached widgets. Read-only (see .Xr AG_WidgetSizeReq 3 ) . .It Ft int wMin, hMin Suggested minimum window geometry in pixels. Read-only (use .Fn AG_WindowSetMinSize ) . .It Ft AG_Window *parent Pointer to parent window, or NULL if there isn't any. Read-only (see .Fn AG_WindowAttach and .Fn AG_WindowDetach ) . .It Ft TAILQ subwins List of dependent child windows. Read-only (see .Fn AG_WindowAttach and .Fn AG_WindowDetach ) . .It Ft AG_Icon *icon Pointer to the floating .Xr AG_Icon 3 object if we are using Agar's internal window manager, NULL otherwise. Read-only. .El .Sh WINDOW MANAGER HINTS The .Va wmType field of .Nm 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. .Bd -literal .\" SYNTAX(c) 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 */ }; .Ed .Sh FLAGS For the .Ft AG_Window object: .Bl -tag -width "AG_WINDOW_NOUPDATERECT " .It 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 .Fn AG_WindowMakeTransient ) , then it is modal for its parent window, otherwise it is application-modal. .It AG_WINDOW_KEEPABOVE Stay on top of other windows. .It AG_WINDOW_KEEPBELOW Stay below other windows. .It AG_WINDOW_MAIN Break from .Xr 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. .It AG_WINDOW_INHERIT_ZOOM Inherit the zoom level from the parent window. See .Fn AG_WindowSetZoom . .It AG_WINDOW_DENYFOCUS Don't automatically grab focus in response to a .Sq mouse-button-down event in the window area. .It AG_WINDOW_TILING If no explicit window position is specified, choose a default position using a tiling WM algorithm which honors the preferred window alignment and attempts to avoid overlap with other tiling windows. Non-tiling windows are ignored. .It AG_WINDOW_FADEIN Enable smooth fade-in for compositing WM. .It AG_WINDOW_FADEOUT Enable smooth fade-out for compositing WM (only applies to hide operation, not detach). .It AG_WINDOW_NOTITLE Create a window without a titlebar. Under some WMs, this may imply .Dv AG_WINDOW_NOBORDERS . .It AG_WINDOW_NOBORDERS Don't draw decorative window borders. Under some WMs, this may imply .Dv AG_WINDOW_NOTITLE . .It AG_WINDOW_PLAIN Create a completely undecorated window (alias for .Dv AG_WINDOW_NOTITLE and .Dv AG_WINDOW_NOBORDERS ) . .It AG_WINDOW_NOHRESIZE Disable horizontal window resize control. .It AG_WINDOW_NOVRESIZE Disable vertical window resize control. .It AG_WINDOW_NORESIZE Alias for .Dv AG_WINDOW_NO[HV]RESIZE . .It AG_WINDOW_NOCLOSE Disable window close button in titelbar. .It AG_WINDOW_NOMINIMIZE Disable minimize button in titlebar. .It AG_WINDOW_NOMAXIMIZE Disable maximize button in titlebar. .It AG_WINDOW_NOBUTTONS Alias for .Dv AG_WINDOW_NOCLOSE , .Dv AG_WINDOW_NOMINIMIZE and .Dv AG_WINDOW_NOMAXIMIZE . .It AG_WINDOW_HMAXIMIZE Keep window scaled to the display width. .It AG_WINDOW_VMAXIMIZE Keep window scaled to the display height. .It AG_WINDOW_NOMOVE User is not allowed to move the window. .It AG_WINDOW_NOBACKGROUND Don't fill the window background prior to rendering its contents. .It AG_WINDOW_NOUPDATERECT Disable automatic updates of the video region covering the window area (for single-window, framebuffer-based graphics drivers only). .It 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. .It AG_WINDOW_MAXIMIZED Window is currently maximized (read-only). .It AG_WINDOW_MINIMIZED Window is currently minimized (read-only). .El .Sh EVENTS The GUI system may send .Nm objects the following events: .Bl -tag -width 2n .It Fn window-close "void" Request to close the window. For anonymous windows created by .Fn AG_WindowNew , the default is to Detach (and destroy). For named windows, the default is to Hide. The request can also be ignored. It is safe to create new windows in from a "window-close" handler. See: .Fn AG_WindowSetCloseAction . .It Fn window-detached "void" The window has been successfully detached (as per a previous .Xr AG_ObjectDetach 3 request), and is about to be freed. This handler can be used (and should only be used) to release any additional resources associated with the window. .It Fn window-shown "void" The window is now visible. See: .Fn AG_WindowShow . .It Fn window-hidden "void" The window is no longer visible. See: .Fn AG_WindowHide . .It Fn window-enter "void" The cursor has entered the window area. .It Fn window-leave "void" The cursor has left the window area. .El .Sh EXAMPLES The following code fragment creates an Agar window containing a label and a row of buttons. It will be positioned and dimensioned automatically: .Bd -literal -offset indent .\" SYNTAX(c) AG_Window *win; AG_Box *box; win = AG_WindowNew(0); AG_LabelNew(win, 0, "Hello!"); box = AG_BoxNewHoriz(win, AG_BOX_EXPAND); { AG_ButtonNew(box, 0, "Foo"); AG_ButtonNew(box, 0, "Bar"); AG_ButtonNew(box, 0, "Baz"); } AG_WindowShow(win); .Ed .Pp The following code fragment creates an empty Agar window with a green background, centers it and sets an explicit size of 320x240: .Bd -literal -offset indent .\" SYNTAX(c) AG_Window *win; win = AG_WindowNew(0); AG_SetStyle(win, "background-color", "green"); AG_WindowSetGeometryAligned(win, AG_WINDOW_MC, 320, 240); AG_WindowShow(win); .Ed .Sh SEE ALSO .Xr AG_Color 3 , .Xr AG_Cursor 3 , .Xr AG_Driver 3 , .Xr AG_DriverMw 3 , .Xr AG_DriverSw 3 , .Xr AG_Icon 3 , .Xr AG_InitGraphics 3 , .Xr AG_Intro 3 , .Xr AG_KeySym 3 , .Xr AG_KeyMod 3 , .Xr AG_MouseButton 3 , .Xr AG_Rect 3 , .Xr AG_StyleSheet 3 , .Xr AG_Surface 3 , .Xr AG_Text 3 , .Xr AG_Widget 3 .Sh HISTORY The .Nm system first appeared in Agar 1.0. In Agar 1.6.0, the .Fn AG_WindowFind call was added and .Fn AG_WindowNewSw was renamed .Fn AG_WindowNewUnder . .Fn AG_WindowSetPadding and .Fn AG_WindowSetSpacing were deprecated in favor of the "padding" and "spacing" style attributes.