Modules
	Internal-only Window 'Core' features

	Window Manager Window Properties

	Pointer/Cursor management

	Points, Rectangles, and Geometries

	Graphics Context APIs related to Windows

Typedefs
typedef int(*	WBLocateWindowCallback) (Window wID, void *pData)
	callback definition for WBLocateWindow More...

Enumerations
enum	WBCreateWindow_flags { WBCreateWindow_flagsDefault = 0, WBCreateWindow_flagsNoImageCache = 0x100000000LL }
	WBCreateWindow 'iFlags' additional bits. More...

Functions
Window	WBCreateWindow (Display pDisplay, Window wIDParent, WBWinEvent pProc, const char szClass, int iX, int iY, int iWidth, int iHeight, int iBorder, int iIO, WB_UINT64 iFlags, XSetWindowAttributes *pXSWA)
	Create a window. More...

void	WBDestroyWindow (Window wID)
	Destroy a window. More...

Window	WBGetApplicationWindow (void)
	Get the main 'Application' window. More...

void	WBSetApplicationWindow (Window wID)
	Assign the main 'Appklication' window. More...

int	WBDefault (Window wID, XEvent *pEvent)
	implements the default window event callback behavior More...

int	WBAppDefault (XEvent *pEvent)
	implements the default application event callback behavior More...

void	WBRegisterAppCallback (WBAppEvent pCallback)
	Registers a callback function for application events. More...

void	WBUnregisterAppCallback ()
	unregister callback function for application events More...

void	WBRegisterWindowCallback (Window wID, WBWinEvent pCallback)
	register callback function for a window (required) More...

void	WBUnregisterWindowCallback (Window wID)
	un-register the window's callback function (implies resource destruction) More...

void	WBSetWindowTitle (Window wID, const char *szTitle)
	assign window (and icon) title More...

Window	WBLocateWindow (WBLocateWindowCallback callback, void *pData)
	Locate a window by enumerating with a callback function. More...

void	WBSetInputFocus (Window wID)
	set input focus to a specific window More...

Display *	WBGetWindowDisplay (Window wID)
	returns the Display associated with a window More...

void	WBSetWindowIcon (Window wID, int idIcon)
	assigns an icon resource (by ID) to a window More...

void	WBSetWindowFont (Window wID, WB_FONTC pFont)
	assigns the default WB_FONT object for a window More...

void	WBSetWindowData (Window wID, int iIndex, void *pData)
	assign 'data pointer' for a window and specified index value More...

WB_FONTC	WBQueryWindowFont (Window wID)
	Returns the WB_FONT assigned to the window (may be NULL), not a copy. More...

WB_FONT	WBGetWindowFont (Window wID)
	Returns a copy of the current WB_FONT assigned to the window (may be NULL) More...

unsigned long	WBGetWindowFGColor (Window wID)
	Returns the currently assigned foreground color. More...

unsigned long	WBGetWindowBGColor (Window wID)
	Returns the currently assigned background color. More...

void	WBDefaultStandardColormap (Display pDisplay, XStandardColormap pMap)
	returns a default XStandardColormap structure for the default screen of the specified display More...

void	WBSetWindowClassName (Window wID, const char *szClassName)
	Assignes the window's class name pointer. More...

const char *	WBGetWindowClassName (Window wID)
	Returns the window's assigned class name pointer. More...

void *	WBGetWindowData (Window wID, int iIndex)
	Gets the data associated with this window and the specified index. More...

Window	WBGetParentWindow (Window wID)
	Returns the window's parent (or None if there is no parent) More...

void	WBSetParentWindow (Window wID, Window wIDParent)
	Assigns the parent to the specified window within the internal structure. More...

int	WBReparentWindow (Window wID, Window wIDParent, int iX, int iY)
	Assigns a new parent to the specified window (aka 'Re-parent') More...

int	WBIsChildWindow (Window wIDParent, Window wIDChild)
	Returns non-zero if wIDParent is in a parent relationsihp with wIDChild. More...

void	WBAddMenuWindow (Window wID, Window wIDMenu)
	Add a MENU WINDOW to a (frame) window. More...

Window	WBGetMenuWindow (Window wID)
	Returns the Window ID of the (first) menu window assigned to a (frame) window. More...

void	WBRemoveMenuWindow (Window wID, Window wIDMenu)
	Remove (detach) the specified menu window from a (frame) window. More...

int	WBIsValid (Display *pDisplay, Window wID)
	returns non-zero if 'valid' (i.e. 'not destroyed') More...

Detailed Description

These functions and definitions comprise the CORE WINDOW HANDLING functionality for the X11workbench Toolkit API. This includes information and initialization functions, but not event nor class-specific functionality.

Typedef Documentation

◆ WBLocateWindowCallback

typedef int(* WBLocateWindowCallback) (Window wID, void *pData)

callback definition for WBLocateWindow

Parameters

wID	The ID of the window being enumerated
pData	The pointer specified in the call to WBLocateWindow

Returns: A value > 0 to indicate a match, < 0 to stop enumerating, 0 to continue enumerating

Header File: window_helper.h

Definition at line 1291 of file window_helper.h.

Enumeration Type Documentation

◆ WBCreateWindow_flags

enum WBCreateWindow_flags

WBCreateWindow 'iFlags' additional bits.

Bit flags for additional properties for 'iFlags' in WBCreateWindow.

Enumerator
WBCreateWindow_flagsDefault	equivalent to 'CWBorderPixel \| CWBackPixel \| CWColormap \| CWBitGravity' when specified without any additional 'CW' flags
WBCreateWindow_flagsNoImageCache	do not use a 'backing store' when drawing the window (native X11 calls)

Definition at line 1068 of file window_helper.h.

Function Documentation

◆ WBAddMenuWindow()

void WBAddMenuWindow	(	Window	wID,
		Window	wIDMenu
	)

Add a MENU WINDOW to a (frame) window.

Parameters

wID	The Window ID to which a menu window will be added (typically only one)
wIDMenu	The Window ID of the menu window to add/assign to wID

This function will add a MENU WINDOW to a (frame) window. The menu window will process all hotkeys and mouse clicks that are related to menus and menu activation. In many cases, hotkeys may need to be checked within the owner window's event callback (see MBMenuProcessHotKey() for more on this). If the focus is currently on the menu window itself, then the menu window's callback function will handle them. Also, Frame Windows will handle the menu hotkeys automatically within their default event handlers.

See also: Frame Window API, Child frame Window API

NOTE: you can add multiple menus to multiple windows. however, at this time, only a 1:1 relationship is supported

Header File: window_helper.h

Definition at line 7138 of file window_helper.c.

◆ WBAppDefault()

int WBAppDefault ( XEvent * pEvent )

implements the default application event callback behavior

Header File: window_helper.h

Definition at line 4906 of file window_helper.c.

◆ WBCreateWindow()

Window WBCreateWindow	(	Display *	pDisplay,
		Window	wIDParent,
		WBWinEvent	pProc,
		const char *	szClass,
		int	iX,
		int	iY,
		int	iWidth,
		int	iHeight,
		int	iBorder,
		int	iIO,
		WB_UINT64	iFlags,
		XSetWindowAttributes *	pXSWA
	)

Create a window.

Parameters

pDisplay	A pointer to the display (or NULL for the default display)
wIDParent	The parent window, or 'None'
pProc	A pointer to the event handler proc
szClass	The name of the window's class (mostly for debugging in X11; for WIN32 this is important for other reasons)
iX	The X position of the window
iY	The Y position of the window
iWidth	The width of the window
iHeight	The height of the window
iBorder	The border width of the window
iIO	The I/O type of the window (Input, InputOutput, etc.)
iFlags	The flags indicating which bits are valid in the XSetWindowAttributes structure, plus additional flags specific to the X11Workbench Toolkit (see below)
pXSWA	A pointer to the XSetWindowAttributes structure. May be NULL if the lower 32-bits of iFlags is WBCreateWindow_flagsDefault (see below).

Returns: A valid Window ID, or 'None' on error

Call this function to create a window, which is similar to XCreateWindow(). It will automatically register the callback function and the class name, and sets up a few default parameters for you automatically.
The window is created with the default visual and depth for the specified display with default screen and a default set of WM_HINTS.

The X11Workbench Toolkit also supports a number of additional bit values for 'iFlags':

WBCreateWindow_flagsDefault (which has a value of zero) When specified alone, this uses the default value CWBorderPixel | CWBackPixel | CWColormap | CWBitGravity . if the value of 'pXSWA' is NULL, a default XSetWindowAttributes structure will be created and initialized for you, using WBInitWindowAttributes() and default values.

See also: WBInitWindowAttributes()

Header File: window_helper.h

Definition at line 2753 of file window_helper.c.

◆ WBDefault()

int WBDefault	(	Window	wID,
		XEvent *	pEvent
	)

implements the default window event callback behavior

Header File: window_helper.h

Definition at line 4911 of file window_helper.c.

◆ WBDefaultStandardColormap()

void WBDefaultStandardColormap	(	Display *	pDisplay,
		XStandardColormap *	pMap
	)

returns a default XStandardColormap structure for the default screen of the specified display

Parameters

pDisplay	The display for which to obtain the XStandardColormap. This will use its default Colormap
pMap	A pointer to an XStandardColormap structure. This will receive a copy of the XStandardColormap for the specified display

This function obtains an XStandardColormap for the default colormap associated with a display. For the defaut display, this value is cached (for performance). Other displays will 'hit' the X Server to obtain the necessary information. If there is no default XStandardColormap in the system (which is typical), this function will derive one using the Red, Green, and Blue color pixel values, and the results of using XAllocColor.

An XStandardColormap structure is necessary in order to map RGB values to/from 'Pixel' values without calling the time-expensive XAllocColor (and related functions). If you do any kind of extensive color-related things with your code, you will most likely need a copy of the XStandardColormap .

You should also ignore the visualid and killid parameters. These will both be assigned to 'None'

Header File: window_helper.h

Definition at line 5917 of file window_helper.c.

◆ WBDestroyWindow()

void WBDestroyWindow ( Window wID )

Destroy a window.

Call this function to destroy a window, rather than XDestroyWindow

Header File: window_helper.h

Definition at line 2233 of file window_helper.c.

◆ WBGetApplicationWindow()

Window WBGetApplicationWindow ( void )

Get the main 'Application' window.

Returns: The application window's Window ID, or 'None'

Call this function to get the 'Application' window's ID registered via WBSetApplicationWindow(). There can be only one.

Header File: window_helper.h

Definition at line 3295 of file window_helper.c.

◆ WBGetMenuWindow()

Window WBGetMenuWindow ( Window wID )

Returns the Window ID of the (first) menu window assigned to a (frame) window.

Parameters

wID	The Window ID for which to query the menu Window ID

Returns: The Window ID for the Menu window assigned to wID (only one may be assigned for this to work)

Header File: window_helper.h

Definition at line 7154 of file window_helper.c.

◆ WBGetParentWindow()

Window WBGetParentWindow ( Window wID )

Returns the window's parent (or None if there is no parent)

Parameters

wID	The Window ID to obtain the parent for

Returns: The Window ID of the parent, or None

Header File: window_helper.h

Definition at line 6958 of file window_helper.c.

◆ WBGetWindowBGColor()

unsigned long WBGetWindowBGColor ( Window wID )

Returns the currently assigned background color.

Parameters

wID	The Window ID from which to obtain the background color

Returns: The current background color for the window

Header File: window_helper.h

See also: WBGetGCBGColor()

Definition at line 5845 of file window_helper.c.

◆ WBGetWindowClassName()

const char* WBGetWindowClassName ( Window wID )

Returns the window's assigned class name pointer.

Parameters

wID	The Window ID to obtain a 'class name' from

Returns: A const pointer to a 0-byte terminated character string containing the window's class name, or NULL if there is none

The windows 'class name' is a persistent string pointer that is optionally assigned by calling WBSetWindowClassName(). This function returns the assigned pointer. Its primary use is for debugging and tracing.

Header File: window_helper.h

Definition at line 6259 of file window_helper.c.

◆ WBGetWindowData()

void* WBGetWindowData	(	Window	wID,
		int	iIndex
	)

Gets the data associated with this window and the specified index.

Parameters

wID	The Window ID to obtain window data for
iIndex	The 0-based index for the window's data

Returns: A void pointer assigned to the specified index for the specified window, or NULL if there is no data.

Each window has up to WINDOW_DATA_SIZE void pointers that can be stored within the internal data structure associated with each window. For many standard windows and controls defined in the API, the first entry (index zero) is reserved. Any unused entries can be made use of in any way necessary. It is important to keep in mind that these values are not automatically checked, nor are any resources automatically deleted when the window is destroyed.

Header File: window_helper.h

Definition at line 6271 of file window_helper.c.

◆ WBGetWindowDisplay()

Display* WBGetWindowDisplay ( Window wID )

returns the Display associated with a window

Parameters

wID	The Window ID from which to obtain the Display pointer

Returns: A Display pointer corresponding to the Window ID, or NULL on error

Header File: window_helper.h

Definition at line 5596 of file window_helper.c.

◆ WBGetWindowFGColor()

unsigned long WBGetWindowFGColor ( Window wID )

Returns the currently assigned foreground color.

Parameters

wID	The Window ID from which to obtain the foreground color

Returns: The current foreground color for the window

Header File: window_helper.h

See also: WBGetGCFGColor()

Definition at line 5833 of file window_helper.c.

◆ WBGetWindowFont()

WB_FONT WBGetWindowFont ( Window wID )

Returns a copy of the current WB_FONT assigned to the window (may be NULL)

Parameters

wID	The Window ID from which to obtain a copy of the current WB_FONT object

Returns: A copy of the assigned WB_FONT, or 'NULL' on error. A non-null return must be free's using WBFreeFont()

Header File: window_helper.h

Definition at line 6213 of file window_helper.c.

◆ WBIsChildWindow()

int WBIsChildWindow	(	Window	wIDParent,
		Window	wIDChild
	)

Returns non-zero if wIDParent is in a parent relationsihp with wIDChild.

Parameters

wIDParent	The Window ID for the 'test' parent window
wIDChild	The Window ID for the 'test' child window

Returns: A non-zero value if wIDParent is in a parent/child relatinship with wIDChild; otherwise it returns zero

Rather than checking for the parent window ID and doing a 'direct match', this function checks all parent windows of 'wIDChild' to see if 'wIDParent' is one of them, and returns a non-zero value if it is. Otherwise, the function returns zero.

Header File: window_helper.h

Definition at line 7014 of file window_helper.c.

◆ WBIsValid()

int WBIsValid	(	Display *	pDisplay,
		Window	wID
	)

returns non-zero if 'valid' (i.e. 'not destroyed')

Parameters

pDisplay	The Display pointer associated with the specified window
wID	A Window ID to test 'valid'

Returns: Non-zero value if the internal window information exists and the window has not been destroyed, else zero

This function works ONLY for windows that have been registered with a callback. It checks to see if the internal window information exists and returns a non-zero value if the internal information exists AND the window itself has not been destroyed. This works whether or not the window was ever mapped.

Header File: window_helper.h

Definition at line 5547 of file window_helper.c.

◆ WBLocateWindow()

Window WBLocateWindow	(	WBLocateWindowCallback	callback,
		void *	pData
	)

Locate a window by enumerating with a callback function.

Parameters

callback	A pointer to a callback function to call for each enumerated window - see WBLocateWindowCallback
pData	A void pointer that is passed to the callback function as its 2nd parameter

Returns: The Window ID being enumerated when the callback returns a value > 0, or None

loops through all known windows passing the window ID and pData to the callback function. The callback function then determines whether this is the window (droids?) you are looking for.

The callback must return > 0 if found, 0 if not found, < 0 to quit enumerating

WBLocateWindow then returns either 0 (None) or a valid window ID

See also: WBLocateWindowCallback

Header File: window_helper.h

Definition at line 3263 of file window_helper.c.

◆ WBQueryWindowFont()

WB_FONTC WBQueryWindowFont ( Window wID )

Returns the WB_FONT assigned to the window (may be NULL), not a copy.

Parameters

wID	The Window ID from which to obtain a copy of the current WB_FONT object

Returns: The assigned WB_FONT, or 'NULL' on error.

Header File: window_helper.h

Definition at line 6201 of file window_helper.c.

◆ WBRegisterAppCallback()

void WBRegisterAppCallback ( WBAppEvent pCallback )

Registers a callback function for application events.

To handle events sent to the application ('no window' events), register a callback function using this API. The callback function you register should call WBAppDefault() for any events that it does not process.

Header File: window_helper.h

Definition at line 2378 of file window_helper.c.

◆ WBRegisterWindowCallback()

void WBRegisterWindowCallback	(	Window	wID,
		WBWinEvent	pCallback
	)

register callback function for a window (required)

Header File: window_helper.h

Definition at line 3029 of file window_helper.c.

◆ WBRemoveMenuWindow()

void WBRemoveMenuWindow	(	Window	wID,
		Window	wIDMenu
	)

Remove (detach) the specified menu window from a (frame) window.

Parameters

wID	The Window ID for which to remove a menu Window ID
wIDMenu	The Window ID of the menu window to remove

Header File: window_helper.h

Definition at line 7170 of file window_helper.c.

◆ WBReparentWindow()

int WBReparentWindow	(	Window	wID,
		Window	wIDParent,
		int	iX,
		int	iY
	)

Assigns a new parent to the specified window (aka 'Re-parent')

Parameters

wID	The Window ID of the target (to be adopted) window
wIDParent	The new parent Window ID. Congratulations, it's a Window!
iX	The new X location for the window specified by wID (see XReparentWindow)
iY	The new Y location for the window specified by wID (see XReparentWindow)

Call this function to re-assign the parent window via XReparentWindow. Using this function will ensure that internal information remains synchronized.
NOTE: this function should NOT be called for top level windows.

Header File: window_helper.h

Definition at line 6993 of file window_helper.c.

◆ WBSetApplicationWindow()

void WBSetApplicationWindow ( Window wID )

Assign the main 'Appklication' window.

Parameters

wID	The Window identifier of the 'application' window, or None

Call this function to set the 'Application' window's ID. There can be only one. Make sure the window has an assigned callback already, or the assignment will fail. Once the application window's callback has been unregistered, the application window ID will be reset to 'None' automatically.

Header File: window_helper.h

Definition at line 3300 of file window_helper.c.

◆ WBSetInputFocus()

void WBSetInputFocus ( Window wID )

set input focus to a specific window

Parameters

wID	The Window ID to assign the focus

Call this function to assign the input focus to a specific window. The 'revert' window will be the previous focus window.

Header File: window_helper.h

Definition at line 2180 of file window_helper.c.

◆ WBSetParentWindow()

void WBSetParentWindow	(	Window	wID,
		Window	wIDParent
	)

Assigns the parent to the specified window within the internal structure.

Parameters

wID	The Window ID of the target
wIDParent	The parent Window ID to assign to the internal structure

Call this function to assign the specified parent window ID to the internal structure for the target window. This does NOT re-parent the window!

If you want to change the owner window you should call WBReparentWindow() instead. NOTE: this function should NOT be called for top level windows.

Header File: window_helper.h

Definition at line 6985 of file window_helper.c.

◆ WBSetWindowClassName()

void WBSetWindowClassName	(	Window	wID,
		const char *	szClassName
	)

Assignes the window's class name pointer.

Parameters

wID	The Window ID to assign a 'class name' to
szClassName	A const pointer to a 0-byte terminated string containing the class name. The actual pointer is assigned internally.

Assigns a pointer to a persistent character string that identifies the 'window class' for debug and tracing purposes. The pointer must be 'persistent', neither allocated via 'malloc()' or on the stack, since it is assigned directly 'as-is' to the internal structure, without copying the string data.

Header File: window_helper.h

Definition at line 6249 of file window_helper.c.

◆ WBSetWindowData()

void WBSetWindowData	(	Window	wID,
		int	iIndex,
		void *	pData
	)

assign 'data pointer' for a window and specified index value

Parameters

wID	The Window ID to which to assign the data pointer
iIndex	The 0-based index that identifies the entry
pData	The data pointer to assign (may be NULL)

Header File: window_helper.h

Definition at line 5795 of file window_helper.c.

◆ WBSetWindowFont()

void WBSetWindowFont	(	Window	wID,
		WB_FONTC	pFont
	)

assigns the default WB_FONT object for a window

Parameters

wID	The Window ID from which to return the default font
pFont	The WB_FONTC (or WB_FONT) object for the window. A copy of this object will be owned by the window. To use the default font set, you can assign a value of 'NULL'

Header File: window_helper.h

Definition at line 5704 of file window_helper.c.

◆ WBSetWindowIcon()

void WBSetWindowIcon	(	Window	wID,
		int	idIcon
	)

assigns an icon resource (by ID) to a window

Parameters

wID	The Window ID from which to return the default icon
idIcon	The resource ID for the window's icon

Header File: window_helper.h

Definition at line 5608 of file window_helper.c.

◆ WBSetWindowTitle()

void WBSetWindowTitle	(	Window	wID,
		const char *	szTitle
	)

assign window (and icon) title

Parameters

wID	The Window ID for the window
szTitle	A const pointer to a character string containing the window title

Header File: window_helper.h

Definition at line 3004 of file window_helper.c.

◆ WBUnregisterAppCallback()

void WBUnregisterAppCallback ( )

unregister callback function for application events

Header File: window_helper.h

Definition at line 2383 of file window_helper.c.

◆ WBUnregisterWindowCallback()

void WBUnregisterWindowCallback ( Window wID )

un-register the window's callback function (implies resource destruction)

Header File: window_helper.h

Definition at line 3051 of file window_helper.c.

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ WBLocateWindowCallback

Enumeration Type Documentation

◆ WBCreateWindow_flags

Function Documentation

◆ WBAddMenuWindow()

◆ WBAppDefault()

◆ WBCreateWindow()

◆ WBDefault()

◆ WBDefaultStandardColormap()

◆ WBDestroyWindow()

◆ WBGetApplicationWindow()

◆ WBGetMenuWindow()

◆ WBGetParentWindow()

◆ WBGetWindowBGColor()

◆ WBGetWindowClassName()

◆ WBGetWindowData()

◆ WBGetWindowDisplay()

◆ WBGetWindowFGColor()

◆ WBGetWindowFont()

◆ WBIsChildWindow()

◆ WBIsValid()

◆ WBLocateWindow()

◆ WBQueryWindowFont()

◆ WBRegisterAppCallback()

◆ WBRegisterWindowCallback()

◆ WBRemoveMenuWindow()

◆ WBReparentWindow()

◆ WBSetApplicationWindow()

◆ WBSetInputFocus()

◆ WBSetParentWindow()

◆ WBSetWindowClassName()

◆ WBSetWindowData()

◆ WBSetWindowFont()

◆ WBSetWindowIcon()

◆ WBSetWindowTitle()

◆ WBUnregisterAppCallback()

◆ WBUnregisterWindowCallback()