X11 Work Bench Toolkit  1.0
Window 'Core'

Data Structures

struct  __EVENT_ENTRY__
 Core (internal) structure for storing and dispatching events. More...
 
struct  __TIMER_ENTRY__
 Core (internal) structure for managing timers. More...
 
struct  __DELAYED_EVENT_ENTRY__
 Core (internal) structure for managing delayed events. More...
 

Macros

#define WB_STANDARD_INPUT_MASK   (FocusChangeMask | PropertyChangeMask | ExposureMask | StructureNotifyMask | VisibilityChangeMask | SubstructureNotifyMask)
 'Standard' input mask, bit flag for window creation More...
 
#define WB_KEYBOARD_INPUT_MASK   (KeyPressMask | KeyReleaseMask)
 'Keyboard' input mask, bit flag for window creation More...
 
#define WB_MOUSE_INPUT_MASK   (ButtonPressMask | ButtonReleaseMask | PointerMotionMask | EnterWindowMask | LeaveWindowMask)
 'Mouse' input mask, bit flag for window creation More...
 
#define WBGetWindowCopyGC2(wID, gcSrc)   WBCopyDrawableGC(WBGetWindowDisplay(wID), wID, gcSrc)
 makes a copy of the specified GC for the desired window More...
 
#define WBPointInRect(X, Y, R)   ((X) >= (R).left && (X) < (R).right && (Y) >= (R).top && (Y) < (R).bottom)
 Returns logical TRUE if the point (X,Y) is within the borders of the rectangle 'R'. More...
 
#define WBPointInGeom(X, Y, G)   ((X) >= (G).x && (X) < ((G).x + (G).width) && (Y) >= (G).y && (Y) < ((G).y + (G).height))
 Returns logical TRUE if the point (X,Y) is within the borders of the geometry 'G'. More...
 
#define WBRectOverlapped(R1, R2)
 Returns logical TRUE if the rectangle R1 overlaps/intersects R2. More...
 
#define WBGeomOverlapped(G1, G2)
 Returns logical TRUE if the geometry G1 overlaps/intersects G2. More...
 

Typedefs

typedef int(* WBLocateWindowCallback )(Window wID, void *pData)
 callback definition for WBLocateWindow More...
 
typedef struct __EVENT_ENTRY__ EVENT_ENTRY
 Core (internal) structure for storing and dispatching events.
 
typedef struct __TIMER_ENTRY__ TIMER_ENTRY
 Core (internal) structure for managing timers.
 
typedef struct
__DELAYED_EVENT_ENTRY__ 
DELAYED_EVENT_ENTRY
 Core (internal) structure for managing delayed events.
 

Enumerations

enum  WMPropertiesWindowType {
  WMPropertiesWindowType_TypeMask = 0x3f, WMPropertiesWindowType_Normal = 0, WMPropertiesWindowType_Desktop = 1, WMPropertiesWindowType_Dock = 2,
  WMPropertiesWindowType_ToolBar = 3, WMPropertiesWindowType_Menu = 4, WMPropertiesWindowType_Utility = 5, WMPropertiesWindowType_Splash = 6,
  WMPropertiesWindowType_Dialog = 7, WMPropertiesWindowType_DropDownMenu = 8, WMPropertiesWindowType_PopupMenu = 9, WMPropertiesWindowType_ToolTip = 10,
  WMPropertiesWindowType_Notification = 11, WMPropertiesWindowType_Combo = 12, WMPropertiesWindowType_Drag_N_Drop = 13, WMPropertiesWindowType_Reserved14 = 14,
  WMPropertiesWindowType_Reserved15 = 15, WMPropertiesWindowType_StateMask = 0xfffC0, WMPropertiesWindowType_NoState = 0, WMPropertiesWindowType_Modal = 0x00040,
  WMPropertiesWindowType_Sticky = 0x00080, WMPropertiesWindowType_VMax = 0x00100, WMPropertiesWindowType_HMax = 0x00200, WMPropertiesWindowType_FullScreen = 0x00400,
  WMPropertiesWindowType_Hidden = 0x00800, WMPropertiesWindowType_Shaded = 0x01000, WMPropertiesWindowType_SkipTaskbar = 0x02000, WMPropertiesWindowType_SkipPager = 0x04000,
  WMPropertiesWindowType_Above = 0x08000, WMPropertiesWindowType_Below = 0x10000, WMPropertiesWindowType_Focused = 0x20000, WMPropertiesWindowType_DemandsAttention = 0x40000,
  WMPropertiesWindowType_Reserved80000 = 0x80000, WMPropertiesWindowType_Max = 0x80000000
}
 Window type enumeration. Reserved for future implementation. More...
 
enum  WMPropertiesWMProtocols {
  WMPropertiesWMProtocols_Mask = 0xff, WMPropertiesWMProtocols_None = 0x0, WMPropertiesWMProtocols_DeleteWindow = 0x01, WMPropertiesWMProtocols_Reserved2 = 0x02,
  WMPropertiesWMProtocols_Reserved3 = 0x04, WMPropertiesWMProtocols_Reserved4 = 0x08, WMPropertiesWMProtocols_Reserved5 = 0x10, WMPropertiesWMProtocols_Reserved6 = 0x20,
  WMPropertiesWMProtocols_Reserved7 = 0x40, WMPropertiesWMProtocols_Reserved8 = 0x80
}
 Window WMProtocols support enumeration. 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, int iFlags, XSetWindowAttributes *pXSWA)
 Create a window. More...
 
void WBDestroyWindow (Window wID)
 Destroy a window. More...
 
Window WBGetApplicationWindow (void)
 Destroy a window. More...
 
void WBSetApplicationWindow (Window wID)
 Destroy a 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 WBSetWMProperties (Window wID, const char *szTitle, XSizeHints *pNormalHints, XWMHints *pWMHints, XClassHint *pClassHints)
 assign standard WM (Window Manager) properties via XSetWMProperties More...
 
void WBSetWindowTitle (Window wID, const char *szTitle)
 assign window (and icon) title More...
 
void WBSetWMPropertiesWindowType (Window wID, enum WMPropertiesWindowType wmProp)
 assign standard WM (Window Manager) 'window type' properties BEFORE mapping it (reserved) More...
 
void WBChangeWMPropertiesWindowType (Window wID, enum WMPropertiesWindowType wmPropSet, enum WMPropertiesWindowType wmChangeMask)
 re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved) More...
 
enum WMPropertiesWindowType WBGetWMPropertiesWindowType (Window wID)
 re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved) More...
 
void WBSetWMProtocols (Window wID, Atom aProperty,...)
 re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved) 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 WBSetWindowFontStruct (Window wID, XFontStruct *pFontStruct)
 assigns the default XFontStruct to a window More...
 
void WBSetWindowFontSet (Window wID, XFontSet fontSet)
 assigns the default XFontSet to a window More...
 
void WBSetWindowDefaultCursor (Window wID, int idStandardCursor)
 Assigns a default cursor (by ID) to a window. More...
 
int WBGetWindowDefaultCursor (Window wID)
 returns the default cursor ID for a window More...
 
void WBCreateWindowDefaultGC (Window wID, unsigned long clrFG, unsigned long clrBG)
 creates a default GC for a window More...
 
void WBSetWindowDefaultGC (Window wID, GC hGC)
 assigns a default GC to a window More...
 
GC WBGetWindowCopyGC (Window wID)
 makes a copy of the default GC so that it can be modified More...
 
GC WBCopyDrawableGC (Display *pDisplay, Drawable dw, GC gcSrc)
 makes a copy of the specified GC for the desired 'Drawable' More...
 
XFontStruct * WBGetGCFont (Display *pDisplay, GC gc)
 return a copy of the XFontStruct that was assigned to a GC More...
 
void WBSetWindowData (Window wID, int iIndex, void *pData)
 assign 'data pointer' for a window and specified index value More...
 
void WBBeginWaitCursor (Window wID)
 increment 'wait cursor' count, set cursor to WB_WAIT_CURSOR More...
 
void WBEndWaitCursor (Window wID)
 decrement 'wait cursor' count, restore to default when zero More...
 
void WBSetWindowCursor (Window wID, int idCursor)
 immediately set the window cursor More...
 
void WBRestoreDefaultCursor (Window wID)
 restore the default cursor More...
 
GC WBGetWindowDefaultGC (Window wID)
 Returns the default GC currently assigned to the window. More...
 
XFontStruct * WBGetWindowFontStruct (Window wID)
 Returns the current XFontStruct pointer assigned to the window (may be NULL) More...
 
XFontSet WBGetWindowFontSet (Window wID)
 Returns the current XFontSet assigned to the window (may be None) 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...
 
unsigned long WBGetGCFGColor (Display *pDisplay, GC gc)
 returns the currently assigned foreground color for a GC More...
 
unsigned long WBGetGCBGColor (Display *pDisplay, GC gc)
 returns the currently assigned background color for a GC 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...
 
void WBGetWindowGeom (Window wID, WB_GEOM *pGeom)
 Returns the RAW geometry of the window as reported by the window manager. More...
 
void WBGetWindowGeom2 (Window wID, WB_GEOM *pGeom)
 Returns the geometry of the window relative to the root window. More...
 
void WBGetWindowGeom0 (Window wID, WB_GEOM *pGeom)
 Returns the ABSOLUTE window geometry relative the screen. More...
 
void WBGetWindowRect (Window wID, WB_RECT *pRect)
 Returns the WB_RECT (rectangle) defined by the window's geometry, including the border area. More...
 
void WBGetClientRect (Window wID, WB_RECT *pRect)
 Returns the WB_RECT (rectangle) defined by the window's geometry, excluding the border area. 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 WBXlatCoordPoint (Window wIDSrc, int iXSrc, int iYSrc, Window wIDDest, int *piXDest, int *piYDest)
 Translate X,Y point coordinates relative to a window. More...
 
void WBXlatCoordGeom (Window wIDSrc, const WB_GEOM *pGeomSrc, Window wIDDest, WB_GEOM *pGeomDest)
 Translate geometry coordinates relative to a window. More...
 
void WBXlatCoordRect (Window wIDSrc, const WB_RECT *pRectSrc, Window wIDDest, WB_RECT *pRectDest)
 Translate rectangle coordinates relative to a window. More...
 
int WBPointInWindow (Window wIDRef, int iX, int iY, Window wIDQuery)
 Returna a non-zero value if X,Y coordinates relative to the reference window are within the query window. More...
 
void WBRegisterMenuCallback (Window wID, WBWinEvent pCallback)
 (internal) Register a MENU callback for a window More...
 
void WBAddMenuWindow (Window wID, Window wIDMenu)
 Add a MENU WINDOW to a (frame) window - more than one is possible, only one currently supported. 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...
 

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.

Macro Definition Documentation

#define WB_KEYBOARD_INPUT_MASK   (KeyPressMask | KeyReleaseMask)

'Keyboard' input mask, bit flag for window creation

'Keyboard' input mask. Use this as a parameter to XSelectInput to enable keyboard events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 992 of file window_helper.h.

#define WB_MOUSE_INPUT_MASK   (ButtonPressMask | ButtonReleaseMask | PointerMotionMask | EnterWindowMask | LeaveWindowMask)

'Mouse' input mask, bit flag for window creation

'Mouse' input mask. Use this as a parameter to XSelectInput to enable mouse events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 1000 of file window_helper.h.

#define WB_STANDARD_INPUT_MASK   (FocusChangeMask | PropertyChangeMask | ExposureMask | StructureNotifyMask | VisibilityChangeMask | SubstructureNotifyMask)

'Standard' input mask, bit flag for window creation

'Standard' input mask. Use this as a parameter to XSelectInput to enable standard events to be sent to the window
This bit mask may be 'or'd with other bit masks as needed.

Definition at line 984 of file window_helper.h.

#define WBGeomOverlapped (   G1,
  G2 
)
Value:
((((G1).x >= (G2).x && (G1).x < (G2).x + (G2).width) || \
((G2).x >= (G1).x && (G2).x < (G1).x + (G1).width)) && \
(((G1).y >= (G2).y && (G1).y < (G2).y + (G2).height) || \
((G2).y >= (G1).y && (G2).y < (G1).y + (G1).height)))

Returns logical TRUE if the geometry G1 overlaps/intersects G2.

Parameters
G1A WB_GEOM structure bounding the first area to check
G2A second WB_GEOM structure bounding the second area to check
Returns
logical TRUE if the two WB_GEOMs intersect, FALSE otherwise

Definition at line 1811 of file window_helper.h.

#define WBGetWindowCopyGC2 (   wID,
  gcSrc 
)    WBCopyDrawableGC(WBGetWindowDisplay(wID), wID, gcSrc)

makes a copy of the specified GC for the desired window

Parameters
wIDThe Window ID for which to copy the GC
gcSrcThe source 'GC'
Returns
A copy of the GC for the specified window

Essentially, it works the same as WBGetWindowCopyGC() except it uses gcSrc instead of the window's 'default GC'. (legacy, use WBCopyDrawableGC() instead)

Header File: window_helper.h

Definition at line 1417 of file window_helper.h.

#define WBPointInGeom (   X,
  Y,
 
)    ((X) >= (G).x && (X) < ((G).x + (G).width) && (Y) >= (G).y && (Y) < ((G).y + (G).height))

Returns logical TRUE if the point (X,Y) is within the borders of the geometry 'G'.

Parameters
XThe X value to check for
YThe Y value to check for
GA WB_GEOM structure bounding the area to check
Returns
logical TRUE if (X,Y) lies within 'G', FALSE otherwise

Definition at line 1791 of file window_helper.h.

#define WBPointInRect (   X,
  Y,
 
)    ((X) >= (R).left && (X) < (R).right && (Y) >= (R).top && (Y) < (R).bottom)

Returns logical TRUE if the point (X,Y) is within the borders of the rectangle 'R'.

Parameters
XThe X value to check for
YThe Y value to check for
RA WB_RECT structure bounding the area to check
Returns
logical TRUE if (X,Y) lies within 'R', FALSE otherwise

Definition at line 1782 of file window_helper.h.

#define WBRectOverlapped (   R1,
  R2 
)
Value:
((((R1).left >= (R2).left && (R1).left < (R2).right) || \
((R2).left >= (R1).left && (R2).left < (R1).right)) && \
(((R1).top >= (R2).top && (R1).top < (R2).bottom) || \
((R2).top >= (R1).top && (R2).top < (R1).bottom)))

Returns logical TRUE if the rectangle R1 overlaps/intersects R2.

Parameters
R1A WB_RECT structure bounding the first area to check
R2A second WB_RECT structure bounding the second area to check
Returns
logical TRUE if the two WB_RECTs intersect, FALSE otherwise

Definition at line 1799 of file window_helper.h.

Typedef Documentation

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

callback definition for WBLocateWindow

Parameters
wIDThe ID of the window being enumerated
pDataThe 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 1279 of file window_helper.h.

Enumeration Type Documentation

Window type enumeration. Reserved for future implementation.

reserved for future implementation

Definition at line 1009 of file window_helper.h.

Window WMProtocols support enumeration.

Bit flags indicating support for known WM_PROTOCOLS window manager features

Definition at line 1062 of file window_helper.h.

Function Documentation

void WBAddMenuWindow ( Window  wID,
Window  wIDMenu 
)

Add a MENU WINDOW to a (frame) window - more than one is possible, only one currently supported.

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

Header File: window_helper.h

Definition at line 7217 of file window_helper.c.

int WBAppDefault ( XEvent *  pEvent)

implements the default application event callback behavior

Header File: window_helper.h

Definition at line 4961 of file window_helper.c.

void WBBeginWaitCursor ( Window  wID)

increment 'wait cursor' count, set cursor to WB_WAIT_CURSOR

Parameters
wIDThe Window ID to which the wait cursor needs to be assigned

Header File: window_helper.h

Definition at line 6437 of file window_helper.c.

void WBChangeWMPropertiesWindowType ( Window  wID,
enum WMPropertiesWindowType  wmPropSet,
enum WMPropertiesWindowType  wmChangeMask 
)

re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved)

Parameters
wIDThe Window ID for the window
wmPropSetA set of enumerated bit values from the WMPropertiesWindowType enumeration
wmChangeMaskA mask for the enumerated bit values to change from the WMPropertiesWindowType enumeration
See Also
latest WM spec WM spec v 1.3

Header File: window_helper.h

Definition at line 3146 of file window_helper.c.

GC WBCopyDrawableGC ( Display *  pDisplay,
Drawable  dw,
GC  gcSrc 
)

makes a copy of the specified GC for the desired 'Drawable'

Parameters
pDisplayA pointer to the 'Display' for the drawable. NULL implies the default display.
dwThe 'Drawable' for which to copy the original GC (None uses the 'default' window)
gcSrcThe source 'GC'
Returns
A copy of the GC for the specified 'Drawable'

Makes a copy of the specified GC. Useful if you want to make temporary modifications to a GC for a particular drawing operation, but don't want to actually modify the original GC.

Header File: window_helper.h

Definition at line 5858 of file window_helper.c.

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

Create a window.

Parameters
pDisplayA pointer to the display
wIDParentThe parent window, or 'None'
pProcA pointer to the event handler proc
szClassThe name of the window's class (mostly for debugging)
iXThe X position of the window
iYThe Y position of the window
iWidthThe width of the window
iHeightThe height of the window
iBorderThe border width of the window
iIOThe I/O type of the window (Input, InputOutput, etc.)
iFlagsThe flags indicating which bits are valid in the XSetWindowAttributes structure
pXSWAA pointer to the XSetWindowAttributes structure
Returns
A valid Window ID, or 'None' on error

Call this function to create a window, in lieu of 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.

Header File: window_helper.h

Definition at line 2801 of file window_helper.c.

void WBCreateWindowDefaultGC ( Window  wID,
unsigned long  clrFG,
unsigned long  clrBG 
)

creates a default GC for a window

Parameters
wIDThe Window ID for which to assign the colors
clrFGThe foreground color
clrBGThe background color

Header File: window_helper.h

Definition at line 5759 of file window_helper.c.

int WBDefault ( Window  wID,
XEvent *  pEvent 
)

implements the default window event callback behavior

Header File: window_helper.h

Definition at line 4966 of file window_helper.c.

void WBDefaultStandardColormap ( Display *  pDisplay,
XStandardColormap *  pMap 
)

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

Parameters
pDisplayThe display for which to obtain the XStandardColormap. This will use its default Colormap
pMapA 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 6010 of file window_helper.c.

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 2292 of file window_helper.c.

void WBEndWaitCursor ( Window  wID)

decrement 'wait cursor' count, restore to default when zero

Parameters
wIDThe Window ID to which the cursor needs to be restored

Header File: window_helper.h

Definition at line 6478 of file window_helper.c.

Window WBGetApplicationWindow ( void  )

Destroy a 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 3313 of file window_helper.c.

void WBGetClientRect ( Window  wID,
WB_RECT pRect 
)

Returns the WB_RECT (rectangle) defined by the window's geometry, excluding the border area.

Parameters
wIDThe Window ID to obtain the WB_RECT data for
pRectA pointer to the WB_RECT structure to receive the data

Header File: window_helper.h

Definition at line 6787 of file window_helper.c.

unsigned long WBGetGCBGColor ( Display *  pDisplay,
GC  gc 
)

returns the currently assigned background color for a GC

Parameters
pDisplayA pointer to the Display
gcThe GC to be queried
Returns
The currently assigned background color

If the current background color cannot be determined, this function will return the pre-defined color for WHITE on the specified Display and default screen

Header File: window_helper.h

Definition at line 5989 of file window_helper.c.

unsigned long WBGetGCFGColor ( Display *  pDisplay,
GC  gc 
)

returns the currently assigned foreground color for a GC

Parameters
pDisplayA pointer to the Display
gcThe GC to be queried
Returns
The currently assigned foreground color

If the current foreground color cannot be determined, this function will return the pre-defined color for BLACK on the specified Display and default screen

Header File: window_helper.h

Definition at line 5969 of file window_helper.c.

XFontStruct* WBGetGCFont ( Display *  pDisplay,
GC  gc 
)

return a copy of the XFontStruct that was assigned to a GC

Parameters
pDisplayA pointer to the Display
gcThe GC to be queried
Returns
A pointer to an XFontStruct, or NULL on error. non-NULL values must be freed via XFreeFont()

Call this function to determine the font that has been assigned to a GC. If there has been NO font assigned, the system default font information will be returned. The return value is always a new pointer to an XFontStruct, or NULL on error. The caller must free non-NULL return values via XFreeFont().

Header File: window_helper.h

Definition at line 5891 of file window_helper.c.

Window WBGetMenuWindow ( Window  wID)

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

Parameters
wIDThe 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 7233 of file window_helper.c.

Window WBGetParentWindow ( Window  wID)

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

Parameters
wIDThe Window ID to obtain the parent for
Returns
The Window ID of the parent, or None

Header File: window_helper.h

Definition at line 7037 of file window_helper.c.

unsigned long WBGetWindowBGColor ( Window  wID)

Returns the currently assigned background color.

Parameters
wIDThe Window ID from which to obtain the background color
Returns
The current background color for the window

Header File: window_helper.h

Definition at line 5957 of file window_helper.c.

const char* WBGetWindowClassName ( Window  wID)

Returns the window's assigned class name pointer.

Parameters
wIDThe 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 6338 of file window_helper.c.

GC WBGetWindowCopyGC ( Window  wID)

makes a copy of the default GC so that it can be modified

Parameters
wIDThe Window ID from which to copy the GC
Returns
A copy of the default GC for the specified window

Header File: window_helper.h

Definition at line 5830 of file window_helper.c.

void* WBGetWindowData ( Window  wID,
int  iIndex 
)

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

Parameters
wIDThe Window ID to obtain window data for
iIndexThe 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 6350 of file window_helper.c.

int WBGetWindowDefaultCursor ( Window  wID)

returns the default cursor ID for a window

Parameters
wIDThe Window ID from which to return the default cursor
Returns
The Cursor ID (Typically an XC_ definition from X11/cursorfont.h). A value of '-1' equates to 'None'

Header File: window_helper.h

Definition at line 6427 of file window_helper.c.

GC WBGetWindowDefaultGC ( Window  wID)

Returns the default GC currently assigned to the window.

Parameters
wIDThe Window ID from which to obtain the default GC
Returns
The default GC associated with the specified window. This is the actual GC, not a copy.

Each window that is mapped within the API will have a 'default GC' associated with it. This GC should not be modified unless you want the changes to remain for the next time a GC is required. A preferred method is to re-assign a new default GC with the new settings, or create a copy of the default GC as a 'starting point', then modify the copy as needed to perform the desired operation. This, in fact, will happen every time you use the API to handle Expose events, via the WBBeginPaint() and WBEndPaint() functions, where the paint GC is a modified version of the default GC.

Header File: window_helper.h

Definition at line 5818 of file window_helper.c.

Display* WBGetWindowDisplay ( Window  wID)

returns the Display associated with a window

Parameters
wIDThe 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 5651 of file window_helper.c.

unsigned long WBGetWindowFGColor ( Window  wID)

Returns the currently assigned foreground color.

Parameters
wIDThe Window ID from which to obtain the foreground color
Returns
The current foreground color for the window

Header File: window_helper.h

Definition at line 5945 of file window_helper.c.

XFontSet WBGetWindowFontSet ( Window  wID)

Returns the current XFontSet assigned to the window (may be None)

Parameters
wIDThe Window ID from which to obtain the current XFontStruct pointer
Returns
The assigned XFontSet, or 'None' on error

Header File: window_helper.h

Definition at line 6311 of file window_helper.c.

XFontStruct* WBGetWindowFontStruct ( Window  wID)

Returns the current XFontStruct pointer assigned to the window (may be NULL)

Parameters
wIDThe Window ID from which to obtain the current XFontStruct pointer
Returns
A pointer to the assigned XFontStruct, or NULL on error

Header File: window_helper.h

Definition at line 6294 of file window_helper.c.

void WBGetWindowGeom ( Window  wID,
WB_GEOM pGeom 
)

Returns the RAW geometry of the window as reported by the window manager.

Parameters
wIDThe Window ID to obtain the WB_GEOM data for
pGeomA pointer to the WB_GEOM structure to receive the data

Header File: window_helper.h

Definition at line 6601 of file window_helper.c.

void WBGetWindowGeom0 ( Window  wID,
WB_GEOM pGeom 
)

Returns the ABSOLUTE window geometry relative the screen.

Parameters
wIDThe Window ID to obtain the WB_GEOM data for
pGeomA pointer to the WB_GEOM structure to receive the data

The 'ABSOLUTE' window geometry is the position of the window relative to the origin point (the upper left corner of the screen). Window managers typically cook all of the XEvent and API data that relates to window positioning, such that a top level frame window's upper left corner is nearly always reported as 0,0 (or similar). Not all window managers behave the same in this regard. To ensure that an ABSOLUTE window position is known (helpful for centering on screen, etc.), the absolute coordinates are frequently cached within the internal data structure associated with the window. Those cached values are returned by this function.

Header File: window_helper.h

Definition at line 6552 of file window_helper.c.

void WBGetWindowGeom2 ( Window  wID,
WB_GEOM pGeom 
)

Returns the geometry of the window relative to the root window.

Parameters
wIDThe Window ID to obtain the WB_GEOM data for
pGeomA pointer to the WB_GEOM structure to receive the data

Header File: window_helper.h

Definition at line 6686 of file window_helper.c.

void WBGetWindowRect ( Window  wID,
WB_RECT pRect 
)

Returns the WB_RECT (rectangle) defined by the window's geometry, including the border area.

Parameters
wIDThe Window ID to obtain the WB_RECT data for
pRectA pointer to the WB_RECT structure to receive the data

Header File: window_helper.h

Definition at line 6772 of file window_helper.c.

enum WMPropertiesWindowType WBGetWMPropertiesWindowType ( Window  wID)

re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved)

Parameters
wIDThe Window ID for the window
Returns
A bitmask consisting of WMPropertiesWindowType enumeration values.

These values are cached from WBSetWMPropertiesWindowType() and WBChangeWMPropertiesWindowType()

Header File: window_helper.h

Definition at line 3154 of file window_helper.c.

int WBIsChildWindow ( Window  wIDParent,
Window  wIDChild 
)

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

Parameters
wIDParentThe Window ID for the 'test' parent window
wIDChildThe 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 7093 of file window_helper.c.

Window WBLocateWindow ( WBLocateWindowCallback  callback,
void *  pData 
)

Locate a window by enumerating with a callback function.

Parameters
callbackA pointer to a callback function to call for each enumerated window - see WBLocateWindowCallback
pDataA 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 3281 of file window_helper.c.

int WBPointInWindow ( Window  wIDRef,
int  iX,
int  iY,
Window  wIDQuery 
)

Returna a non-zero value if X,Y coordinates relative to the reference window are within the query window.

Parameters
wIDRefThe reference Window ID
iXThe X coordinates relative to wIDRef
iYThe Y coordinates relative to wIDRef
wIDQueryThe Window ID of the window to test the translated X and Y values against
Returns
Non-zero if the (X,Y) coordinates are within wIDQuery, zero otherwise.

Use this function to see if coordinates relative to one window also fall within another window. Typical use includes 'hover' detection, drag/drop operations, and child window activation To specify X,Y screen coordinates, pass 'None' for 'wIDRef'

Header File: window_helper.h

Definition at line 6898 of file window_helper.c.

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 2437 of file window_helper.c.

void WBRegisterMenuCallback ( Window  wID,
WBWinEvent  pCallback 
)

(internal) Register a MENU callback for a window

Header File: window_helper.h

Definition at line 7203 of file window_helper.c.

void WBRegisterWindowCallback ( Window  wID,
WBWinEvent  pCallback 
)

register callback function for a window (required)

Header File: window_helper.h

Definition at line 3047 of file window_helper.c.

void WBRemoveMenuWindow ( Window  wID,
Window  wIDMenu 
)

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

Parameters
wIDThe Window ID for which to remove a menu Window ID
wIDMenuThe Window ID of the menu window to remove

Header File: window_helper.h

Definition at line 7249 of file window_helper.c.

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

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

Parameters
wIDThe Window ID of the target (to be adopted) window
wIDParentThe new parent Window ID. Congratulations, it's a Window!
iXThe new X location for the window specified by wID (see XReparentWindow)
iYThe 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 7072 of file window_helper.c.

void WBRestoreDefaultCursor ( Window  wID)

restore the default cursor

Parameters
wIDThe Window ID to which the default cursor needs to be restored

Header File: window_helper.h

Definition at line 6538 of file window_helper.c.

void WBSetApplicationWindow ( Window  wID)

Destroy a window.

Parameters
wIDThe 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 3318 of file window_helper.c.

void WBSetInputFocus ( Window  wID)

set input focus to a specific window

Parameters
wIDThe 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 2239 of file window_helper.c.

void WBSetParentWindow ( Window  wID,
Window  wIDParent 
)

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

Parameters
wIDThe Window ID of the target
wIDParentThe 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 7064 of file window_helper.c.

void WBSetWindowClassName ( Window  wID,
const char *  szClassName 
)

Assignes the window's class name pointer.

Parameters
wIDThe Window ID to assign a 'class name' to
szClassNameA 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 6328 of file window_helper.c.

void WBSetWindowCursor ( Window  wID,
int  idCursor 
)

immediately set the window cursor

Parameters
wIDThe Window ID to which the cursor needs to be assigned
idCursorThe Cursor ID (Typically an XC_ definition from X11/cursorfont.h). A value of '-1' equates to 'None'

Header File: window_helper.h

Definition at line 6526 of file window_helper.c.

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

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

Parameters
wIDThe Window ID to which to assign the data pointer
iIndexThe 0-based index that identifies the entry
pDataThe data pointer to assign (may be NULL)

Header File: window_helper.h

Definition at line 5808 of file window_helper.c.

void WBSetWindowDefaultCursor ( Window  wID,
int  idStandardCursor 
)

Assigns a default cursor (by ID) to a window.

Parameters
wIDThe Window ID from which to return the default cursor
idStandardCursorThe default Cursor ID to assign (Typically an XC_ definition from X11/cursorfont.h). A value of '-1' equates to 'None'

Header File: window_helper.h

Definition at line 6414 of file window_helper.c.

void WBSetWindowDefaultGC ( Window  wID,
GC  hGC 
)

assigns a default GC to a window

Parameters
wIDThe Window ID for which to assign the GC
hGCThe GC to assign

Header File: window_helper.h

Definition at line 5793 of file window_helper.c.

void WBSetWindowFontSet ( Window  wID,
XFontSet  fontSet 
)

assigns the default XFontSet to a window

Parameters
wIDThe Window ID from which to return the default cursor
fontSetAn XFontSet for the window. This value will be 'owned' by the window. To use the default font set, assign a value of 'None'

Header File: window_helper.h

Definition at line 5733 of file window_helper.c.

void WBSetWindowFontStruct ( Window  wID,
XFontStruct *  pFontStruct 
)

assigns the default XFontStruct to a window

Parameters
wIDThe Window ID from which to return the default cursor
pFontStructA pointer to an XFontStruct that describes the font. This value will be 'owned' by the window. To use the default font, assign a value of NULL

Header File: window_helper.h

Definition at line 5706 of file window_helper.c.

void WBSetWindowIcon ( Window  wID,
int  idIcon 
)

assigns an icon resource (by ID) to a window

Parameters
wIDThe Window ID from which to return the default cursor
idIconThe resource ID for the window's icon

Header File: window_helper.h

Definition at line 5663 of file window_helper.c.

void WBSetWindowTitle ( Window  wID,
const char *  szTitle 
)

assign window (and icon) title

Parameters
wIDThe Window ID for the window
szTitleA const pointer to a character string containing the window title

Header File: window_helper.h

Definition at line 3022 of file window_helper.c.

void WBSetWMProperties ( Window  wID,
const char *  szTitle,
XSizeHints *  pNormalHints,
XWMHints *  pWMHints,
XClassHint *  pClassHints 
)

assign standard WM (Window Manager) properties via XSetWMProperties

Parameters
wIDThe Window ID for the window
szTitleA const pointer to a character string containing the window title
pNormalHintsThe pointer to the XSiteHints data, or NULL
pWMHintsThe pointer to the XWMHints data, or NULL
pClassHintsThe pointer to the XClassHint data, or NULL

Header File: window_helper.h

Definition at line 2870 of file window_helper.c.

void WBSetWMPropertiesWindowType ( Window  wID,
enum WMPropertiesWindowType  wmProp 
)

assign standard WM (Window Manager) 'window type' properties BEFORE mapping it (reserved)

Parameters
wIDThe Window ID for the window
wmPropAn inclusive set of enumerated bit values from the WMPropertiesWindowType enumeration
See Also
latest WM spec WM spec v 1.3

Header File: window_helper.h

Definition at line 3136 of file window_helper.c.

void WBSetWMProtocols ( Window  wID,
Atom  aProperty,
  ... 
)

re-assign standard WM (Window Manager) 'window type' properties and notify the root window (reserved)

Parameters
wIDThe Window ID for the window
aPropertyThe atoms to be assigned to the supported WM Protocols list

Additional parameters are all Atom values, the last one being 'None' to mark the end of the list. These Atoms will be assigned to the WM_PROTOCOLS property via XSetWMProtocols(). In some cases, the behavior of the toolkit will change depending on the atoms that are assigned. This assignment should ONLY be done on top-level windows, and only at the time of window creation.

Header File: window_helper.h

Definition at line 3169 of file window_helper.c.

void WBUnregisterAppCallback ( )

unregister callback function for application events

Header File: window_helper.h

Definition at line 2442 of file window_helper.c.

void WBUnregisterWindowCallback ( Window  wID)

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

Header File: window_helper.h

Definition at line 3069 of file window_helper.c.

void WBXlatCoordGeom ( Window  wIDSrc,
const WB_GEOM pGeomSrc,
Window  wIDDest,
WB_GEOM pGeomDest 
)

Translate geometry coordinates relative to a window.

Parameters
wIDSrcThe source Window ID
pGeomSrcA const pointer to a WB_GEOM structure containing the coordinates to translate
wIDDestThe destination Window ID
pGeomDestA pointer to a WB_GEOM structure that receives the translated coordinates

For many operations, coordinates relative to one window must be translated into coordinates relative to a different window so that they can be used for the new window's processing.
To translate from screen coordinates, pass 'None' for 'wIDSrc'

Header File: window_helper.h

Definition at line 6841 of file window_helper.c.

void WBXlatCoordPoint ( Window  wIDSrc,
int  iXSrc,
int  iYSrc,
Window  wIDDest,
int *  piXDest,
int *  piYDest 
)

Translate X,Y point coordinates relative to a window.

Parameters
wIDSrcThe source Window ID
iXSrcThe X coordinate within wIDSrc
iYSrcThe Y coordinate within wIDSrc
wIDDestThe destination Window ID
piXDestA pointer to an integer to receive the translated X coordinate
piYDestA pointer to an integer to receive the translated Y coordinate

For many operations, coordinates relative to one window must be translated into coordinates relative to a different window so that they can be used for the new window's processing.
To translate from screen coordinates, pass 'None' for 'wIDSrc'

Header File: window_helper.h

Definition at line 6806 of file window_helper.c.

void WBXlatCoordRect ( Window  wIDSrc,
const WB_RECT pRectSrc,
Window  wIDDest,
WB_RECT pRectDest 
)

Translate rectangle coordinates relative to a window.

Parameters
wIDSrcThe source Window ID
pRectSrcA const pointer to a WB_RECT structure containing the coordinates to translate
wIDDestThe destination Window ID
pRectDestA pointer to a WB_RECT structure that receives the translated coordinates

For many operations, coordinates relative to one window must be translated into coordinates relative to a different window so that they can be used for the new window's processing.
To translate from screen coordinates, pass 'None' for 'wIDSrc'

Header File: window_helper.h

Definition at line 6871 of file window_helper.c.