FreeBSD Manual Pages
AG_WINDOW(3) BSD Library Functions Manual AG_WINDOW(3) NAME AG_Window -- agar window system 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 some 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 (us- ing 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 visi- ble using AG_WindowShow(). Windows are destroyed by a single call to AG_ObjectDetach(3). The detach operation actually places the window on a queue, and actual freeing will occur after the end of the current event processing cycle. After a win- dow has been successfully detached, the `window-detached' event is raised. INHERITANCE HIERARCHY AG_Object(3) -> AG_Widget(3) -> AG_Window. INTERFACE AG_Window * AG_WindowNew(Uint flags) AG_Window * AG_WindowNewNamed(Uint flags, const char *format, ...) AG_Window * AG_WindowNewNamedS(Uint flags, const char *name) AG_Window * AG_WindowNewSw(AG_DriverSw *drv, Uint flags) void AG_WindowSetCaption(AG_Window *win, const char *format, ...) void AG_WindowSetCaptionS(AG_Window *win, const char *text) void AG_WindowSetIcon(AG_Window *win, AG_Surface *surface) void AG_WindowSetIconNODUP(AG_Window *win, AG_Surface *surface) void AG_WindowSetCloseAction(AG_Window *win, eum ag_window_close_action action) void AG_WindowSetPadding(AG_Window *win, int paddingLeft, int paddingRight, int paddingTop, int paddingBottom) void AG_WindowSetSpacing(AG_Window *win, int spacing) void AG_WindowSetSideBorders(AG_Window *win, int pixels) void AG_WindowSetBottomBorder(AG_Window *win, int pixels) void AG_WindowSetPosition(AG_Window *win, enum ag_window_alignment alignment, int tiling) void AG_WindowSetGeometry(AG_Window *win, int x, int y, int w, int h) void AG_WindowSetGeometryRect(AG_Window *win, AG_Rect rect, int bounded) void AG_WindowSetGeometryAligned(AG_Window *win, enum ag_window_alignment alignment, int w, int h) void AG_WindowSetGeometryAlignedPct(AG_Window *win, enum ag_window_alignment alignment, int wPct, int hPct) void AG_WindowSetGeometryBounded(AG_Window *win, int x, int y, int w, int h) void AG_WindowSetGeometryMax(AG_Window *win) void AG_WindowSetMinSize(AG_Window *win, int w, int h) void AG_WindowSetMinSizePct(AG_Window *win, int pct) int AG_WindowSetOpacity(AG_Window *win, float opacity) void AG_WindowSetFadeIn(AG_Window *win, float fadeTime, float fadeIncr) void AG_WindowSetFadeOut(AG_Window *win, float fadeTime, float fadeIncr) void AG_WindowSetZoom(AG_Window *win, int zoomLvl) void AG_ZoomIn(void) void AG_ZoomOut(void) void AG_ZoomReset(void) void AG_WindowMaximize(AG_Window *win) void AG_WindowUnmaximize(AG_Window *win) void AG_WindowMinimize(AG_Window *win) void AG_WindowUnminimize(AG_Window *win) void AG_WindowAttach(AG_Window *winParent, AG_Window *winChld) void AG_WindowDetach(AG_Window *winParent, AG_Window *winChld) void AG_WindowMakeTransient(AG_Window *winParent, AG_Window *winTrans) void AG_WindowPin(AG_Window *winParent, AG_Window *winToPin) void AG_WindowUnpin(AG_Window *win) void AG_WindowUpdate(AG_Window *win) 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 con- tain 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 appli- cations that wish to use multiple single-window drivers concurrently. The AG_WindowSetCaption() function sets the text displayed by the title- bar (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 win- dow. 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 du- plicate the provided surface, which must remain valid until the window is destroyed. The AG_WindowSetCloseAction() function specifies the action to perform when the window is requested to be closed. Accepted arguments include: AG_WINDOW_HIDE Hide the window. This is the default action for win- dows created with AG_WindowNewNamed(). AG_WINDOW_DETACH Detach and destroy the window. This is the default action for windows created with AG_WindowNew(). AG_WINDOW_IGNORE Ignore the close request. To perform a different action, an event handler can be configured for the `window-close' and `window-modal-close' events (see the EVENTS section). 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 wid- gets from each other. The default is 2 pixels. Note that AG_WindowSetSpacing() only affects the widgets which are di- rectly attached to the window. For widgets that are attached to con- tainer 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-spe- cific. 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 posi- tion, per the specified alignment. Possible values for the alignment ar- gument 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 ini- tial window position up to the underlying window manager (possibly Agar itself, or an external window manager). If the tiling argument is 1, the AG_WINDOW_TILING flag is set (see FLAGS section). With tiling enabled, the window manager will attempt to avoid overlap between existing windows. The AG_WindowSetGeometry() function moves/resizes a window to the spe- cific 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 align- ment (see description of AG_WindowSetPosition() for the possible values). The parameters of AG_WindowSetGeometryAlignedPct() are given in percent- age 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 com- positing 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). 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 depen- dent of winParent. Detaching the parent window (using AG_ObjectDetach(3)) will cause dependent child windows to be detached im- plicitely. Child windows also inherit the style properties from their parent. The AG_WindowDetach() function detaches the window from its par- ent window. AG_WindowMakeTransient() registers winTrans as a dependent and transient window for winParent. The effects of transient window state are depen- dent 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 dis- placed 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 follow- ing 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 struc- ture. Note: In widget implementation code, one should use AG_WidgetUpdate(3) instead of this function. 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) in- vokes them internally. void AG_WindowDraw(AG_Window *win) void AG_WindowDrawQueued(void) void AG_WindowProcessQueued(void) 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. VISIBILITY void AG_WindowShow(AG_Window *win) void AG_WindowHide(AG_Window *win) int AG_WindowIsVisible(AG_Window *win) 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. void AG_WindowFocus(AG_Window *win) int AG_WindowFocusNamed(const char *name) int AG_WindowFocusAtPos(AG_DriverSw *drv, int x, int y) AG_Window * AG_WindowFindFocused(void) int AG_WindowIsFocused(AG_Window *win) void AG_WindowCycleFocus(AG_Window *win, int reverse) void AG_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 func- tion 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 can- celled. 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 pre- ceeding 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 fo- cused window, if any. STRUCTURE DATA For the AG_Window object: Uint flags Option flags (see FLAGS section below). int wmType Window manager hint describing window function (see WINDOW MANAGER HINTS below). int visible Visibility flag (1 = visible, 0 = hidden). Read-only (see AG_WindowShow() and AG_WindowHide()). int dirty Redraw flag. If set to 1, the window will be redrawn as soon as possible. AG_Titlebar *tbar Pointer to the associated AG_Titlebar(3) widget, or NULL if the window has no titlebar. Read-only. int wReq, hReq Ideal window geometry in pixels, as last computed from the size_request() operation of its attached widgets. Read-only (see AG_WidgetSizeReq(3)). int wMin, hMin Suggested minimum window geometyry in pixels. Read- only (use AG_WindowSetMinSize()). AG_Window *parent Pointer to parent window, or NULL if there isn't any. Read-only (see AG_WindowAttach() and AG_WindowDetach()). TAILQ subwins List of dependent child windows. Read-only (see AG_WindowAttach() and AG_WindowDetach()). AG_Icon *icon 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 window managers to tweak window appearance and behavior details. The values correspond to those specified in Ex- tended Window Manager Hints (EWMH) version 1.4. 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 */ }; FLAGS For the AG_Window object: AG_WINDOW_TILING If no explicit window position is specified, choose a default position using a tiling window manager algorithm. This method honors the pre- ferred window alignment, and also attempts to avoid overlap with other tiling windows. Non- tiling windows are ignored in the calculation. AG_WINDOW_FADEIN Enable smooth fade-in for compositing window managers. AG_WINDOW_FADEOUT Enable smooth fade-out for compositing window managers. Only effective with AG_WindowHide() (i.e., windows destroyed with AG_ObjectDetach(), are not faded out). AG_WINDOW_MAXIMIZED Window is currently maximized (read-only). AG_WINDOW_MINIMIZED Window is currently minimized (read-only). AG_WINDOW_KEEPABOVE Stay on top of other windows. AG_WINDOW_KEEPBELOW Stay below other windows. AG_WINDOW_DENYFOCUS 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. If a click or touch event is detected outside of the window area, a `window-modal-close' event will be raised. AG_WINDOW_NOBACKGROUND Don't fill the window background prior to ren- dering 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 window managers, this option may imply AG_WINDOW_NOBORDERS. AG_WINDOW_NOBORDERS Don't draw decorative window borders. Under some window managers, this option 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_NOHRESIZE and AG_WINDOW_NOVRESIZE. 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_NOCLIPPING Disable the clipping rectangle over the window area (enabled by default). AG_WINDOW_MODKEYEVENTS Deliver discrete events to widget when modifier keys (CTRL, ALT, SHIFT) are pressed. AG_WINDOW_NOCURSORCHG Deny any cursor change requested by widgets at- tached to this window. This flag is automati- cally 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 (sent by the user / underlying window system). The default behavior is to hide named windows and detach unnamed windows. It is safe for an event handler to ignore the re- quest, or to create new windows (e.g., a confirmation dialog) in re- sponse. window-modal-close(int x, int y) The window is modal (the AG_WINDOW_MODAL option is set), and a click or touch event was detected outside of its area (at given coordi- nates). By default, the request is ignored. window-detached(void) The window has been successfully detached (as per a previous AG_ObjectDetach(3) request). window-shown(void) The window is now visible. window-hidden(void) The window is no longer visible. window-enter(void) The cursor has entered the window area. window-leave(void) The cursor has left the window area. 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_Cursor(3), AG_Icon(3), AG_Intro(3), AG_View(3), AG_Widget(3) HISTORY The AG_Window system first appeared in Agar 1.0. BSD August 21, 2002 BSD
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INTERFACE | DRIVER / EVENT LOOP INTERFACE | VISIBILITY | FOCUS STATE | STRUCTURE DATA | WINDOW MANAGER HINTS | FLAGS | EVENTS | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Window&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>