NAME

AG_DriverMw — agar multiple-window driver class

SYNOPSIS

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

DESCRIPTION

AG_DriverMw is a subclass of AG_Driver(3) for "multiple-window" drivers (i.e., drivers where Agar must interface with a native window system).

INHERITANCE HIERARCHY

AG_Driver(3) -> AG_DriverMw.

INTERNAL API

The AG_DriverMwClass structure describes a "multiple-window" graphics driver, where Agar will need to interface with an existing window manager. AG_DriverMwClass inherits from AG_DriverClass and is defined as follows:

typedef struct ag_driver_mw_class {
	struct ag_driver_class _inherit;

	/* Create / destroy window */
	int  (*openWindow)(AG_Window *win, const AG_Rect *r, int bpp,
	                   Uint flags);
	void (*closeWindow)(AG_Window *win);

	/* Set window visibility */
	int (*mapWindow)(AG_Window *win);
	int (*unmapWindow)(AG_Window *win);

	/* Configure stacking order and parenting */
	int (*raiseWindow)(AG_Window *win);
	int (*lowerWindow)(AG_Window *win);
	int (*reparentWindow)(AG_Window *win, AG_Window *winParent,
	                      int x, int y);

	/* Change and query input focus state */
	int (*getInputFocus)(AG_Window **win);
	int (*setInputFocus)(AG_Window *win);

	/* Move and resize windows */
	int  (*moveWindow)(AG_Window *win, int x, int y);
	int  (*resizeWindow)(AG_Window *win, Uint w, Uint h);
	int  (*moveResizeWindow)(AG_Window *win, AG_SizeAlloc *a);
	void (*preResizeCallback)(AG_Window *win);
	void (*postResizeCallback)(AG_Window *win, AG_SizeAlloc *a);

	/* Configure window parameters */
	int  (*setBorderWidth)(AG_Window *win, Uint w);
	int  (*setWindowCaption)(AG_Window *win, const char *s);
	void (*setTransientFor)(AG_Window *win, AG_Window *winParent);
	int  (*setOpacity)(AG_Window *win, float opacity);
	void (*tweakAlignment)(AG_Window *win, AG_SizeAlloc *a);
        void (*setWindowMinSize)(AG_Window *win, int w, int h);
        void (*setWindowMaxSize)(AG_Window *win, int w, int h);
} AG_DriverMwClass;

The openWindow() operation opens a new "native" window corresponding to an AG_Window(3) that is in the process of being created, returning 0 on success or -1 on failure. The r argument specifies the preferred location and geometry of the window, in pixels. bpp specifies a preferred depth in bits per pixels. The following flags are recognized:

AG_DRIVER_MW_ANYPOS

Ignore the coordinates in r and let the underlying window system select some default coordinates.

mapWindow() and unmapWindow() make a window visible or invisible, returning 0 on success and -1 on failure.

raiseWindow() and lowerWindow() respectively raise and lower the window, returning 0 on success and -1 on failure. The reparentWindow() function arranges for the window to become a child of winParent, moving it to parent-relative coordinates x, y. The function should return 0 on success or -1 on failure.

The getInputFocus() operation retrieves a pointer to the window currently holding focus, returning 0 on success. If the focus is external to the Agar application, it should return -1. setInputFocus() gives focus to the specified window, returning 0 on success or -1 on failure.

The moveWindow(), resizeWindow() and moveResizeWindow() operations respectively move, resize or move+resize a window to specified coordinates and geometry, returning 0 on success or -1 on failure.

The preResizeCallback() operation is invoked prior to a window resize, and postResizeCallback() is invoked following a window resize (the new window geometry is passed as the a argument).

setBorderWidth() configures a window border size in pixels, returning 0 on success or -1 if the operation is unsupported or an error has occurred.

setWindowCaption() sets the associated window caption text, if supported by the window system. The string passed to the function may contain characters in UTF-8 encoding. The function should return 0 on success or -1 on failure.

setTransientFor() passes a hint to the window manager that the window should be marked as "transient" for the specified window winParent. This operation is optional and window manager specific.

setOpacity() passes a window opacity argument (ranging from 0.0 to 1.0) to the underlying window manager.

The optional tweakAlignment() operation allows the driver to override or alter the effect of the window alignment request (set by AG_WindowSetPosition(3) or AG_WindowSetGeometryAligned(3)), such that underlying WM-specific items (desktop panels and such) can be taken into consideration (by default, the display boundaries are used). This routine should set the x and y members of a, in function of w and h.

The optional setWindowMinSize() and setWindowMaxSize() operations set a minimum and a maximum window size in pixels.

SEE ALSO

AG_Driver(3), AG_DriverSw(3), AG_InitGraphics(3), AG_Intro(3)

HISTORY

The AG_DriverMw class first appeared in Agar 1.4.0.