X11workbench Toolkit  1.0
Default Parameters and Definitions

Typedefs

typedef struct tagWBExtent WB_EXTENT
 internal wrapper struct for 'extent' definition More...
 
static __inline__ Display * WBGetDefaultDisplay (void)
 Returns the default Display. More...
 
WB_FONTC WBGetDefaultFont (void)
 Returns a pointer to the default font WB_FONT for the default display. This is a shared resource; do NOT free it nor alter it! More...
 
Window WBGetHiddenHelperWindow (void)
 Returns a special 'hidden' window used for information purposes. More...
 
Display * WBInit (const char *szDisplayName)
 initializes default objects for the specified Display (required) More...
 
int WBInitDisplay (Display *pDisplay)
 initializes default objects for the specified Display More...
 
int WBInitClipboardSystem (Display *pDisplay, const char *szDisplayName)
 initializes clipboard sub-system More...
 
int __StartInitClipboardSystem (Display *pDisplay, const char *szDisplayName)
 
int __FinishInitClipboardSystem (Display *pDisplay, const char *szDisplayName)
 
void WBExit (void)
 deletes any remaining global objects, frees the Display pointer, and terminates event processing More...
 
void WBExitClipboardSystem (Display *pDisplay)
 Shut down the clipboard sub-system. More...
 
Display * WBThreadInitDisplay (void)
 initializes default Display for a thread (must call WBInit() first) More...
 
void WBThreadFreeDisplay (Display *pThreadDisplay)
 un-initializes a Display for a thread that was allocated by WBThreadInitDisplay() More...
 
const char * GetStartupDisplayName (void)
 returns character name of the display to be opened and passed to WBInit More...
 
void GetStartupGeometry (WB_GEOM *pGeom)
 returns the startup geometry based on command line parameters More...
 
int GetStartupMinMax (void)
 returns the min/max/normal window state for startup More...
 
static __inline__ Colormap WBDefaultColormap (Display *pDisplay)
 returns the default colormap for the default screen of the specified display More...
 
void WBInitWindowAttributes (XSetWindowAttributes *pXSWA, unsigned long lBorderPixel, unsigned long lBackgroundPixel, Colormap clrMap, int iBitGravity)
 initializes the XSetWIndowAttributes structure with minimal attributes More...
 
void WBInitSizeHints (XSizeHints *pSH, Display *pDisplay, int iMinHeight, int iMinWidth)
 initializes the XSizeHints structure with standard attributes More...
 
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...
 
void WBSetWMProperties (Window wID, const char *szTitle, XSizeHints *pNormalHints, XWMHints *pWMHints, XClassHint *pClassHints)
 assign standard WM (Window Manager) properties via XSetWMProperties 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 WBSetWindowFont (Window wID, WB_FONTC pFont)
 assigns the default WB_FONT object for 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 WBGC for a window More...
 
void WBSetWindowDefaultGC (Window wID, WBGC hGC)
 assigns a default WBGC to a window More...
 
WBGC WBGetWindowCopyGC (Window wID)
 makes a copy of the default WBGC so that it can be modified 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...
 
WBGC WBGetWindowDefaultGC (Window wID)
 Returns the default WBGC currently assigned to the window (not a copy) 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...
 
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...
 
int WBKeyEventProcessKey (const XKeyEvent *pEvent, char *pBuf, int *pcbLen, int *piAltCtrlShift)
 Generic keyboard event translation utility. 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...
 
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...
 
Time WBGetLastEventTime (void)
 Main message loop, high level API to check for and retrieve the next event. More...
 
int WBCheckGetEvent (Display *pDisplay, XEvent *pEvent)
 Main message loop, high level API to check for and retrieve the next event. More...
 
void WBWaitForEvent (Display *pDisplay)
 Wait for an event, blocking indefinitely. More...
 
void WBDispatch (XEvent *pEvent)
 Generic Event Dispatcher, using message type to dispatch. More...
 
int WBAppDispatch (XEvent *pEvent)
 Dispatches an application XEvent. May be called directly. More...
 
int WBWindowDispatch (Window wID, XEvent *pEvent)
 Dispatches a window XEvent. May be called directly. More...
 
const char * WBEventName (int iEventID)
 debug function to return the name of an X11 event More...
 
int WBShowModal (Window wID, int bMenuSplashFlag)
 Shows a 'modal' window by processing events until the window closes. More...
 
void WBEndModal (Window wID, int iReturn)
 End a modal window with a specific return value. More...
 
int WBNextEvent (Display *pDisplay, XEvent *pEvent)
 low-level event queue wrapper. Implements the client-side event queue. Does not block if no events available. More...
 
int WBPostEvent (Window wID, XEvent *pEvent)
 Places a copy of the specified event at the end of the regular (internal) event queue. More...
 
int WBPostPriorityEvent (Window wID, XEvent *pEvent)
 Places a copy of the specified event at the end of the priority (internal) event queue. More...
 
void WBPostDelayedEvent (XEvent *pEvent, unsigned int nDelay)
 Delays placing a copy of the specified event at the end of the regular (internal) event queue by a specified number of milliseconds. More...
 
int WBPostAppEvent (XEvent *pEvent)
 Places a copy of the specified event at the end of the priority (internal) event queue. More...
 
void WBPostDelayedSetFocusAppEvent (Display *pDisplay, Window wID, Window wIDFrom, unsigned int nDelay)
 Creates a 'set focus' ClientMessage event for the application event handler. More...
 
void WBProcessExposeEvent (XExposeEvent *pEvent)
 low-level event processing, internal handling of Expose events More...
 
void WBMouseCancel (Display *pDisplay, Window wID)
 low-level event processing, internal handling of Expose events More...
 
void * WBGetClipboardData (Display *pDisplay, Atom *paType, int *piFormat, unsigned long *pnData)
 Get clipboard data of requested type. More...
 
int WBSetClipboardData (Display *pDisplay, Atom aType, int iFormat, const void *pData, unsigned long nData)
 Get clipboard data of requested type. More...
 
void * WBGetSelectionData (Display *pDisplay, Atom aSelection, Atom *paType, int *piFormat, unsigned long *pnData)
 Get clipboard data of requested type. More...
 
int WBSetSelectionData (Display *pDisplay, Atom aSelection, Atom aType, int iFormat, const void *pData, unsigned long nData)
 Get clipboard data of requested type. More...
 
int WBMapWindow (Display *pDisplay, Window wID)
 Wrapper for XMapWindow, makes window visible. More...
 
int WBMapRaised (Display *pDisplay, Window wID)
 wrapper for XMapRaised, makes window visible and moves to top More...
 
int WBUnmapWindow (Display *pDisplay, Window wID)
 wrapper for XUnmapWindow, makes window invisible without destroying it More...
 
int WBIsMapped (Display *pDisplay, Window wID)
 Returns non-zero if window has been mapped; zero otherwise. More...
 
void WBInvalidateGeom (Window wID, const WB_GEOM *pGeom, int bPaintFlag)
 'Paint' helper, invalidates a geometry for asynchronous Expose event generation More...
 
void WBInvalidateRegion (Window wID, Region rgn, int bPaintFlag)
 'Paint' helper, invalidates a region for asynchronous Expose event generation More...
 
void WBValidateGeom (Window wID, const WB_GEOM *pGeom)
 'Paint' helper, validates a geometry for asynchronous Expose event generation More...
 
void WBValidateRegion (Window wID, Region rgn)
 'Paint' helper, validates a region for asynchronous Expose event generation More...
 
Region WBGetInvalidRegion (Window wID)
 'Paint' helper, returns a copy of the invalid region for a window More...
 
Region WBGetPaintRegion (Window wID)
 'Paint' helper, returns a copy of the current 'paint' region for the window More...
 
Region WBRectToRegion (const WB_RECT *pRect)
 'Paint' helper, converts a WB_RECT structure to a Region. More...
 
Region WBGeomToRegion (const WB_GEOM *pGeom)
 'Paint' helper, converts a WB_GEOM structure to a Region. More...
 
Region WBCopyRegion (Region rgnSource)
 Simple utility to copy a region. More...
 
void WBUpdateWindow (Window wID)
 'Paint' helper, generates an asynchronous Expose event for non-empty 'invalid' region More...
 
void WBUpdateWindowImmediately (Window wID)
 'Paint' helper, generates an immediate Expose event for non-empty 'invalid' region More...
 
WBGC WBBeginPaint (Window wID, XExposeEvent *pEvent, WB_GEOM *pgRet)
 'Paint' helper, creates a WBGC for use in updating the window in an Expose event handler More...
 
WBGC WBBeginPaintGeom (Window wID, WB_GEOM *pgBounds)
 'Paint' helper, creates a WBGC for use in updating the window for a specified rectangular area More...
 
void WBEndPaint (Window wID, WBGC gc)
 'Paint' helper, frees resources and marks the update region 'valid' More...
 
void WBClearWindow (Window wID, WBGC gc)
 'Paint' helper, erases background by painting the background color within the clipping region More...
 
static __inline__ void WBInvalidateRect (Window wID, const WB_RECT *pRCT, int bPaintFlag)
 'Paint' helper, invalidates a WB_RECT for asynchronous Expose event generation More...
 
static __inline__ void WBValidateRect (Window wID, WB_RECT *pRCT)
 'Paint' helper, validates a WB_RECT for asynchronous Expose event generation More...
 
WBGC WBCreateGC (Display *pDisplay, Drawable dw, unsigned long valuemask, const XGCValues *values)
 Creates a WBGC, wrapper for XCreateGC() More...
 
int WBChangeGC (WBGC hGC, unsigned long valuemask, const XGCValues *values)
 Change a WBGC, a wrapper for XChangeGC() More...
 
Status WBGetGCValues (WBGC hGC, unsigned long valuemask, XGCValues *values)
 Change a WBGC, a wrapper for XGetGCValues() More...
 
unsigned long WBGetGCBGColor (WBGC gc)
 returns the currently assigned background color for a WBGC More...
 
unsigned long WBGetGCFGColor (WBGC gc)
 returns the currently assigned foreground color for a WBGC More...
 
WB_FONTC WBQueryGCFont (WBGC gc)
 return the WB_FONTC object that was assigned to a WBGC More...
 
WB_FONT WBGetGCFont (Display *pDisplay, WBGC gc)
 return a copy of the WB_FONT object that was assigned to a WBGC More...
 
WBGC WBCopyGC (WBGC hGCOrig)
 makes a copy of a WBGC, a more sensible wrapper for XCopyGC() More...
 
int WBCopyGC2 (WBGC hGCOrig, unsigned long valuemask, WBGC hGCDest)
 makes a copy of a WBGC, a wrapper for XCopyGC() More...
 
WBGC WBCopyDrawableGC (Display *pDisplay, Drawable dw, WBGC hGCOrig)
 makes a copy of the specified WBGC for the desired 'Drawable' More...
 
void WBFreeGC (WBGC hGC)
 Free resources for a WBGC, wrapper for XFreeGC() More...
 
GContext WBGContextFromGC (WBGC hGC)
 Free resources for a WBGC, wrapper for XGContextFromGC() More...
 
int WBSetRegion (WBGC hGC, Region rgnClip)
 Assign clipping region, wrapper for XSetRegion() More...
 
int WBSetClipOrigin (WBGC hGC, int clip_x_origin, int clip_y_origin)
 Set clip origin, a wrapper for XSetClipOrigin() More...
 
int WBSetClipMask (WBGC hGC, Pixmap pixmap)
 Set clip mask, a wrapper for XSetClipMask() More...
 
int WBSetFunction (WBGC hGC, int function)
 Set the 'function' for the WBGC, a wrapper for XSetFunction() More...
 
static __inline__ unsigned long WBGetForeground (WBGC hGC)
 Get the (cached) foreground color for a WBGC. More...
 
int WBSetForeground (WBGC hGC, unsigned long foreground)
 Assign foreground color, a wrapper for XSetForeground() More...
 
static __inline__ unsigned long WBGetBackground (WBGC hGC)
 Get the (cached) background color for a WBGC. More...
 
int WBSetBackground (WBGC hGC, unsigned long background)
 Assign background color, a wrapper for XSetBackground() More...
 
int WBSetFont (WBGC hGC, WB_FONTC pFont)
 Assign font to a WBGC, a wrapper for XSetFont() More...
 
int WBSetFontNoCopy (WBGC hGC, WB_FONT pFont)
 Assign font to a WBGC, a wrapper for XSetFont() More...
 
int WBSetLineAttributes (WBGC hGC, unsigned int line_width, int line_style, int cap_style, int join_style)
 Assign font to a WBGC, a wrapper for XSetLineAttributes() More...
 
int WBSetDashes (WBGC hGC, int dash_offset, const char dash_list[], int n)
 Assign font to a WBGC, a wrapper for XSetFont() More...
 
XImage * WBGetWindowImage (Display *pDisplay, Window wID)
 Obtain an XImage for the entire window. More...
 
int WBAssignWindowImage (Display *pDisplay, Window wID, XImage *pImage)
 Assign an XImage for the entire window. More...
 
int WBCopyIntoWindowImage (Display *pDisplay, Window wID, XImage *pSrcImage, int xSrc, int ySrc, int width, int height, int xOffs, int yOffs)
 Copy an XImage into the cached XImage for the entire window. More...
 
void WBUpdateWindowWithImage (Display *pDisplay, Window wID)
 Update the window's appearance with the contents of the cached XImage. More...
 
int WBDrawPoint (Display *display, Drawable d, WBGC gc, int x, int y)
 Wrapper for XDrawPoint() More...
 
int WBDrawPoints (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int mode)
 Wrapper for XDrawPoints() More...
 
int WBDrawLine (Display *display, Drawable d, WBGC gc, int x1, int y1, int x2, int y2)
 Wrapper for XDrawLines() More...
 
int WBDrawLines (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int mode)
 Wrapper for XDrawLine() More...
 
int WBDrawRectangle (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height)
 Wrapper for XDrawRectangle() More...
 
int WBFillRectangle (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height)
 Wrapper for XFillRectangle() More...
 
int WBDrawArc (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height, int angle1, int angle2)
 Wrapper for XDrawArc() More...
 
int WBFillArc (Display *display, Drawable d, WBGC gc, int x, int y, unsigned int width, unsigned int height, int angle1, int angle2)
 Wrapper for XFillArc() More...
 
int WBFillPolygon (Display *display, Drawable d, WBGC gc, XPoint *points, int npoints, int shape, int mode)
 Wrapper for XFillPolygon() More...
 
int WBDrawString (Display *display, Drawable d, WBGC gc, int x, int y, const char *string, int length)
 wrapper for XDrawString() More...
 
int CreateTimer (Display *pDisplay, Window wID, unsigned long lInterval, long lID, int iPeriodic)
 Creates a one-shot or periodic timer. More...
 
void DeleteTimer (Display *pDisplay, Window wID, long lID)
 Deletes an existing timer's resources. More...
 
static __inline__ void WBSupressErrorOutput (void)
 Supress X11 XErrorEvent output to stderr. More...
 
static __inline__ void WBAllowErrorOutput (void)
 Restore X11 XErrorEvent output to stderr. More...
 
void WBErrorClear (void)
 Clear the 'last error' information obtained via WBGetLastError() More...
 
int WBErrorCheck (void)
 Check to see whether or not an X11 error was detected. More...
 
int WBErrorCheckRetry (void)
 Check to see whether or not an X11 error was detected AND can be re-tried. More...
 
const WB_ERROR_INFOWBGetLastError (void)
 Obtain a const pointer to the internal WB_ERROR_INFO structure. More...
 
#define WB_DEFAULT_CURSOR   XC_left_ptr
 The default window cursor (this is what xterm uses)
 
#define WB_WAIT_CURSOR   XC_watch /*XC_clock*/
 The 'wait' cursor (this is what xterm uses)
 
#define WB_DEFAULT_FONT   "fixed"
 The default X11 font name (currently "fixed")
 
#define WB_DEFAULT_FONT_SIZE   13 /* override via settings */
 The default X11 font size (currently 13)
 
#define WINDOW_DATA_SIZE   4 /* size of a 'void *' array that stores per-window data */
 The 'window data' array size (currently 4 void pointers)
 
#define EVENT_ALL_MASK   0x01ffffffL /* 2^24 | 2^23 ... 2^0 - see X.h */
 An event mask for ALL events, with bits 0 through 24 set - see X.h which only defines bits 0 to 24 for an event mask.
 
#define GCAll
 A bit mask for ALL GC properties (used when copying a GC) More...
 
#define BEGIN_XCALL_DEBUG_WRAPPER   { const char *__szOldXCallFunc__ = sz_xcall_func; int __iOldXCallLine__ = i_xcall_line; sz_xcall_func = __FUNCTION__; i_xcall_line = __LINE__; {
 wrapper macro for calls into the X11 library. This macro precedes the call(s)
 
#define END_XCALL_DEBUG_WRAPPER   } sz_xcall_func = __szOldXCallFunc__; i_xcall_line = __iOldXCallLine__; }
 wrapper macro for calls into the X11 library. This macro follows the call(s)
 
#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 WBGC 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...
 
#define WB_KEYEVENT_KEYSYM   8 /* bit flags for 'piAltCtrlShift' below */
 'AltCtrlShift' bit flag for 'VK_' keys for WBKeyEventProcessKey()
 
#define WB_KEYEVENT_ALT   4
 'AltCtrlShift' bit flag for ALT modifier for WBKeyEventProcessKey()
 
#define WB_KEYEVENT_CTRL   2
 'AltCtrlShift' bit flag for Control modifier for WBKeyEventProcessKey()
 
#define WB_KEYEVENT_SHIFT   1
 'AltCtrlShift' bit flag for Shift modifier for WBKeyEventProcessKey()
 
#define WB_KEYEVENT_ACSMASK   7
 'AltCtrlShift' bit mask for Alt+Ctrl+Shift bits for WBKeyEventProcessKey()
 
#define WB_POINTER_UNSPECIFIED   0 /* possible motion or state-change notifications */
 Unspecified event, possible motion or state-chagne notification.
 
#define WB_POINTER_CLICK   1
 Mouse 'click' event.
 
#define WB_POINTER_DBLCLICK   2
 WB_POINTER 'double-click' event, send in lieu of WB_POINTER_CLICK for double-click.
 
#define WB_POINTER_DRAG   3 /* window proc returns window ID to support drag/drop */
 WB_POINTER 'drag' event, window proc MUST return the window ID to auto-support drag/drop.
 
#define WB_POINTER_DROP   4 /* may not happen if drag is canceled */
 WB_POINTER 'drop' event, only sent if drag/drop supported AND was not 'canceled'; see WB_POINTER_CANCEL.
 
#define WB_POINTER_MOVE   5 /* motion notify while dragging */
 WB_POINTER 'move' event, for motion notification during drag/drop.
 
#define WB_POINTER_CANCEL   6 /* reservedly any kind of cancellation, but for now, 'drag cancel' */
 WB_POINTER 'cancel' event, cancels an ongoing operation, such as drag/drop (useful for resource cleanup)
 
#define WB_POINTER_SCROLLUP   7 /* scroll event, mouse button 4 */
 WB_POINTER 'scroll up' event, caused by mouse button 4.
 
#define WB_POINTER_SCROLLDOWN   8 /* scroll event, mouse button 5 */
 WB_POINTER 'scroll down' event, caused by mouse button 5.
 
#define WB_POINTER_BUTTON1   1 /* these are bitmasks */
 WB_POINTER button bitmask indicating that button 1 is pressed.
 
#define WB_POINTER_BUTTON2   2
 WB_POINTER button bitmask indicating that button 2 is pressed.
 
#define WB_POINTER_BUTTON3   4
 WB_POINTER button bitmask indicating that button 3 is pressed.
 
#define WB_POINTER_BUTTON4   8
 WB_POINTER button bitmask indicating that button 4 (scroll wheel 'up') is pressed.
 
#define WB_POINTER_BUTTON5   16
 WB_POINTER button bitmask indicating that button 5 (scroll wheel 'down') is pressed.
 
enum  WBScrollEventParam {
  WB_SCROLL_DEFAULT = 0, WB_SCROLL_HORIZONTAL = 1, WB_SCROLL_VERTICAL = 2, WB_SCROLL_KNOB = 0,
  WB_SCROLL_FORWARD = 1, WB_SCROLL_BACKWARD = -1, WB_SCROLL_PAGEFWD = 2, WB_SCROLL_PAGEBACK = -2,
  WB_SCROLL_FIRST = -3, WB_SCROLL_LAST = 3, WB_SCROLL_DBLCLICK = 4, WB_SCROLL_ABSOLUTE = 99,
  WB_SCROLL_RELATIVE = -99, WB_SCROLL_NA = 0x80000000
}
 Enumeration for aSCROLL_NOTIFY ClientMessage. More...
 
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...
 
enum  WBCreateWindow_flags { WBCreateWindow_flagsDefault = 0 }
 WBCreateWindow 'iFlags' additional bits. More...
 
typedef int(* WBWinEvent) (Window wID, XEvent *pEvent)
 event callback function type for window events More...
 
typedef int(* WBAppEvent) (XEvent *pEvent)
 event callback function type definition for application events More...
 
typedef struct tagWBGCWBGC
 internal wrapper struct for GC with local cache More...
 
typedef struct tagWBPoint WB_POINT
 internal wrapper struct for 'point' definition More...
 
typedef struct tagWBExtent WB_EXTENT
 
typedef struct tagWBRect WB_RECT
 internal wrapper struct for 'rectangle' definition More...
 
typedef struct tagWBGeom WB_GEOM
 internal wrapper struct for X11 'geometry' definition More...
 
typedef int(* WBLocateWindowCallback) (Window wID, void *pData)
 callback definition for WBLocateWindow More...
 
typedef struct tagWB_ERROR_INFO WB_ERROR_INFO
 Structure definition for X11 error information. More...
 
const char * sz_xcall_func
 debug helper variable tracking the function calling into the X11 library
 
int i_xcall_line
 debug helper variable indicating the line number of the function calling into the X11 library
 
const Atom aMENU_COMMAND
 commands sent by menus via ClientMessage More...
 
const Atom aMENU_UI_COMMAND
 UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'. More...
 
const Atom aRESIZE_NOTIFY
 notification of window re-size via ClientMessage More...
 
const Atom aDESTROY_NOTIFY
 notify parent that child is being destroyed More...
 
const Atom aCONTROL_NOTIFY
 dialog control and child window notification messages More...
 
const Atom aSCROLL_NOTIFY
 
const Atom aQUERY_CLOSE
 query if it's ok to close (and optionally destroy yourself if ok) a window More...
 
const Atom aRECALC_LAYOUT
 notify window that it should re-calculate things like scrollbars and viewports More...
 
const Atom aDLG_FOCUS
 dialog focus messages More...
 
const Atom aSET_FOCUS
 dialog focus messages More...
 
const Atom aWB_CHAR
 keystroke/character notifications generated by API More...
 
const Atom aWB_TIMER
 timer notifications generated by API More...
 
const Atom aWB_POINTER
 pointer click/double-click/drag notifications generated by API More...
 
const Atom aWM_PROTOCOLS
 WM supported protocols. More...
 
const Atom aWM_DELETE_WINDOW
 Delete Window notification event. More...
 
const Atom aWM_TAKE_FOCUS
 'Take Focus' - TODO document this properly More...
 
const Atom aAVERAGE_WIDTH
 Atoms for fonts - Average Character Width. More...
 
const Atom aCLIPBOARD
 CLIPBOARD Atom for the clipboard. More...
 
const Atom aPRIMARY
 PRIMARY Atom for the clipboard - uses XA_PRIMARY. More...
 
const Atom aSECONDARY
 SECONDARY Atom for the clipboard - uses XA_SECONDARY. More...
 
const Atom aMANAGER
 MANAGER Atom for the clipboard. More...
 
const Atom aTARGET
 TARGET Atom for the clipboard. More...
 
const Atom aINCR
 INCR Atom for the clipboard. More...
 
const Atom aWINDOW
 WINDOW Atom for the clipboard - uses XA_WINDOW. More...
 
const Atom aBITMAP
 BITMAP Atom for the clipboard - uses XA_BITMAP. More...
 
const Atom aDRAWABLE
 DRAWABLE Atom for the clipboard - uses XA_DRAWABLE. More...
 
const Atom aCOLORMAP
 COLORMAP Atom for the clipboard - uses XA_COLORMAP. More...
 
const Atom aPIXEL
 PIXEL Atom for the clipboard. More...
 
const Atom aPIXMAP
 PIXMAP Atom for the clipboard - uses XA_PIXMAP. More...
 
const Atom aTEXT
 TEXT Atom for the clipboard. More...
 
const Atom aSTRING
 STRING Atom for the clipboard - uses XA_STRING. More...
 
const Atom aUTF8_STRING
 UTF8_STRING Atom for the clipboard. More...
 
const Atom aC_STRING
 C_STRING Atom for the clipboard. More...
 
const Atom aCOMPOUND_TEXT
 COMPOUND_TEXT Atom for the clipboard. More...
 
const Atom aTARGETS
 TARGETS Atom for the clipboard. More...
 
const Atom aMULTIPLE
 MULTIPLE Atom for the clipboard. More...
 
const Atom aTIMESTAMP
 TIMESTAMP Atom for the clipboard. More...
 
const Atom aNULL
 NULL Atom for the clipboard. More...
 

Detailed Description

Functions and variables associated with default parameters, and default definitions

Macro Definition Documentation

◆ GCAll

#define GCAll
Value:
(GCFunction | GCPlaneMask | GCForeground | GCBackground | GCLineWidth | \
GCLineStyle | GCCapStyle | GCJoinStyle | GCFillStyle | GCFillRule | \
GCTile | GCStipple | GCTileStipXOrigin | GCTileStipYOrigin | GCFont | \
GCSubwindowMode | GCGraphicsExposures | GCClipXOrigin | GCClipYOrigin | \
GCClipMask | GCDashOffset | GCDashList | GCArcMode)

A bit mask for ALL GC properties (used when copying a GC)

Definition at line 138 of file window_helper.h.

◆ WB_KEYBOARD_INPUT_MASK

#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 948 of file window_helper.h.

◆ WB_MOUSE_INPUT_MASK

#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 956 of file window_helper.h.

◆ WB_STANDARD_INPUT_MASK

#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 940 of file window_helper.h.

◆ WBGeomOverlapped

#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 1761 of file window_helper.h.

◆ WBGetWindowCopyGC2

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

makes a copy of the specified WBGC for the desired window

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

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

Header File: window_helper.h

Definition at line 1422 of file window_helper.h.

◆ WBPointInGeom

#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 1741 of file window_helper.h.

◆ WBPointInRect

#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 1732 of file window_helper.h.

◆ WBRectOverlapped

#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 1749 of file window_helper.h.

Typedef Documentation

◆ WB_ERROR_INFO

Structure definition for X11 error information.

typedef struct tagWB_ERROR_INFO
{
Display *pDisplay; // Display pointer passed into error handler function (NULL if no error)
const char *pFunc; // Name of the function as assigned by BEGIN_XCALL_DEBUG_WRAPPER
int iLine; // Line number of the function as assigned by BEGIN_XCALL_DEBUG_WRAPPER
unsigned long serial; // serial number from XErrorEvent
int error_code; // error code from XErrorEvent
int request_code; // request code from XErrorEvent
int minor_code; // minor code from XErrorEvent
XID resourceid; // resource ID (usually a Window) from XErrorEvent

◆ WB_EXTENT

internal wrapper struct for 'extent' definition

The extent structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use 'extents' can easily be ported into this environment.

typedef struct tagWBExtent
{
unsigned int width; // the 'width' value of the extent.
unsigned int height; // the 'height' value of the extent.

Definition at line 79 of file font_helper.h.

◆ WB_GEOM

internal wrapper struct for X11 'geometry' definition

The geometry structure is a wrapper for the X11 functions that specify the individual parameters for a geometry, such as XGetGeometry. Instead of passing 5 integers, you pass the pointer to a structure for the X11workbench API functions. This provides many advantages over the 'individual parameter' method as well as providing a structure for cacheing geometry information.

typedef struct tagWBGeom
{
int x, y;
unsigned int width, height, border;

Use of 'int' and 'unsigned int' for the various parameter is consistent with the various 'Geom' functions, which typically use 'int *' for returned parameters, as shown:

Status XGetGeometry(Display *display, Drawable d, Window *root_return,
int *x_return, int *y_return,
unsigned int *width_return, unsigned int *height_return,
unsigned int *border_return, unsigned int *depth_return);

◆ WB_POINT

internal wrapper struct for 'point' definition

The point structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use 'points' can easily be ported into this environment.

typedef struct tagWBPoint
{
int x; // the 'x' value of the point. can be negative.
int y; // the 'y' value of the point. can be negative.

Note that this is different from an XPoint structure, which is defined as

typedef struct
{
short x, y;
} XPoint;

◆ WB_RECT

internal wrapper struct for 'rectangle' definition

The rectangle structure has been defined primarily for convenience, so that specific coding methods that work well in GUI environments that use rectangles (instead of 'geometry') can easily be ported into this environment.

typedef struct tagWBRect
{
int left, top, right, bottom;

Note that this is different from an XRectangle structure, which is defined as

typedef struct
{
short x, y;
unsigned short width, height;
} XRectangle;

◆ WBAppEvent

WBAppEvent

event callback function type definition for application events

typedef int (* WBAppEvent)(XEvent *pEvent);
Parameters
pEventA pointer to the XEvent structure passed to the callback function
Returns
Event-specific value. Typically returns zero if the event was not processed, non-zero if further processing is not necessary

An event callback for the application should be declared according to this defined type

Header File: window_helper.h

Definition at line 204 of file window_helper.h.

◆ WBGC

internal wrapper struct for GC with local cache

The WBGC data type (and its associated structure) represent a locally cached 'Graphics Context' that can be efficiently used by the X11workbench Toolkit . It is similar to a GC structure in X11, and an HDC in windows, and exists for basically the same purpose.

Local cacheing of context information improves efficiency, especially for remote X11 clients.

typedef struct tagWBGC
{
Display *display; // the Display associated with the WBGC (NULL implies 'Default Display')
Drawable dw; // the Drawable for which this WBGC was created (None implies default Window)
GC gc; // the associated 'GC'
XGCValues values; // cached XGCValues for the GC
WB_FONT pFont; // cached default font
Region clip_rgn; // clipping region (or None to use clip_image)
XImage *clip_image; // cached XImage for the GC, for 'clip mask'
XImage *tile_image; // cached XImage for the GC, for 'tile'
XImage *stip_image; // cached XImage for the GC, for 'stipple'
} * WBGC;

It is generally safe to query the 'values' member in order to get cached information about the WBGC. You should not change them, however.

The XOrg documentation defines the XGCValues structure as follows:

typedef struct // XGCValues
{
int function; // logical operation
unsigned long plane_mask; // plane mask
unsigned long foreground; // foreground pixel
unsigned long background; // background pixel
int line_width; // line width (in pixels)
int line_style; // LineSolid, LineOnOffDash, LineDoubleDash
int cap_style; // CapNotLast, CapButt, CapRound, CapProjecting
int join_style; // JoinMiter, JoinRound, JoinBevel
int fill_style; // FillSolid, FillTiled, FillStippled FillOpaqueStippled
int fill_rule; // EvenOddRule, WindingRule
int arc_mode; // ArcChord, ArcPieSlice
Pixmap tile; // tile pixmap for tiling operations
Pixmap stipple; // stipple 1 plane pixmap for stippling
int ts_x_origin; // offset for tile or stipple operations
int ts_y_origin;
Font font; // default text font for text operations
int subwindow_mode; // ClipByChildren, IncludeInferiors
Bool graphics_exposures; // boolean, should exposures be generated
int clip_x_origin; // origin for clipping
int clip_y_origin;
Pixmap clip_mask; // bitmap clipping; other calls for rects
int dash_offset; // patterned/dashed line information
char dashes;
} XGCValues;

Additional information regarding the drawing of lines

The XOrg 'manual page' documentation for XGCValues also includes the following information (slightly edited):

The line-width is measured in pixels and either can be greater than or
equal to one (wide line) or can be the special value zero (thin line).
Wide lines are drawn centered on the path described by the graphics
request. Unless otherwise specified by the join-style or cap-style,
the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
width w is a rectangle with vertices at the following real coordinates:
[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
Here sn is the sine of the angle of the line, and cs is the cosine of
the angle of the line. A pixel is part of the line and so is drawn if
the center of the pixel is fully inside the bounding box (which is
viewed as having infinitely thin edges). If the center of the pixel is
exactly on the bounding box, it is part of the line if and only if the
interior is immediately to its right (x increasing direction). Pixels
with centers on a horizontal edge are a special case and are part of
the line if and only if the interior or the boundary is immediately
below (y increasing direction) and the interior or the boundary is
immediately to the right (x increasing direction).
Thin lines (zero line-width) are one-pixel-wide lines drawn using an
unspecified, device-dependent algorithm. There are only two con-
straints on this algorithm.
1. If a line is drawn unclipped from [x1,y1] to [x2,y2] and if
another line is drawn unclipped from [x1+dx,y1+dy] to
[x2+dx,y2+dy], a point [x,y] is touched by drawing the first line
if and only if the point [x+dx,y+dy] is touched by drawing the
second line.
2. The effective set of points comprising a line cannot be affected
by clipping. That is, a point is touched in a clipped line if and
only if the point lies inside the clipping region and the point
would be touched by the line when drawn unclipped.
A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
and join-style. It is recommended that this property be true for thin
lines, but this is not required. A line-width of zero may differ from
a line-width of one in which pixels are drawn. This permits the use of
line drawing hardware from many manufacturers, which may run many times
faster than the more precisely specified wide lines.
In general, drawing a thin line will be faster than drawing a wide line
of width one. However, because of their different drawing algorithms,
thin lines may not mix well aesthetically with wide lines. If it is
desirable to obtain precise and uniform results across all displays, a
client should always use a line-width of one rather than a line-width
of zero.

To be fair, the use of a line width of zero in the X11Workbench Toolkit is NOT recommended. The XImage code will assume zero implies width=1.

Also, an algorithm that allows the 'touching' of the same point many times is not impractical with an XImage; that is, the amount of code needed to check if a point were touched or will be touched is more computationally expensive than 'just touching it anyway'. As such, the XImage code may 'touch' a point multiple times, depending. For video hardware, especially accelerated video hardware, this could be a performance hit. But when using an XImage as a backing store for the window contents, it makes more sense to simply draw it anyway.

Additional information can be found in the aforementioned manual page.

◆ WBLocateWindowCallback

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 1294 of file window_helper.h.

◆ WBWinEvent

WBWinEvent

event callback function type for window events

typedef int (* WBWinEvent)(Window wID, XEvent *pEvent);
Parameters
wIDThe Window ID for the window receiving the event notification
pEventA pointer to the XEvent structure passed to the callback function
Returns
Event-specific value. Typically returns zero if the event was not processed, non-zero if further processing is not necessary

Event callbacks for windows should be declared according to this defined type

Header File: window_helper.h

Definition at line 186 of file window_helper.h.

Enumeration Type Documentation

◆ 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

Definition at line 1071 of file window_helper.h.

◆ WBScrollEventParam

Enumeration for aSCROLL_NOTIFY ClientMessage.

Enumeration of values used in scroll notification messages.

See also
WBScrollBarEvent()
Enumerator
WB_SCROLL_DEFAULT 

1st parameter (bar) - 'Default Bar', currently not implemented, probably won't be used

WB_SCROLL_HORIZONTAL 

1st parameter (bar) - The horizontal scroll bar for the control or window

WB_SCROLL_VERTICAL 

1st parameter (bar) - The vertical scroll bar for the control or window.

WB_SCROLL_KNOB 

2nd parameter (direction) - 'knob track' - pos in data.l[2]

WB_SCROLL_FORWARD 

2nd parameter (direction) - down, right

WB_SCROLL_BACKWARD 

2nd parameter (direction) - up, left

WB_SCROLL_PAGEFWD 

2nd parameter (direction) - pgdn, pgright

WB_SCROLL_PAGEBACK 

2nd parameter (direction) - pgup, pgleft

WB_SCROLL_FIRST 

2nd parameter (direction) - home, top

WB_SCROLL_LAST 

2nd parameter (direction) - bottom, end

WB_SCROLL_DBLCLICK 

2nd parameter (direction) - double-clicked item (no selection change info) (sent to list control's owner)

WB_SCROLL_ABSOLUTE 

2nd parameter (direction) - absolute scroll - pos in data.l[2]

WB_SCROLL_RELATIVE 

2nd parameter (direction) - relative scroll - rel pos in data.l[2]

WB_SCROLL_NA 

generic 'NA' or 'UNDEFINED' value

Definition at line 897 of file window_helper.h.

◆ WMPropertiesWindowType

Window type enumeration. Reserved for future implementation.

reserved for future implementation

Definition at line 996 of file window_helper.h.

◆ WMPropertiesWMProtocols

Window WMProtocols support enumeration.

Bit flags indicating support for known WM_PROTOCOLS window manager features

Enumerator
WMPropertiesWMProtocols_None 

the default

Definition at line 1049 of file window_helper.h.

Function Documentation

◆ CreateTimer()

int CreateTimer ( Display *  pDisplay,
Window  wID,
unsigned long  lInterval,
long  lID,
int  iPeriodic 
)

Creates a one-shot or periodic timer.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
lIntervalThe timer interval in microseconds
lIDThe unique timer identifier
iPeriodicNon-zero for a recurring timer, zero for a 'one-shot' timer.
Returns
Non-zero on error, zero on success.

Timers can either be periodic (recurring), or one-shot. Use this function to create them. A timer created by this function must be subsequently deleted via DeleteTimer()

Header File: window_helper.h

See also
aWB_TIMER

Definition at line 3347 of file window_helper.c.

◆ DeleteTimer()

void DeleteTimer ( Display *  pDisplay,
Window  wID,
long  lID 
)

Deletes an existing timer's resources.

Parameters
pDisplayThe display associated with the specified window
wIDThe window associated with the timer
lIDThe unique ID associated with the timer

Timers created via CreateTimer() must be subsequently deleted using this function by passing the same Display, Window, and Timer 'unique' ID that were used to create it.

Header File: window_helper.h

See also
aWB_TIMER

Definition at line 3444 of file window_helper.c.

◆ GetStartupDisplayName()

const char* GetStartupDisplayName ( void  )

returns character name of the display to be opened and passed to WBInit

Gets the display name associated with the current (default) display, or the display specified in the command line arguments passed to WBParseStandardArguments(). This name should be used in a call to XOpenDisplay(), and the resulting Display should then be passed to WBInit()

Header File: window_helper.h

Definition at line 1736 of file window_helper.c.

◆ GetStartupGeometry()

void GetStartupGeometry ( WB_GEOM pGeom)

returns the startup geometry based on command line parameters

Returns the desired geometry to be applied to the main window on startup. The value is based on a prior call to WBParseStandardArguments(), and should not be relied upon otherwise.

Header File: window_helper.h

Definition at line 1741 of file window_helper.c.

◆ GetStartupMinMax()

int GetStartupMinMax ( void  )

returns the min/max/normal window state for startup

Following a call to WBParseStandardArguments(), this function will return the desired startup window state, either minimized (< 0), maximized (> 0), or normal (= 0).

Header File: window_helper.h

Definition at line 1749 of file window_helper.c.

◆ WBAddMenuWindow()

void WBAddMenuWindow ( Window  wID,
Window  wIDMenu 
)

Add a MENU WINDOW to a (frame) window.

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

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.

◆ WBAllowErrorOutput()

static __inline__ void WBAllowErrorOutput ( void  )
static

Restore X11 XErrorEvent output to stderr.

Call this function to decrement the error output supression counter. Error output will be restored whenever the supression counter returns to zero. Each call to the WBSupressErrorOutput() function should be balanced with a call to this function.

Header File: window_helper.h

Definition at line 3706 of file window_helper.h.

◆ 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.

◆ WBAppDispatch()

int WBAppDispatch ( XEvent *  pEvent)

Dispatches an application XEvent. May be called directly.

Parameters
pEventA pointer to an XEvent structure to process

Application events have a window ID of None, and are dispatched to the registered Application callback. In the absence of a callback, default processing is performed.

Header File: window_helper.h

Definition at line 4558 of file window_helper.c.

◆ WBAssignWindowImage()

int WBAssignWindowImage ( Display *  pDisplay,
Window  wID,
XImage *  pImage 
)

Assign an XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
pImageThe XImage to assign to the window's internal information. On success, after the function call, this pointer is 'owned' by the window and should not be destroyed.
Returns
A value of zero on success. A non-zero value indicates an error.

Calling this function assigns a new cached XImage as 'backing store' for the window. It must be large enough to include the entire window's display area. On success, the assigned image will replace any existing image. Assigning a value of 'NULL' deletes any existing cached image. If an image is too small, the function call will fail, and ownership of the XImage remains as-is. Your call to this function needs to check for errors so that any resources can be properly cleaned up, as the XImage will not be owned nor destroyed.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8166 of file window_helper.c.

◆ WBBeginPaint()

WBGC WBBeginPaint ( Window  wID,
XExposeEvent *  pEvent,
WB_GEOM pgRet 
)

'Paint' helper, creates a WBGC for use in updating the window in an Expose event handler

Parameters
wIDWindow ID associated with the Expose event
pEventPointer to the Expose event that's being processed
pgRetThe returned bounding geometry for the invalid region being 'painted'
Returns
A WBGC (graphics context) to be used in handling the Expose event

When processing Expose events, you should call WBBeginPaint to obtain the WBGC needed for all of the operations needed to update (paint) the window.
This function collects all of the relevant invalid regions associated with the window that fall within the 'Expose' event area, and calculates a bounding WB_GEOM rectangle for it. It also applies the invalid region as a 'clipping' region for the returned WBGC. When you call WBEndPaint(), the entire clipping region will be marked 'valid' automatically, so it is important for your 'paint' function to update the entire WB_GEOM rectangle identified by pgRet. This includes erasing the background as well as drawing whatever is in the foreground.

Header File: window_helper.h

Definition at line 7732 of file window_helper.c.

◆ WBBeginPaintGeom()

WBGC WBBeginPaintGeom ( Window  wID,
WB_GEOM pgBounds 
)

'Paint' helper, creates a WBGC for use in updating the window for a specified rectangular area

Parameters
wIDWindow ID associated with the Expose event
pgBoundsOn entry, the bounding WB_GEOM for which to get a graphics context. On return, the bounding WB_GEOM for the invalid region being 'painted'
Returns
A WBGC (graphics context) to be used in painting the specific rectangular region

When processing Expose events, you should call WBBeginPaint() to obtain the WBGC needed for all of the operations needed to update (paint) the window.
This particular function is more suited to updating a specific area outside of a normal Expose callback handler. As an example, a frame window would use this to update the tab area or the status bar area, prior to calling the user callback function. That way, only the desired region will be 'validated' on call to WBEndPaint(), and not the entire window client area.

Header File: window_helper.h

Definition at line 7780 of file window_helper.c.

◆ WBBeginWaitCursor()

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

◆ WBChangeGC()

int WBChangeGC ( WBGC  hGC,
unsigned long  valuemask,
const XGCValues *  values 
)

Change a WBGC, a wrapper for XChangeGC()

Parameters
hGCThe WBGC which is to be modified
valuemaskA bitwise mask of values to assign to the new WBGC from 'values'
valuesA pointer to an XGCValues structure describing values to be assigned (may be NULL)
Returns
An integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions (such as this one).

See also
WBGC

Header File: window_helper.h

Definition at line 676 of file graphical_api.c.

◆ WBChangeWMPropertiesWindowType()

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

◆ WBCheckGetEvent()

int WBCheckGetEvent ( Display *  pDisplay,
XEvent *  pEvent 
)

Main message loop, high level API to check for and retrieve the next event.

Parameters
pDisplayA pointer to the Display to query events on
pEventA pointer to an XEvent structure to receive the event data
Returns
A non-zero value if there is an event to be processed, otherwise zero

Implementation of the X11workbench Toolkit API is centered around the API's event loop processing. The main application should implement its message loop by repeatedly calling WBCheckGetEvent() or WBNextEvent() and passing any retrieved event to WBDispatch(). Internally, WBCheckGetEvent() calls the X___CheckEvent functions correctly, dispatches Expose events for asynchronous processing, translates keyboard and pointer events, and handles internally queued events (such as timers and 'posted' events).

The function returns a non-zero value if there is an event is to be processed.

To correctly implement a message loop, your code should be similar to the following:

XEvent event;
while ( !bQuitFlag )
{
if( !WBCheckGetEvent(pX11Display, &event) )
{
// as needed, perform an iteration of background processing here
// With nothing else to do, SLEEP if there is no event in the message queue
// and no background processing to be performed.
// (alternately, you could use WBWaitForEvent() if you do not need periodic
// wake-up for background processing)
WBDelay(100); // 100 microsecs - 0.1 millisecond
continue;
}
WBDispatch(&event);
}

NOTE: If you do not want to do any background processing, consider using WBWaitForEvent() instead of WBDelay()

To only retrieve 'internally queued' events, see WBNextEvent()

Header File: window_helper.h

Definition at line 3725 of file window_helper.c.

◆ WBClearWindow()

void WBClearWindow ( Window  wID,
WBGC  gc 
)

'Paint' helper, erases background by painting the background color within the clipping region

Parameters
wIDWindow ID associated with the Expose event
gcThe WBGC (graphics context) returned by WBBeginPaint().

Call this function, following a call to WBBeginPaint(), if you want to erase the background of the window. Call this in lieu of XClearWindow() or XClearArea()

Header File: window_helper.h

Definition at line 7971 of file window_helper.c.

◆ WBCopyDrawableGC()

WBGC WBCopyDrawableGC ( Display *  pDisplay,
Drawable  dw,
WBGC  hGCOrig 
)

makes a copy of the specified WBGC 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 WBGC (NULL/None uses the 'default' window)
hGCOrigThe source 'WBGC'
Returns
A copy of the WBGC for the specified 'Drawable'

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

Header File: window_helper.h

Definition at line 1162 of file graphical_api.c.

◆ WBCopyGC()

WBGC WBCopyGC ( WBGC  hGCOrig)

makes a copy of a WBGC, a more sensible wrapper for XCopyGC()

Parameters
hGCOrigThe WBGC which is to be copied
Returns
A copy of the original WBGC

Header File: window_helper.h

Definition at line 905 of file graphical_api.c.

◆ WBCopyGC2()

int WBCopyGC2 ( WBGC  hGCOrig,
unsigned long  valuemask,
WBGC  hGCDest 
)

makes a copy of a WBGC, a wrapper for XCopyGC()

Parameters
hGCOrigThe WBGC which is to be copied
unsignedlong valuemask A bitwise mask of values to assign to the new WBGC from the original
hGCDestThe destination WBGC to copy to
Returns
An integer indicating success or fail

Header File: window_helper.h

Definition at line 958 of file graphical_api.c.

◆ WBCopyIntoWindowImage()

int WBCopyIntoWindowImage ( Display *  pDisplay,
Window  wID,
XImage *  pSrcImage,
int  xSrc,
int  ySrc,
int  width,
int  height,
int  xOffs,
int  yOffs 
)

Copy an XImage into the cached XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
pImageThe XImage to copy into the cached XImage for the window. Must be a pointer to a valid XImage. The specified XImage will not be changed, owned, nor destroyed.
xSrcThe 'x' offset within the source XImage to begin copying from
ySrcThe 'y' offset within the source XImage to begin copying from
widthThe width within the source XImage to copy from. a value of '-1' copies as much as possible to the destination image
heightThe height within the source XImage to copy from. a value of '-1' copies as much as possible to the destination image
xDstThe 'x' offset within the window's cached XImage to begin copying to
yDstThe 'y' offset within the window's cached XImage to begin copying to
Returns
A value of zero on success. A non-zero value indicates an error.

Calling this function copies the specified XImage's data into the cached image of the window. If the window does not already have a cached image, one will be created that containing the window's visible display data. On success, the assigned image will replace that portion of the existing image as specified by the source offset, source size, and destination offset. Images that are too large to fit into the destination will be limited within the appropriate dimensions, based on the destination image size.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8181 of file window_helper.c.

◆ WBCopyRegion()

Region WBCopyRegion ( Region  rgnSource)

Simple utility to copy a region.

Parameters
rgnSourceA source region to copy
Returns
A region that is a union of the source region with itself; i.e. a copy

This function makes a simple copy of a region by doing a union with itself, returning the result. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7634 of file window_helper.c.

◆ WBCreateGC()

WBGC WBCreateGC ( Display *  pDisplay,
Drawable  dw,
unsigned long  valuemask,
const XGCValues *  values 
)

Creates a WBGC, wrapper for XCreateGC()

Parameters
pDisplayA pointer to the Display, or NULL to use the default Display
Drawabledw The Drawable for which to create the WBGC
valuemaskA bitwise mask of values to assign to the new WBGC from 'values'
valuesA pointer to an XGCValues structure describing values to be assigned (may be NULL)
Returns
A copy of the new WBGC

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 565 of file graphical_api.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
pDisplayA pointer to the display (or NULL for the default display)
wIDParentThe parent window, or 'None'
pProcA pointer to the event handler proc
szClassThe name of the window's class (mostly for debugging in X11; for WIN32 this is important for other reasons)
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, plus additional flags specific to the X11Workbench Toolkit (see below)
pXSWAA 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.

◆ WBCreateWindowDefaultGC()

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

creates a default WBGC 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 5726 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.

◆ WBDefaultColormap()

static __inline__ Colormap WBDefaultColormap ( Display *  pDisplay)
static

returns the default colormap for the default screen of the specified display

Convenience function that returns the default colormap for the default screen of the specified display. Helps to clean up the initialization code and make it more 'modular'.

Header File: window_helper.h

Definition at line 715 of file window_helper.h.

◆ WBDefaultStandardColormap()

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 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.

◆ WBDispatch()

void WBDispatch ( XEvent *  pEvent)

Generic Event Dispatcher, using message type to dispatch.

Parameters
pEventA pointer to an XEvent structure to process

Call this function to generically dispatch an XEvent. The application will need to check for a 'quit' state independently. See WBWindowDispatch(), WBAppDispatch()

Header File: window_helper.h

Definition at line 4658 of file window_helper.c.

◆ WBDrawArc()

int WBDrawArc ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height,
int  angle1,
int  angle2 
)

Wrapper for XDrawArc()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the arc's elipse
heightThe height of the arc's elipse
angle1The starting angle of the arc
angle2The ending angle of the arc
Returns
An integer indicating success or failure

This function draws an arc, similar to XDrawArc(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 345 of file graphical_api.c.

◆ WBDrawLine()

int WBDrawLine ( Display *  display,
Drawable  d,
WBGC  gc,
int  x1,
int  y1,
int  x2,
int  y2 
)

Wrapper for XDrawLines()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
x1The origin 'x' coordinate of the line
y1The origin 'y' coordinate of the line
x2The final 'x' coordinate of the line
y2The final 'y' coordinate of the line
Returns
An integer indicating success or failure

This function draws a line, similar to XDrawLines(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 197 of file graphical_api.c.

◆ WBDrawLines()

int WBDrawLines ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  mode 
)

Wrapper for XDrawLine()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the line vertices
npointsThe number of entries in the 'points' array
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XDrawLines().
Returns
An integer indicating success or failure

This function draws one or more lines, similar to XDrawLines(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 234 of file graphical_api.c.

◆ WBDrawPoint()

int WBDrawPoint ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y 
)

Wrapper for XDrawPoint()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin 'x' coordinate of the line
yThe origin 'y' coordinate of the line
Returns
An integer indicating success or failure

This function draws a point, similar to XDrawPoint(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 124 of file graphical_api.c.

◆ WBDrawPoints()

int WBDrawPoints ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  mode 
)

Wrapper for XDrawPoints()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the line vertices
npointsThe number of entries in the 'points' array
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XDrawLines().
Returns
An integer indicating success or failure

This function draws one or more points, similar to XDrawPoints(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 160 of file graphical_api.c.

◆ WBDrawRectangle()

int WBDrawRectangle ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height 
)

Wrapper for XDrawRectangle()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the rectangle
heightThe height of the rectangle
Returns
An integer indicating success or failure

This function draws a rectangle, similar to XDrawRectangle(), on the specified Drawable, with the specified graphics context indicating foreground and background colors.

Header File: window_helper.h

Definition at line 271 of file graphical_api.c.

◆ WBDrawString()

int WBDrawString ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
const char *  string,
int  length 
)

wrapper for XDrawString()

Parameters
pDisplayA pointer to the display to use for rendering the text
dThe 'Drawable' object upon which to render the text
gcThe graphics context 'WBGC' for rendering the text
xThe 'x' coordinate for the text alignment (left)
yThe 'y' coordinate for the text alignment (bottom)
stringA const pointer to a UTF-8 or multi-byte string
lengthThe BYTE LENGTH of the UTF-8 or mult-byte string (not character length)
Returns
An integer indicating success or failure

Use this function in lieu of XDrawString() to draw text in a platform-independent manner, using the specified font, upon the specified 'Drawable'. This function is the equivalent of the X11 library's XDrawString(). Internally, it calls DTDrawString().

Header File: draw_text.h

Definition at line 458 of file graphical_api.c.

◆ WBEndModal()

void WBEndModal ( Window  wID,
int  iReturn 
)

End a modal window with a specific return value.

Parameters
wIDWindow ID of the window that must end its modal loop
iReturnThe 'return' value from the modal loop - see WBShowModal()

Call this function from within a modal window's event process to close the window and exit from WBShowModal with the specified value in 'iReturn'

Header File: window_helper.h

Definition at line 2165 of file window_helper.c.

◆ WBEndPaint()

void WBEndPaint ( Window  wID,
WBGC  gc 
)

'Paint' helper, frees resources and marks the update region 'valid'

Parameters
wIDWindow ID associated with the Expose event and passed to WBBeginPaint()
gcThe WBGC (graphics context) returned by WBBeginPaint()

Call this function, following a call to WBBeginPaint(), once the invalid area of the window has been properly rendered. It will free resources and mark the invalid (update) region as 'valid'.

Additionally, if a cached XImage is being used for this window, the display will be updated using the cached image during the call to this function.

Header File: window_helper.h

See also
WBBeginPaint() WBAssignWindowImage()

Definition at line 8033 of file window_helper.c.

◆ WBEndWaitCursor()

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

◆ WBErrorCheck()

int WBErrorCheck ( void  )

Check to see whether or not an X11 error was detected.

Returns
A non-zero value if an error was stored in the internal WB_ERROR_INFO structure, else zero

Call this function to check to see if an XErrorEvent has been processed and stored in the internal WB_ERROR_INFO structure. It is necessary to FIRST call WBErrorClear() before any operation that might result in an error that can THEN be checked for using this function.

Header File: window_helper.h

Definition at line 9594 of file window_helper.c.

◆ WBErrorCheckRetry()

int WBErrorCheckRetry ( void  )

Check to see whether or not an X11 error was detected AND can be re-tried.

Returns
A non-zero value if a retryable error was stored in the internal WB_ERROR_INFO structure, else zero

Call this function to check to see if an XErrorEvent has been processed and stored in the internal WB_ERROR_INFO structure, and if a retry is possible based on the type and condition of the error. It is necessary to FIRST call WBErrorClear() before any operation that might result in an error that can THEN be checked for retryability using this function.

Header File: window_helper.h

Definition at line 9599 of file window_helper.c.

◆ WBErrorClear()

void WBErrorClear ( void  )

Clear the 'last error' information obtained via WBGetLastError()

Header File: window_helper.h

Definition at line 9589 of file window_helper.c.

◆ WBEventName()

const char* WBEventName ( int  iEventID)

debug function to return the name of an X11 event

Parameters
iEventIDAn event type identifier
Returns
A const pointer to an ASCII 0-byte terminated character string representing the event ID, or NULL

Intended primarily for debug messages, it returns a pointer to an ASCII string containing the name of the event, based on its event ID. The ID of the event is the value of 'type' within the XEvent structure.

Header File: window_helper.h

Definition at line 8976 of file window_helper.c.

◆ WBExit()

void WBExit ( void  )

deletes any remaining global objects, frees the Display pointer, and terminates event processing

This function deletes any remaining global objects, frees the Display pointer, and terminates event processing, freeing up any remaining resources for the entire toolkit. You should call this function in your application right before it terminates.

Header File: window_helper.h

Definition at line 1639 of file window_helper.c.

◆ WBExitClipboardSystem()

void WBExitClipboardSystem ( Display *  pDisplay)

Shut down the clipboard sub-system.

Shuts down the clipboard sub-system. Called internally by WBExit()

Header File: window_helper.h

Definition at line 273 of file clipboard_helper.c.

◆ WBFillArc()

int WBFillArc ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height,
int  angle1,
int  angle2 
)

Wrapper for XFillArc()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the arc's elipse
heightThe height of the arc's elipse
angle1The starting angle of the arc
angle2The ending angle of the arc
Returns
An integer indicating success or failure

This function draws a filled arc, similar to XFillArc(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 383 of file graphical_api.c.

◆ WBFillPolygon()

int WBFillPolygon ( Display *  display,
Drawable  d,
WBGC  gc,
XPoint *  points,
int  npoints,
int  shape,
int  mode 
)

Wrapper for XFillPolygon()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
pointsA pointer to an array of XPoint structures describing the polygon line vertices
npointsThe number of entries in the 'points' array
shapeA constant indicating the general shape, either Convex, Nonconvex, or Complex - see XFillPolygon()
modeA constant indicating the coordinate mode, either CoordModeOrigin or CoordModePrevious - see XFillPolygon().
Returns
An integer indicating success or failure

This function draws a filled polygon, similar to XFillPolygon(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 421 of file graphical_api.c.

◆ WBFillRectangle()

int WBFillRectangle ( Display *  display,
Drawable  d,
WBGC  gc,
int  x,
int  y,
unsigned int  width,
unsigned int  height 
)

Wrapper for XFillRectangle()

Parameters
pDisplayThe display associated with the specified window
dThe Drawable (or window) I'm painting. If a window, this may use the XImage cache
gcThe Graphics context of the operation
xThe origin x of the operation
yThe origin y of the operation
widthThe width of the rectangle
heightThe height of the rectangle
Returns
An integer indicating success or failure

This function draws a filled rectangle, similar to XFillRectangle(), on the specified Drawable, with the specified graphics context indicating foreground, fill, and background colors.

Header File: window_helper.h

Definition at line 308 of file graphical_api.c.

◆ WBFreeGC()

void WBFreeGC ( WBGC  hGC)

Free resources for a WBGC, wrapper for XFreeGC()

Parameters
hGCThe WBGC which is to be freed

Header File: window_helper.h

Definition at line 1218 of file graphical_api.c.

◆ WBGContextFromGC()

GContext WBGContextFromGC ( WBGC  hGC)

Free resources for a WBGC, wrapper for XGContextFromGC()

Parameters
hGCThe WBGC which is to be freed
Returns
a GContext indicating the saved graphics context associated with the WBGC

NOTE: this only preserves those things that XGContextFromGC will preserve; some things are only cached by the WBGC internally

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1291 of file graphical_api.c.

◆ WBGeomToRegion()

Region WBGeomToRegion ( const WB_GEOM pGeom)

'Paint' helper, converts a WB_GEOM structure to a Region.

Parameters
pGeomA const pointer to the WB_GEOM structure
Returns
A region that encompasses the area of the WB_GEOM structure, or None on error

This function converts a WB_GEOM structure to a Region. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7697 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.

◆ WBGetBackground()

static __inline__ unsigned long WBGetBackground ( WBGC  hGC)
static

Get the (cached) background color for a WBGC.

Parameters
hGCThe WBGC to query the color of
Returns
the backgound color associated with the WBGC

Header File: window_helper.h

Definition at line 3139 of file window_helper.h.

◆ WBGetClientRect()

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

◆ WBGetClipboardData()

void* WBGetClipboardData ( Display *  pDisplay,
Atom *  paType,
int *  piFormat,
unsigned long *  pnData 
)

Get clipboard data of requested type.

Parameters
pDisplaythe Display pointer for the selection (NULL for default)
paTypePointer to an atom indicating the requested data type ('None' for ANY), and returning the actual data type
piFormatpointer to the returned format (0, 8, 16, or 32)
pnDatathe size of the returned data (number of items, based on *piFormat)
Returns
a pointer to the actual data (must use 'WBFree()' to de-allocate the resource)

This function will obtain the clipboard data associated with the specified data type, or whichever data it finds first if 'None' is specified as 'paType'. Some substitutions may occur, such as 'XA_TEXT' vs 'UTF8' (for example), if data in the requested format is not available. The returned value is a pointer to the actual data of size '*pnData' 'items' (which have a bit length as specified by '*piFormat'). You must call 'WBFree()' to release the resource once you are done with it.

Header File: window_helper.h

Definition at line 1842 of file clipboard_helper.c.

◆ WBGetDefaultDisplay()

static __inline__ Display* WBGetDefaultDisplay ( void  )
static

Returns the default Display.

The default display is usually the ONLY display in use by the application. This function returns that Display pointer, which can be used in any case where the current display is not known

See also
WBGetWindowDisplay()

Header File: window_helper.h

Definition at line 786 of file window_helper.h.

◆ WBGetDefaultFont()

WB_FONTC WBGetDefaultFont ( void  )

Returns a pointer to the default font WB_FONT for the default display. This is a shared resource; do NOT free it nor alter it!

Returns
A pointer to a WB_FONT object (const), or 'NULL' on error. This is a shared resource; do NOT free it nor alter it!

The default WB_FONT is allocated at startup. This function returns its value (not a copy), which can then be used in a case where the 'in use' WB_FONT is not known, or when an overriding font has not been specified.

Header File: window_helper.h

Definition at line 1376 of file window_helper.c.

◆ WBGetForeground()

static __inline__ unsigned long WBGetForeground ( WBGC  hGC)
static

Get the (cached) foreground color for a WBGC.

Parameters
hGCThe WBGC to query the color of
Returns
the foreground color associated with the WBGC

Header File: window_helper.h

Definition at line 3108 of file window_helper.h.

◆ WBGetGCBGColor()

unsigned long WBGetGCBGColor ( WBGC  gc)

returns the currently assigned background color for a WBGC

Parameters
gcThe WBGC 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

See also
WBGetWindowBGColor()

Definition at line 5886 of file window_helper.c.

◆ WBGetGCFGColor()

unsigned long WBGetGCFGColor ( WBGC  gc)

returns the currently assigned foreground color for a WBGC

Parameters
gcThe WBGC 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

See also
WBGetWindowFGColor()

Definition at line 5857 of file window_helper.c.

◆ WBGetGCFont()

WB_FONT WBGetGCFont ( Display *  pDisplay,
WBGC  gc 
)

return a copy of the WB_FONT object that was assigned to a WBGC

Parameters
pDisplayA pointer to the Display
gcThe WBGC to be queried
Returns
A pointer to a WB_FONT object, or NULL on error. non-NULL values must be freed via WBFreeFont()

Call this function to determine the font that has been assigned to a WBGC, and make a copy of it for subsequent use. If there has been NO font assigned, the system default font information will be returned.

The return value is always a new pointer to a WB_FONT, or NULL on error. The caller must free non-NULL return values via WBFreeFont().

Header File: window_helper.h

See also
WBQueryGCFont()

Definition at line 1314 of file graphical_api.c.

◆ WBGetGCValues()

Status WBGetGCValues ( WBGC  hGC,
unsigned long  valuemask,
XGCValues *  values 
)

Change a WBGC, a wrapper for XGetGCValues()

Parameters
hGCThe WBGC which is to be queried
valuemaskA bitwise mask of values to assign to the new WBGC from 'values'
valuesA pointer to an XGCValues structure describing values to be assigned (may be NULL)
Returns
A Status indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions. This function will conveniently make a copy of that internal structure and write it to the pointer specified by 'values'.

See also
WBGC, WBFreeGC()

Header File: window_helper.h

Definition at line 833 of file graphical_api.c.

◆ WBGetHiddenHelperWindow()

Window WBGetHiddenHelperWindow ( void  )

Returns a special 'hidden' window used for information purposes.

This function returns a special window that was created for information purposes. If you need a window for query purposes that belongs to the default display, you can use the one returned by this function.

Header File: window_helper.h

Definition at line 1417 of file window_helper.c.

◆ WBGetInvalidRegion()

Region WBGetInvalidRegion ( Window  wID)

'Paint' helper, returns a copy of the invalid region for a window

Parameters
wIDWindow ID
Returns
Copy of 'invalid region' for this window, or None.

This function returns a copy of the current invalid region for the window, or None if the window is up-to-date. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7563 of file window_helper.c.

◆ WBGetLastError()

const WB_ERROR_INFO* WBGetLastError ( void  )

Obtain a const pointer to the internal WB_ERROR_INFO structure.

Returns
A const pointer to the internal WB_ERROR_INFO structure

Call this function to obtain details about the last error from the XErrorEvent passed to the error handler. If there has been no error event, the 'pDisplay' member will always be NULL. You should always call WBErrorClear() to clear out this structure before performing an operation that might result in an XErrorEvent.

Header File: window_helper.h

Definition at line 9611 of file window_helper.c.

◆ WBGetLastEventTime()

Time WBGetLastEventTime ( void  )

Main message loop, high level API to check for and retrieve the next event.

Returns
The 'Time' value for the last event that had a server timestamp

In some cases it's necessary to know an approximate value of the X server's timestamp. The message loop will capture the timestamp value whenever it can. Use this function to return the best known server time value for the default Display.

Header File: window_helper.h

Definition at line 3718 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
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 7154 of file window_helper.c.

◆ WBGetPaintRegion()

Region WBGetPaintRegion ( Window  wID)

'Paint' helper, returns a copy of the current 'paint' region for the window

Parameters
wIDWindow ID
Returns
Copy of 'paint region' for this window, or None. not valid outside of BeginPaint() / EndPaint()

This function returns a copy of the current paint region for the window, or None if the window is up-to-date. The caller must destroy the returned value using XDestroyRegion()
This function is not valid outside of WBBeginPaint() / WBEndPaint() processing, typically part of an 'Expose' event handler.

Header File: window_helper.h

Definition at line 7605 of file window_helper.c.

◆ WBGetParentWindow()

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

◆ WBGetSelectionData()

void* WBGetSelectionData ( Display *  pDisplay,
Atom  aSelection,
Atom *  paType,
int *  piFormat,
unsigned long *  pnData 
)

Get clipboard data of requested type.

Parameters
pDisplaythe Display pointer for the selection (NULL for default)
aSelectionan Atom for the 'selection' data to acquire (usually 'CLIPBOARD' or XA_PRIMARY)
paTypePointer to an atom indicating the requested data type ('None' for ANY), and returning the actual data type
piFormatpointer to the returned format (0, 8, 16, or 32)
pnDatathe size of the returned data (number of items, based on *piFormat)
Returns
a pointer to the actual data (must use 'WBFree()' to de-allocate the resource)

This function will obtain the selection data associated with the target and specified data type, or whichever data it finds first if 'None' is specified as 'paType'. Some substitutions may occur, such as 'XA_TEXT' vs 'UTF8' (for example), if data in the requested format is not available. The returned value is a pointer to the actual data of size '*pnData' 'items' (which have a bit length as specified by '*piFormat'). You must call 'WBFree()' to release the resource once you are done with it.

Header File: window_helper.h

Definition at line 1856 of file clipboard_helper.c.

◆ WBGetWindowBGColor()

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

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

◆ WBGetWindowCopyGC()

WBGC WBGetWindowCopyGC ( Window  wID)

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

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

Header File: window_helper.h

Definition at line 5817 of file window_helper.c.

◆ WBGetWindowData()

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

◆ WBGetWindowDefaultCursor()

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

◆ WBGetWindowDefaultGC()

WBGC WBGetWindowDefaultGC ( Window  wID)

Returns the default WBGC currently assigned to the window (not a copy)

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

Each window that is mapped within the API will have a 'default WBGC' associated with it. This WBGC should not be modified unless you want the changes to remain for the next time a WBGC is required. A preferred method is to re-assign a new default WBGC with the new settings, or create a copy of the default WBGC 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 WBGC is a modified version of the default WBGC.

Header File: window_helper.h

Definition at line 5805 of file window_helper.c.

◆ WBGetWindowDisplay()

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

◆ WBGetWindowFGColor()

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

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
wIDThe 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.

◆ WBGetWindowGeom()

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

◆ WBGetWindowGeom0()

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

◆ WBGetWindowGeom2()

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

◆ WBGetWindowImage()

XImage* WBGetWindowImage ( Display *  pDisplay,
Window  wID 
)

Obtain an XImage for the entire window.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)
Returns
A pointer to an XImage, or NULL on error

Returns the cached XImage for the window. If none exists, one will be created and stored within the internal stuctures for the window. Actual changes to the image will not be reflected on the display until you call WBUpdateWindowWithImage().

NOTE: You should not destroy nor cache the XImage pointer returned by this function. It is owned by the window's internal structures.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8112 of file window_helper.c.

◆ WBGetWindowRect()

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

◆ WBGetWMPropertiesWindowType()

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

◆ WBInit()

Display* WBInit ( const char *  szDisplayName)

initializes default objects for the specified Display (required)

Parameters
szDisplayNameA null-byte terminated ASCII string containing the DISPLAY name, or NULL
NULL values causes the display to initialize using GetStartupDisplayName()
Returns
A pointer to the Display, or NULL on error

Call this function before any other to create a display and initialize the X11 WorkBench Toolkit. Alternately you can create the display yourself and call WBInitDisplay(). WBExit() will free the assigned Display pointer for you by calling XCloseDisplay().
The returned pointer can be retrieved at any time by calling 'WBGetDefaultDisplay()'.
Header File: window_helper.h

Definition at line 1042 of file window_helper.c.

◆ WBInitClipboardSystem()

int WBInitClipboardSystem ( Display *  pDisplay,
const char *  szDisplayName 
)

initializes clipboard sub-system

Parameters
pDisplayThe 'Display' associated with this clipboard (reserved, must match 'WBInitDisplay' call or be NULL)
szDisplayNameA null-byte terminated ASCII string containing the DISPLAY name, or NULL
NULL values causes the display to initialize using GetStartupDisplayName()
Returns
Zero value on success, non-zero on error.

Call this function to initialize the 'Clipboard' sub-system, after initializing the 'Display'. This function is automatically called internally by WBInitDisplay() so there should be no need to invoke it directly.
It will spawn a new thread that runs in the background to process clipboard-related messages, internally using a separate Display object, so that the main thread is not impacted (nor deadlocked) by clipboard handling.
The 'pDisplay' parameter is reserved for future use, for when multiple displays are supported.
If a thread uses the same display name that was passed to 'WBInit' then it refers to the same Display as the main thread, and you will not need to re-initialize the clipboard for that Display.

Header File: window_helper.h

Definition at line 144 of file clipboard_helper.c.

◆ WBInitDisplay()

int WBInitDisplay ( Display *  pDisplay)

initializes default objects for the specified Display

Parameters
pDisplayA pointer to an open Display object, to become the default display for the X11 WorkBench Toolkit.
Returns
Zero value on success, non-zero on error.

Call this function before any other to assign the default Display pointer and initialize the X11 WorkBench Toolkit. A number of internal objects are initialized by this function. On error the function returns a non-zero value.
The preferred method for initialization is to use WBInit() with a display name (or NULL). However, in some cases you may wish to open the display yourself, and pass the pointer to this function instead. Typical reasons for that may be security-related, use of firewalls, proxies, and any other kind of possible and/or unusual method for opening a display.

Header File: window_helper.h

Definition at line 1160 of file window_helper.c.

◆ WBInitSizeHints()

void WBInitSizeHints ( XSizeHints *  pSH,
Display *  pDisplay,
int  iMinHeight,
int  iMinWidth 
)

initializes the XSizeHints structure with standard attributes

Parameters
pSHPointer to the XSizeHints structure
pDisplayPointer to the Display (NULL for default)
iMinHeightMinimum height of the window
iMinWidthMinimum width of the window

Convenience function that assigns the default window size on application startup. Takes into consideration the screen dimensions and min width/height if the user did not specify window geometry on startup. See the X11 API Reference, sections 9.1.6 and 10.3 for more information on XSizeHints

Header File: window_helper.h

Definition at line 1804 of file window_helper.c.

◆ WBInitWindowAttributes()

void WBInitWindowAttributes ( XSetWindowAttributes *  pXSWA,
unsigned long  lBorderPixel,
unsigned long  lBackgroundPixel,
Colormap  clrMap,
int  iBitGravity 
)

initializes the XSetWIndowAttributes structure with minimal attributes

Parameters
pXSWAA pointer to the (un-initialized) XSetWindowAttributes structure
lBorderPixelThe color value for the border pixel
lBackgroundPixelThe color value for the background pixel
clrMapThe colormap, typically the value returned by WBDefaultColormap()
iBitGravityThe 'bit gravity' of the window. Typical value is 'CenterGravity'

Convenience function to assign the minimal window attributes to the XSetWindowAttributes structure. Helps to clean up the initialization code and make it more 'modular'. For more information on window attributes, see the X11 API Documentation, section 3.3 .

You should pass 'iFlags' with 'CWBorderPixel | CWBackPixel | CWColormap | CWBitGravity' to WBCreateWindow(), or use WBCreateWindow_flagsDefault, whenever you use this function to initialize the XSetWindowAttributes structure.

Header File: window_helper.h

Definition at line 1793 of file window_helper.c.

◆ WBInvalidateGeom()

void WBInvalidateGeom ( Window  wID,
const WB_GEOM pGeom,
int  bPaintFlag 
)

'Paint' helper, invalidates a geometry for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pGeomA pointer to a WB_GEOM structure specifying the invalid area, or NULL (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a geometry to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this geometry as part of its update region.

Header File: window_helper.h

Definition at line 7324 of file window_helper.c.

◆ WBInvalidateRect()

static __inline__ void WBInvalidateRect ( Window  wID,
const WB_RECT pRCT,
int  bPaintFlag 
)
static

'Paint' helper, invalidates a WB_RECT for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pRCTA const pointer to a WB_RECT structure specifying the invalid area, or NULL (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a rectangle to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this geometry as part of its update region.

Header File: window_helper.h

Definition at line 2779 of file window_helper.h.

◆ WBInvalidateRegion()

void WBInvalidateRegion ( Window  wID,
Region  rgn,
int  bPaintFlag 
)

'Paint' helper, invalidates a region for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
rgnA Region identifier specifying the invalid area, or None (implying the entire window)
bPaintFlagA non-zero value to force re-paint by generating an Expose message. Zero simply invalidates the specified area

In conjunction with WBProcessExposeEvent it adds a region to the 'invalid' region associated with the window, and optionally generates an asynchronous expose event if 'bPaintFlag' is non-zero.
For a zero 'bPaintFlag' the next Expose event will include this region as part of its update region.

Header File: window_helper.h

Definition at line 7399 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
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 7014 of file window_helper.c.

◆ WBIsMapped()

int WBIsMapped ( Display *  pDisplay,
Window  wID 
)

Returns non-zero if window has been mapped; zero otherwise.

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to check for visibility
Returns
A non-zero value if the window has been both registered and mapped (i.e. is visible), otherwise zero.

This function only works for windows that have been registered with a callback function. It checks the internal flags to see if the window has been mapped, and if it has, it returns a non-zero value. It can be helpful to avoid unnecessary signals from the X11 API.

Header File: window_helper.h

Definition at line 5533 of file window_helper.c.

◆ WBIsValid()

int WBIsValid ( Display *  pDisplay,
Window  wID 
)

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

Parameters
pDisplayThe Display pointer associated with the specified window
wIDA 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.

◆ WBKeyEventProcessKey()

int WBKeyEventProcessKey ( const XKeyEvent *  pEvent,
char *  pBuf,
int *  pcbLen,
int *  piAltCtrlShift 
)

Generic keyboard event translation utility.

Parameters
pEventA const pointer to an XKeyEvent structure to process
pBufA buffer to receive translated keystroke information (may be NULL, see below)
pcbLenA pointer to an integer (pre-assigned to the length of pBuf) that receives the actual data length (see below) (may be NULL)
piAltCtrlShiftA pointer to an integer that receives bit flags associated with CTRL ALT and SHIFT states (may be NULL)
Returns
The first byte of the character string when 'pBuf' is NOT NULL, or a translated UTF character of 1, 2, or 4 bytes when pBuf is NULL

generic utility to process a keystroke. 'pcbLen' must be pre-assigned to size of 'pBuf' if 'pBuf' is to be written to. Any parameter other than 'pEvent' may be NULL. when pBuf is NULL, pcbLen (if not NULL) receives the required length in bytes when pcbLen is NULL and pBuf is not, length is assumed to be 1 byte return value is the first byte of the character string when 'pBuf' is NOT NULL, or a translated UTF character of 1, 2 or 4 bytes (when pBuf is NULL).

See also
aWB_CHAR, aWB_POINTER

Header File: window_helper.h

Definition at line 6834 of file window_helper.c.

◆ WBLocateWindow()

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

◆ WBMapRaised()

int WBMapRaised ( Display *  pDisplay,
Window  wID 
)

wrapper for XMapRaised, makes window visible and moves to top

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to map (i.e. make visible) and Raise (bring to the front)
Returns
The return value from XMapRaised()

Use this function when 'raising' a window, rather than XMapRaised so that the internal state flags and other information can be updated

Header File: window_helper.h

Definition at line 5465 of file window_helper.c.

◆ WBMapWindow()

int WBMapWindow ( Display *  pDisplay,
Window  wID 
)

Wrapper for XMapWindow, makes window visible.

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to map (i.e. make visible)
Returns
The return value from XMapWindow()

Use this function when making a window visible, rather than XMapWindow so that the internal state flags and other information can be updated.

Header File: window_helper.h

Definition at line 5421 of file window_helper.c.

◆ WBMouseCancel()

void WBMouseCancel ( Display *  pDisplay,
Window  wID 
)

low-level event processing, internal handling of Expose events

Parameters
pDisplayThe display for the mouse activity. A value of NULL uses the default display, either for 'wID', or the system default if wID is 'None'.
wIDThe window to post the 'WB_POINTER_CANCEL' message to. This window should have the input focus. A value of 'None' indicates the window with the input focus.

Call this function to effectively 'cancel' any operation involving the mouse. This will un-do any 'drag' operations and send a WB_POINTER Client Message event with the 'WB_POINTER_CANCEL', and optionally un-grab the mouse (and keyboard, as needed). In the case of a Modal operation, this may differ from normal Asynchronous operations. Additionally, if there are any mouse messages already in the queue, this will not remove them. It will be up to the caller to deal with that. This function ONLY fixes the status and capture of the mouse.

Header File: window_helper.h

Definition at line 5335 of file window_helper.c.

◆ WBNextEvent()

int WBNextEvent ( Display *  pDisplay,
XEvent *  pEvent 
)

low-level event queue wrapper. Implements the client-side event queue. Does not block if no events available.

Parameters
pDisplayThe Display pointer to query events on
pEventA pointer to an XEvent structure to receive event info
Returns
a non-zero value if an event was obtained, or zero if no event was available

Similar to XNextEvent, this function checks the internal event queues for an event. Unlike XNextEvent it does not wait for an event to be available before returning. The function returns zero if there are no events to be processed.

This function will not pull events out of the X server's event queue. It ONLY manages 'internal' queued events, prioritizing them as needed.

See WBCheckGetEvent(), WBWaitForEvent()

Header File: window_helper.h

Definition at line 8839 of file window_helper.c.

◆ WBPointInWindow()

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

◆ WBPostAppEvent()

int WBPostAppEvent ( XEvent *  pEvent)

Places a copy of the specified event at the end of the priority (internal) event queue.

Parameters
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent or calling WBDispatch directly.
Use WBPostAppEvent for application events (where the window ID is 'None')

Header File: window_helper.h

Definition at line 8878 of file window_helper.c.

◆ WBPostDelayedEvent()

void WBPostDelayedEvent ( XEvent *  pEvent,
unsigned int  nDelay 
)

Delays placing a copy of the specified event at the end of the regular (internal) event queue by a specified number of milliseconds.

Parameters
pEventA pointer to an XEvent structure containing the event info
nDelayThe number of milliseconds to delay posting the event

Use this function to effectively delay an event's posting to the internal queue for a specified period of time, in milliseconds. For application messages, specify 'None' for the Window ID in the XEvent structure (otherwise specify the correct Window ID). After the time delay, the event will be retrieved and returned via WBCheckGetEvent(), or WBNextEvent(), similar to a timer message. If the window specified in the message is destroyed before the timeout, the message will be ignored.

Header File: window_helper.h

Definition at line 8857 of file window_helper.c.

◆ WBPostDelayedSetFocusAppEvent()

void WBPostDelayedSetFocusAppEvent ( Display *  pDisplay,
Window  wID,
Window  wIDFrom,
unsigned int  nDelay 
)

Creates a 'set focus' ClientMessage event for the application event handler.

Parameters
pDisplayThe Display pointer, or 'None' to use default
wIDThe Window ID of the window to be set active, raised, and mapped
wIDFromThe previous window that was active, or None
nDelayThe delay in milliseconds before this action takes place (useful to prevent race conditions)

Causes (reliable) 'Set Active' 'Set Input Focus' 'Raise Window' and 'Map Window' events to be applied to a particular window. In many cases window managers may differ in their handling of things like 'XSetInputFocus' to set focus to a window. By handling this in the application event queue, it is possible to delay events asynchronously in a manner that avoids a race condition from the window manager. Clicking on a window, or using ALT+Tab, or switching desktops may cause unexpected 'things' to take place. By forcing the window to be ACTIVE and also using the normal 'XSetInputFocus' function, as well as 'Raising' and mapping the window, THIS method is likely to work everywhere, and in a consistent manner.

Header File: window_helper.h

Definition at line 8891 of file window_helper.c.

◆ WBPostEvent()

int WBPostEvent ( Window  wID,
XEvent *  pEvent 
)

Places a copy of the specified event at the end of the regular (internal) event queue.

Parameters
wIDThe Window ID of the event to be posted. The default 'Display *' will be used
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent() or calling WBDispatch() or WBWindowDispatch() directly.
You should always use this function for asynchronously posting non-priority events, such as notifications and timers, or when recursion may occur. Note that any pointers or X11 resources that are passed using XEvent may not be valid by the time they are received. If you must pass volatile data to a window, use WBDispatch() or WBWindowDispatch() instead.

Header File: window_helper.h

Definition at line 8844 of file window_helper.c.

◆ WBPostPriorityEvent()

int WBPostPriorityEvent ( Window  wID,
XEvent *  pEvent 
)

Places a copy of the specified event at the end of the priority (internal) event queue.

Parameters
wIDThe Window ID of the event to be posted. The default 'Display *' will be used
pEventA pointer to an XEvent structure containing the event info
Returns
A non-zero value on error, or zero if successful

The preferred method of event processing between windows is to post them to one of the internal event queues, rather than using XSendEvent() or calling WBDispatch() or WBWindowDispatch() directly.
Use WBPostPriorityEvent for priority events, such as UI handling (where performance is critical)

Header File: window_helper.h

Definition at line 8862 of file window_helper.c.

◆ WBProcessExposeEvent()

void WBProcessExposeEvent ( XExposeEvent *  pEvent)

low-level event processing, internal handling of Expose events

Parameters
pEventA pointer to an XExposeEvent structure for an Expose event

Instead of passing Expose events directly along to the respective window, they are first consolidated, and then re-prioritized for optimimum display performance.
Expose events typically come in bunches, and all too frequently. By delaying their processing, AND consolidating them into a single event, it is possible to minimize the un-necessary re-drawing of windows and improve the 'apparent speed' of your applicatino. Normally this is done within WBCheckGetEvent() automatically. If you decide to implement the message prioritization yourself, you can use this function to handle Expose events for you, and correctly prioritize them.

Header File: window_helper.h

Definition at line 5316 of file window_helper.c.

◆ WBQueryGCFont()

WB_FONTC WBQueryGCFont ( WBGC  gc)

return the WB_FONTC object that was assigned to a WBGC

Parameters
gcThe WBGC to be queried
Returns
A pointer to a WB_FONTC object, or NULL on error.

Call this function to determine the font that has been assigned to a WBGC. If there has been NO font assigned, the system default font information will be returned. A value of NULL is returned on error, or if no font is assigned.

This function differs from WBGetGCFont() in that it does not create a new copy of an existing GC. Therefore, the return value is only valid within the context of the call to WBQueryGCFont() and should NOT be passed to WBFreeFont().

Header File: window_helper.h

See also
WBGetGCFont()

Definition at line 1304 of file graphical_api.c.

◆ WBQueryWindowFont()

WB_FONTC WBQueryWindowFont ( Window  wID)

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

Parameters
wIDThe 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.

◆ WBRectToRegion()

Region WBRectToRegion ( const WB_RECT pRect)

'Paint' helper, converts a WB_RECT structure to a Region.

Parameters
pRectA const pointer to the WB_RECT structure
Returns
A region that encompasses the area of the WB_RECT structure, or None on error

This function converts a WB_RECT structure to a Region. The caller must destroy the returned value using XDestroyRegion()

Header File: window_helper.h

Definition at line 7664 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.

◆ WBRegisterMenuCallback()

void WBRegisterMenuCallback ( Window  wID,
WBWinEvent  pCallback 
)

(internal) Register a MENU callback for a window

The various 'menu' windows and popups will make use of the assigned 'menu callback' function to register a special event handler that deals with main window events. Event processing via WBWindowDispatch() invokes the menu callback whenever it is assigned. To disable the special event handling, assign the 'menu callback' function to NULL.

Normally, you should not make use of this function in your own application.

Header File: window_helper.h

Definition at line 7124 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
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 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
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 6993 of file window_helper.c.

◆ WBRestoreDefaultCursor()

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

◆ WBSetApplicationWindow()

void WBSetApplicationWindow ( Window  wID)

Assign the main 'Appklication' 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 3300 of file window_helper.c.

◆ WBSetBackground()

int WBSetBackground ( WBGC  hGC,
unsigned long  background 
)

Assign background color, a wrapper for XSetBackground()

Parameters
hGCThe WBGC to set the background color of
backgroundThe background color
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1490 of file graphical_api.c.

◆ WBSetClipboardData()

int WBSetClipboardData ( Display *  pDisplay,
Atom  aType,
int  iFormat,
const void *  pData,
unsigned long  nData 
)

Get clipboard data of requested type.

Parameters
pDisplaythe Display pointer for the selection (NULL for default)
aTypean atom indicating the data type
iFormatthe data format (0, 8, 16, or 32)
pDataa pointer to the data to be assigned (can be NULL, indicating you want to clear it)
nDatathe size of the data (number of items, based on iFormat)
Returns
a value of zero on success, or non-zero on error

This function assigns the clipboard data for the specified type ('aType') and format ('iFormat') to the data specified by 'pData' and 'nData'.

Header File: window_helper.h

Definition at line 1849 of file clipboard_helper.c.

◆ WBSetClipMask()

int WBSetClipMask ( WBGC  hGC,
Pixmap  pixmap 
)

Set clip mask, a wrapper for XSetClipMask()

Parameters
hGCThe WBGC to assign a clipping Region to
pixmapA pixmap containing the clipping mask
Returns
an integer indicating success or fail

Header File: window_helper.h

Definition at line 1436 of file graphical_api.c.

◆ WBSetClipOrigin()

int WBSetClipOrigin ( WBGC  hGC,
int  clip_x_origin,
int  clip_y_origin 
)

Set clip origin, a wrapper for XSetClipOrigin()

Parameters
hGCThe WBGC to assign a clipping Region to
clip_x_originThe 'x' clipping origin
clip_y_originThe 'y' clipping origin
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1422 of file graphical_api.c.

◆ WBSetDashes()

int WBSetDashes ( WBGC  hGC,
int  dash_offset,
const char  dash_list[],
int  n 
)

Assign font to a WBGC, a wrapper for XSetFont()

Parameters
hGCThe WBGC to assign a clipping Region to
dash_offsetThe 'dash offset' for creating dashes
dash_listAn array of 'char' values containing the dash info
nThe number of entries in 'dash_list'
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1582 of file graphical_api.c.

◆ WBSetFont()

int WBSetFont ( WBGC  hGC,
WB_FONTC  pFont 
)

Assign font to a WBGC, a wrapper for XSetFont()

Parameters
hGCThe WBGC to assign a clipping Region to
pFontThe WB_FONTC to assign to the WBGC (makes a copy of it)
Returns
an integer indicating success or fail
See also
WBQueryGCFont(), WBGetGCFont()

Header File: window_helper.h

Definition at line 1503 of file graphical_api.c.

◆ WBSetFontNoCopy()

int WBSetFontNoCopy ( WBGC  hGC,
WB_FONT  pFont 
)

Assign font to a WBGC, a wrapper for XSetFont()

Parameters
hGCThe WBGC to assign a clipping Region to
pFontThe WB_FONT to assign to the WBGC directly without copying
Returns
an integer indicating success or fail

The assigned WB_FONT will be stored directly into the WBGC and not copied first. This means that the WBGC will 'take ownership' of the WB_FONT immediately after making this call. The caller must ensure that it is safe for the WBGC object to own such a WB_FONT.

See also
WBQueryGCFont(), WBGetGCFont()

Header File: window_helper.h

iRet &&

Definition at line 1532 of file graphical_api.c.

◆ WBSetForeground()

int WBSetForeground ( WBGC  hGC,
unsigned long  foreground 
)

Assign foreground color, a wrapper for XSetForeground()

Parameters
hGCThe WBGC to set the foreground color of
foregroundThe foreground color
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1477 of file graphical_api.c.

◆ WBSetFunction()

int WBSetFunction ( WBGC  hGC,
int  function 
)

Set the 'function' for the WBGC, a wrapper for XSetFunction()

Parameters
hGCThe WBGC to assign a clipping Region to
functionThe 'function' for the GC - for more information, see XSetFunction()
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1464 of file graphical_api.c.

◆ WBSetInputFocus()

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

◆ WBSetLineAttributes()

int WBSetLineAttributes ( WBGC  hGC,
unsigned int  line_width,
int  line_style,
int  cap_style,
int  join_style 
)

Assign font to a WBGC, a wrapper for XSetLineAttributes()

Parameters
hGCThe WBGC to assign a clipping Region to
line_widthThe line width, in pixels
line_styleThe line style - see XSetLineAttributes()
cap_styleThe cap style - see XSetLineAttributes()
join_styleThe join style - see XSetLineAttributes()
Returns
an integer indicating success or fail

Most of the cached GC values are stored in the 'values' member of the WBGC structure. It is safe to read this structure directly, though you should never assign anything to it without using one of the API functions.

See also
WBGC

Header File: window_helper.h

Definition at line 1565 of file graphical_api.c.

◆ WBSetParentWindow()

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

◆ WBSetRegion()

int WBSetRegion ( WBGC  hGC,
Region  rgnClip 
)

Assign clipping region, wrapper for XSetRegion()

Parameters
hGCThe WBGC to assign a clipping Region to
rgnClipThe clipping region to assign to the WBGC
Returns
an integer indicating success or fail

Header File: window_helper.h

Definition at line 1382 of file graphical_api.c.

◆ WBSetSelectionData()

int WBSetSelectionData ( Display *  pDisplay,
Atom  aSelection,
Atom  aType,
int  iFormat,
const void *  pData,
unsigned long  nData 
)

Get clipboard data of requested type.

Parameters
pDisplaythe Display pointer for the selection (NULL for default)
aSelectionan Atom for the 'selection' data to assign (usually 'CLIPBOARD' or XA_PRIMARY)
aTypean atom indicating the data type
iFormatthe data format (0, 8, 16, or 32)
pDataa pointer to the data to be assigned (can be NULL, indicating you want to clear it)
nDatathe size of the data (number of items, based on iFormat)
Returns
a value of zero on success, or non-zero on error

This function assigns the selection data for the specified target 'aSelection' and type ('aType') and format ('iFormat') to the data specified by 'pData' and 'nData'.

Header File: window_helper.h

Definition at line 2061 of file clipboard_helper.c.

◆ WBSetWindowClassName()

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

◆ WBSetWindowCursor()

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

◆ WBSetWindowDefaultCursor()

void WBSetWindowDefaultCursor ( Window  wID,
int  idStandardCursor 
)

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

Parameters
wIDThe Window ID to which to assign 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 6335 of file window_helper.c.

◆ WBSetWindowDefaultGC()

void WBSetWindowDefaultGC ( Window  wID,
WBGC  hGC 
)

assigns a default WBGC to a window

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

Header File: window_helper.h

Definition at line 5774 of file window_helper.c.

◆ WBSetWindowFont()

void WBSetWindowFont ( Window  wID,
WB_FONTC  pFont 
)

assigns the default WB_FONT object for a window

Parameters
wIDThe Window ID from which to return the default font
pFontThe 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
wIDThe Window ID from which to return the default icon
idIconThe 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
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 3004 of file window_helper.c.

◆ WBSetWMProperties()

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

◆ WBSetWMPropertiesWindowType()

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

◆ WBSetWMProtocols()

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

◆ WBShowModal()

int WBShowModal ( Window  wID,
int  bMenuSplashFlag 
)

Shows a 'modal' window by processing events until the window closes.

Parameters
wIDWindow to be made modal
bMenuSplashFlagTri-state boolean indicating menu/splash/normal. A value of 0 is normal, > 0 menu, < 0 splash
Returns
-1 on error, or the dialog box's 'WBEndModal()' iReturn value

Use this function to show a 'modal' window. The function returns when the window is closed. 'bMenuFlag' is > 0 if menu semantics need to be applied to the modal window, or < 0 if splash semantics need to be applied. Otherwise, it is treated as a NORMAL (dialog) window.

The return value is -1 on error, or the value specified by 'iReturn' in the call to WBEndModal().

Header File: window_helper.h

Definition at line 1862 of file window_helper.c.

◆ WBSupressErrorOutput()

static __inline__ void WBSupressErrorOutput ( void  )
static

Supress X11 XErrorEvent output to stderr.

Call this function to increment the error output supression counter. Error output will be restored whenever the supression counter returns to zero. Each call to this function should be balanced with a call to WBAllowErrorOutput().

Header File: window_helper.h

Definition at line 3685 of file window_helper.h.

◆ WBThreadFreeDisplay()

void WBThreadFreeDisplay ( Display *  pThreadDisplay)

un-initializes a Display for a thread that was allocated by WBThreadInitDisplay()

Parameters
pThreadDisplaya Display pointer that was created via WBThreadInitDisplay()

Call this function to free a thread-specific Display object that was created by WBThreadInitDisplay() to free up resources before exiting the thread.

Header File: window_helper.h

Definition at line 1781 of file window_helper.c.

◆ WBThreadInitDisplay()

Display* WBThreadInitDisplay ( void  )

initializes default Display for a thread (must call WBInit() first)

Returns
A pointer to the Display, or NULL on error

Call this function to create a thread-specific Display object when you need to process a message loop or create windows within that thread. You must call WBThreadFreeDisplay() to free up resources before exiting the thread.

Header File: window_helper.h

Definition at line 1755 of file window_helper.c.

◆ WBUnmapWindow()

int WBUnmapWindow ( Display *  pDisplay,
Window  wID 
)

wrapper for XUnmapWindow, makes window invisible without destroying it

Parameters
pDisplayA pointer to the Display
wIDThe Window ID for the window to unmap (i.e. make INvisible)
Returns
The return value from XUnmapWindow()

Use this function when making a window invisible, rather than XUnmapWindow so that the internal state flags and other information can be updated

Header File: window_helper.h

Definition at line 5508 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.

◆ WBUpdateWindow()

void WBUpdateWindow ( Window  wID)

'Paint' helper, generates an asynchronous Expose event for non-empty 'invalid' region

Whenever the 'invalid' region is non-empty, you can generate an asynchronous Expose event using this function. This allows you to invalidate several geometries or regions during normal processing, with the paint flag set to 'false', and then generate a single Expose event after all of the processing has completed.

Header File: window_helper.h

Definition at line 7211 of file window_helper.c.

◆ WBUpdateWindowImmediately()

void WBUpdateWindowImmediately ( Window  wID)

'Paint' helper, generates an immediate Expose event for non-empty 'invalid' region

Whenever the 'invalid' region is non-empty, you can generate an immediate (synchronous) Expose event using this function. This is useful for a UI related event in which you need to re-paint portions of a window immediately.
You should make sure that the Expose handler does not cause recursion, since it will be called directly by this function.

Header File: window_helper.h

Definition at line 7271 of file window_helper.c.

◆ WBUpdateWindowWithImage()

void WBUpdateWindowWithImage ( Display *  pDisplay,
Window  wID 
)

Update the window's appearance with the contents of the cached XImage.

Parameters
pDisplayThe display associated with the specified window
wIDThe window that receives the aWB_TIMER XClientEvent (None == application)

Calling this function will update the window's display area with the contents of the cached image. If there is no cached image, this function will have no effect.

Whenever graphics operations make use of the cached image, an implicit call to WBUpdateWindowWithImage() will be made within the call to WBEndPaint().

Header File: window_helper.h

See also
WBBeginPaint() WBEndPaint()

Definition at line 8199 of file window_helper.c.

◆ WBValidateGeom()

void WBValidateGeom ( Window  wID,
const WB_GEOM pGeom 
)

'Paint' helper, validates a geometry for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pGeomA pointer to a WB_GEOM structure specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a geometry from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 7455 of file window_helper.c.

◆ WBValidateRect()

static __inline__ void WBValidateRect ( Window  wID,
WB_RECT pRCT 
)
static

'Paint' helper, validates a WB_RECT for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
pRCTA const pointer to a WB_RECT structure specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a rectangle from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 2815 of file window_helper.h.

◆ WBValidateRegion()

void WBValidateRegion ( Window  wID,
Region  rgn 
)

'Paint' helper, validates a region for asynchronous Expose event generation

Parameters
wIDThe Window ID for the affected window
rgnA Region identifer specifying the valid area, or NULL (implying the entire window)

In conjunction with WBProcessExposeEvent it removes a region from the 'invalid' region associated with the window. If the resulting 'invalid' region is empty, no subsequent 'Expose' event will be generated, even if one had previously been in the queue, until the next Expose event or 'invalid' region exists for this window.

Header File: window_helper.h

Definition at line 7520 of file window_helper.c.

◆ WBWaitForEvent()

void WBWaitForEvent ( Display *  pDisplay)

Wait for an event, blocking indefinitely.

Parameters
pDisplaya pointer to the Display on which to wait for events

Call this function to wait until a new event is available in the event queue. This function will block indefinitely until such an event is available.
NOTE: if 'bQuitFlag' is set, this function will return immediately.

See WBNextEvent(), WBCheckGetEvent()

Header File: window_helper.h

Definition at line 3730 of file window_helper.c.

◆ WBWindowDispatch()

int WBWindowDispatch ( Window  wID,
XEvent *  pEvent 
)

Dispatches a window XEvent. May be called directly.

Parameters
wIDThe Window ID that will be 'dispatched' the event, regardless of the event structure contents
pEventA pointer to an XEvent structure to process
Returns
The integer value returned by the window's event callback

Dispatches an XEvent for the specified window. Normally, WBDispatch will call this function using the window ID from the XEvent itself, and pass that ID as the first parameter. A caller may choose to send the event to a different window, specifying its window ID instead. This is similar to a modal 'Event Send' and can be useful to have a parent or child window handle a particular type of event (rather than the destined window).

Header File: window_helper.h

Definition at line 4678 of file window_helper.c.

◆ WBXlatCoordGeom()

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

◆ WBXlatCoordPoint()

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

◆ WBXlatCoordRect()

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

Variable Documentation

◆ aAVERAGE_WIDTH

const Atom aAVERAGE_WIDTH

Atoms for fonts - Average Character Width.

Average Character Width (font property)

Definition at line 505 of file window_helper.c.

◆ aBITMAP

const Atom aBITMAP

BITMAP Atom for the clipboard - uses XA_BITMAP.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 571 of file window_helper.c.

◆ aC_STRING

const Atom aC_STRING

C_STRING Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 635 of file window_helper.c.

◆ aCLIPBOARD

const Atom aCLIPBOARD

CLIPBOARD Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 515 of file window_helper.c.

◆ aCOLORMAP

const Atom aCOLORMAP

COLORMAP Atom for the clipboard - uses XA_COLORMAP.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 587 of file window_helper.c.

◆ aCOMPOUND_TEXT

const Atom aCOMPOUND_TEXT

COMPOUND_TEXT Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 643 of file window_helper.c.

◆ aCONTROL_NOTIFY

const Atom aCONTROL_NOTIFY

dialog control and child window notification messages

These events are posted to the owning window (or dialog box frame) for controls that are members of the dialog box or window. These provide a powerful asynchronous method by which you can handle user input and other information directly from the control windows.

CONTROL_NOTIFY message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aCONTROL_NOTIFY
format == 32 (always)
data.l[0] contains the dialog control ID (or -1 if N/A)
data.l[1] is the notify code
data.l[2] is window ID

Other data elements are specific to the type notify code being used.
For more information, see: Notification Atoms

Definition at line 256 of file window_helper.c.

◆ aDESTROY_NOTIFY

const Atom aDESTROY_NOTIFY

notify parent that child is being destroyed

RESERVED - not yet implemented TODO document DESTROY_NOTIFY format here

Definition at line 233 of file window_helper.c.

◆ aDLG_FOCUS

const Atom aDLG_FOCUS

dialog focus messages

DLG_FOCUS message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aDLG_FOCUS
format == 32 (always)
data.l[0] is a tri-state value as follows

  • less than zero for 'previous window'
  • greater than zero for 'next window'
  • equal to zero for 'set to this window'

for data.l[0] == 0

  • data.l[1] is the control id to set focus to
  • data.l[2] is non-zero if the control focus was assigned via a hot-key, else zero.

by convention, all remaining entries in 'data.l' should be zero

Definition at line 360 of file window_helper.c.

◆ aDRAWABLE

const Atom aDRAWABLE

DRAWABLE Atom for the clipboard - uses XA_DRAWABLE.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 579 of file window_helper.c.

◆ aINCR

const Atom aINCR

INCR Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 555 of file window_helper.c.

◆ aMANAGER

const Atom aMANAGER

MANAGER Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 539 of file window_helper.c.

◆ aMENU_COMMAND

const Atom aMENU_COMMAND

commands sent by menus via ClientMessage

MENU_COMMAND message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aMENU_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] Window ID of the menu bar

Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer. This will be done automatically by the message framework.

Definition at line 166 of file window_helper.c.

◆ aMENU_UI_COMMAND

const Atom aMENU_UI_COMMAND

UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'.

MENU_COMMAND message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aMENU_UI_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] secure hash for WBMenuItem object pointer - see WBCreatePointerHash()
data.l[3] the value '0' (reserved)
data.l[4] the value '0' (reserved)

A Frame Window returns '0' to indicate that the menu should be displayed normally (same as 'not handled')
Other return values alter the display of the menu.

For a popup menu: -1 : disables the menu 1 : enables the menu (default behavior if no UI handler present, but menu handler IS present) 0 : menu item NOT handled (menu item will be greyed)

For a dynamic menu: (preliminary) - popup menu items only (not found in top-level menus) -1 : disabled the menu 0 : 'not handled' or 'error' (no dynamic menu will be added or displayed) >0 : a 'secure internal pointer hash' representing an actual pointer value (preliminary, RESERVED) this pointer will be to a WBAlloc'd block of memory describing the menu items (as text). It will be necessary for the caller to interpret this text to create the dynamic memory items. PRELIMINARY: the text will be 'menu text\tAtom Name' - no hotkeys, no tooltip text. The menu text can include underscores which will only work when the popup is available

Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer, nor for the WBMenuItem object pointer. This will be done automatically by the message framework.

Definition at line 204 of file window_helper.c.

◆ aMULTIPLE

const Atom aMULTIPLE

MULTIPLE Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 659 of file window_helper.c.

◆ aNULL

const Atom aNULL

NULL Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 675 of file window_helper.c.

◆ aPIXEL

const Atom aPIXEL

PIXEL Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 595 of file window_helper.c.

◆ aPIXMAP

const Atom aPIXMAP

PIXMAP Atom for the clipboard - uses XA_PIXMAP.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 603 of file window_helper.c.

◆ aPRIMARY

const Atom aPRIMARY

PRIMARY Atom for the clipboard - uses XA_PRIMARY.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 523 of file window_helper.c.

◆ aQUERY_CLOSE

const Atom aQUERY_CLOSE

query if it's ok to close (and optionally destroy yourself if ok) a window

QUERY_CLOSE message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aQUERY_CLOSE
format == 32 (always)
data.l[0] contains a non-zero value if the window should destroy its private data NOW; 0 otherwise

Window callbacks should check for this and return '0' when it's ok to destroy the window, a positive value if it's NOT ok, or a negative value on error.

Whenever data.l[0] contains a non-zero value, and it's ok to close the window, the window event handler should destroy all of its private data, zero out data element '0' for the window data (if it pointed to the private data), and call WBUnregisterWindowCallback() for itself. The window will be destroyed by the sender as soon as the callback returns.

If the callback returns a non-zero value, it should not destroy any of its own private data. The sender will assume that it's not ok to close the window and will try to leave everything 'as-is'.

Generally, you should return 0 from your event handler if it is ok to close the window, 1 if NOT ok to close, and '-1' on error.

Definition at line 312 of file window_helper.c.

◆ aRECALC_LAYOUT

const Atom aRECALC_LAYOUT

notify window that it should re-calculate things like scrollbars and viewports

RECALC_LAYOUT message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aRECALC_LAYOUT
format == 32 (always)

A window that has a viewport and scrollbars, using a text object or other construct that supports this ClientMessage atom, should check for this message and recalculate viewports and scrollbar positions whenever it is received. If scroll positions have changed, you should invalidate the entire window rectangle so that it can be re-painted. However, you should not paint the window synchronously. You should rely on asynchronous processing of Expose events.

In some cases, default handling of 'recalc layout' functionality may cause aRESIZE_NOTIFY client message events to be dispatched. Care should be taken to NOT cause an infinite loop or infinite recursion due to the handling of these events.

See also
aRESIZE_NOTIFY

Definition at line 336 of file window_helper.c.

◆ aRESIZE_NOTIFY

const Atom aRESIZE_NOTIFY

notification of window re-size via ClientMessage

RESIZE_NOTIFY message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aRESIZE_NOTIFY
format == 32 (always)
data.l[0] new 'left' client rectangle coordinate
data.l[1] new 'top' client rectangle coordinate
data.l[2] new 'right' client rectangle coordinate
data.l[3] new 'bottom' client rectangle coordinate

The return value is ignored. It is typically sent via a direct call to the message callback function. Since it is merely a notification message, it does not need to be handled. The specified coordinates are in 'client' coordinates relative to the upper left corner of the client area, which is always (0,0).

Definition at line 224 of file window_helper.c.

◆ aSCROLL_NOTIFY

const Atom aSCROLL_NOTIFY

Scroll notifications via ClientMessage

SCROLL_NOTIFY message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aSCROLL_NOTIFY
format == 32 (always)
data.l[0] Identifies the bar (WB_SCROLL_VERTICAL, WB_SCROLL_HORIZONTAL, or WB_SCROLL_DEFAULT)
data.l[1] Indicates the notification type, one of the following:

  • WB_SCROLL_KNOB 'knob track' - knob position will be in data.l[2]
  • WB_SCROLL_FORWARD move down, or move right
  • WB_SCROLL_BACKWARD move up, or move left
  • WB_SCROLL_PAGEFWD page down or page right
  • WB_SCROLL_PAGEBACK page up or page left
  • WB_SCROLL_FIRST scroll to first entry, i.e. home or top
  • WB_SCROLL_LAST scroll to last entry, i.e. bottom or end
  • WB_SCROLL_DBLCLICK double-click detection (no selection info in data.l[2])
  • WB_SCROLL_ABSOLUTE absolute scroll, to the absolute position in data.l[2]
  • WB_SCROLL_RELATIVE relative scroll, relative +/- position in data.l[2]
  • WB_SCROLL_NA generic 'NA' or 'UNDEFINED' value

data.l[2] Optional parameter, typically the absolute or relative scroll position

Definition at line 284 of file window_helper.c.

◆ aSECONDARY

const Atom aSECONDARY

SECONDARY Atom for the clipboard - uses XA_SECONDARY.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 531 of file window_helper.c.

◆ aSET_FOCUS

const Atom aSET_FOCUS

dialog focus messages

SET_FOCUS message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aSET_FOCUS
format == 32 (always)
data.l[0] is the window ID to set focus to (None for default)
This message is typically sent to the application (.window = None)

By posting a SET_FOCUS message to the application, you can ASYNCHRONOUSLY fix focus-related problems, such as the window manager trying to set focus to the application window while a modal dialog is visible.
When sent to a frame window, you are requesting that it set the focus to the appropriate window, similar to aDLG_FOCUS
Assigning 'data.l[0]' to 'None' tells a frame window to set focus to the default. When the event is sent to the application, a value of 'None' is meaningless.

Definition at line 383 of file window_helper.c.

◆ aSTRING

const Atom aSTRING

STRING Atom for the clipboard - uses XA_STRING.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 619 of file window_helper.c.

◆ aTARGET

const Atom aTARGET

TARGET Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 547 of file window_helper.c.

◆ aTARGETS

const Atom aTARGETS

TARGETS Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 651 of file window_helper.c.

◆ aTEXT

const Atom aTEXT

TEXT Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 611 of file window_helper.c.

◆ aTIMESTAMP

const Atom aTIMESTAMP

TIMESTAMP Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 667 of file window_helper.c.

◆ aUTF8_STRING

const Atom aUTF8_STRING

UTF8_STRING Atom for the clipboard.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 627 of file window_helper.c.

◆ aWB_CHAR

const Atom aWB_CHAR

keystroke/character notifications generated by API

Mid-level keystroke handling generates WB_CHAR notifications via ClientMessage passed to the appropriate window in addition to normal key up/down events.

WB_CHAR notification message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aWB_CHAR
format == 32 (always)
data.l[0] is return from WBKeyEventProcessKey
data.l[1] is *piAltCtrlShift from WBKeyEventProcessKey
data.l[2] is # of characters decoded into data.l[3..4]
data.l[3..4] (as char[]) is decode buffer (at least 8 chars long, possibly 16 for 64-bit)

see also: WBKeyEventProcessKey()character notifications (generated by API; avoids key up/down handling)

Definition at line 404 of file window_helper.c.

◆ aWB_POINTER

const Atom aWB_POINTER

pointer click/double-click/drag notifications generated by API

Mid-level pointer click/double-click/drag handling generates WB_POINTER notifications (i.e. mouse motion) via ClientMessage passed to the appropriate window in addition to the normal pointer notification events via the normal event system.

WB_POINTER notification message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aWB_POINTER
format == 32 (always)
data.l[0] is one of the notification codes

data.l[1] is a bitmap of the mouse button state (bit set when pressed)

  • WB_POINTER_BUTTON1 - bit 0 - left button
  • WB_POINTER_BUTTON2 - bit 1 - right button
  • WB_POINTER_BUTTON3 - bit 2 - center button
  • WB_POINTER_BUTTON4 - bit 3 - mouse wheel up
  • WB_POINTER_BUTTON5 - bit 4 - mouse wheel down

data.l[2] is 'WB_KEYEVENT_xxx' mask for CTRL+ALT+SHIFT

  • WB_KEYEVENT_ALT
  • WB_KEYEVENT_CTRL
  • WB_KEYEVENT_SHIFT

data.l[3] is translated X coordinate
data.l[4] is translated Y coordinate

'pointer' notifications (generated by API)

Definition at line 465 of file window_helper.c.

◆ aWB_TIMER

const Atom aWB_TIMER

timer notifications generated by API

Mid-level timer handling generates WB_TIMER notifications via ClientMessage passed to the appropriate window, either periodic or 'one-shot'
See CreateTimer() for more information.

WB_TIMER message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aWB_TIMER
format == 32 (always)
data.l[0] is the unique identifier associated with the timer
see also: CreateTimer(), DeleteTimer()timer notifications (generated by API)

Definition at line 423 of file window_helper.c.

◆ aWINDOW

const Atom aWINDOW

WINDOW Atom for the clipboard - uses XA_WINDOW.

Used by Clipboard owners and clients to communicate.
More information at freedesktop.org WM documentation

Definition at line 563 of file window_helper.c.

◆ aWM_DELETE_WINDOW

const Atom aWM_DELETE_WINDOW

Delete Window notification event.

Used by Window Manager to instruct a window to close, typically activated by clicking on the 'x' button (or similar) in the window's title bar. More information at freedesktop.org WM documentation

Definition at line 485 of file window_helper.c.

◆ aWM_PROTOCOLS

const Atom aWM_PROTOCOLS

WM supported protocols.

Used by Window Manager to indicate supported protocols
More information at freedesktop.org WM documentation

Definition at line 475 of file window_helper.c.

◆ aWM_TAKE_FOCUS

const Atom aWM_TAKE_FOCUS

'Take Focus' - TODO document this properly

TODO document this properly

part of the WM_PROTOCOLS spec, ICCCM, associated with the focus bit in WM_HINTS
More information at freedesktop.org WM documentation

Definition at line 496 of file window_helper.c.