X11workbench Toolkit  1.0
Debug Helper

Macros

#define WB_DEBUG_PRINT(L, ...)   WB_IF_DEBUG_LEVEL(L) { WBDebugPrint(__VA_ARGS__); }
 Preferred method of implementing conditional debug output. More...
 
#define WB_DEBUG_DUMP(L, X, Y, Z)   WB_IF_DEBUG_LEVEL(L) { WBDebugDump(X,Y,Z); }
 Preferred method of implementing conditional debug 'dump' output. More...
 
#define WB_IF_DEBUG_LEVEL(L)   if(WBCheckDebugLevel((L)))
 Preferred method of implementing conditional debug 'if block' code. More...
 
#define WB_WARN_PRINT(...)   WB_DEBUG_PRINT(DebugLevel_WARN, __VA_ARGS__)
 Preferred method of implementing a 'warning level' debug message for all subsystems. More...
 
#define WB_ERROR_PRINT(...)   WB_DEBUG_PRINT(DebugLevel_ERROR, __VA_ARGS__)
 Preferred method of implementing an 'error level' debug message for all subsystems. More...
 
#define WB_WARN_DUMP(X, Y, Z)   WB_DEBUG_DUMP(DebugLevel_WARN, X,Y,Z)
 Preferred method of implementing a 'warning level' binary dump for all subsystems. More...
 
#define WB_ERROR_DUMP(X, Y, Z)   WB_DEBUG_DUMP(DebugLevel_ERROR, X,Y,Z)
 Preferred method of implementing an 'error level' binary dump for all subsystems. 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)
 

Enumerations

enum  DebugLevel {
  DebugLevel_None = 0, DebugLevel_ERROR = 0, DebugLevel_WARN = 1, DebugLevel_Minimal = 1,
  DebugLevel_Light = 2, DebugLevel_Medium = 3, DebugLevel_Heavy = 4, DebugLevel_Chatty = 5,
  DebugLevel_Verbose = 6, DebugLevel_Excessive = 7, DebugLevel_MASK = 7, DebugSubSystem_ALL = 0,
  DebugSubSystem_RESTRICT = 0x80000000, DebugSubSystem_BITSHIFT = 3, DebugSubSystem_Init = 0x00000008, DebugSubSystem_Application = 0x00000010,
  DebugSubSystem_Window = 0x00000020, DebugSubSystem_Menu = 0x00000040, DebugSubSystem_Event = 0x00000080, DebugSubSystem_Dialog = 0x00000100,
  DebugSubSystem_DialogCtrl = 0x00000200, DebugSubSystem_Frame = 0x00000400, DebugSubSystem_Keyboard = 0x00000800, DebugSubSystem_Mouse = 0x00001000,
  DebugSubSystem_Font = 0x00002000, DebugSubSystem_Settings = 0x00004000, DebugSubSystem_Selection = 0x00008000, DebugSubSystem_Pixmap = 0x00010000,
  DebugSubSystem_Expose = 0x00020000, DebugSubSystem_EditWindow = 0x00040000, DebugSubSystem_ScrollBar = 0x00080000, DebugSubSystem_MASK = ~7L
}
 Debug level enumeration. More...
 

Functions

void WBSetDebugLevel (unsigned int iLevel)
 set debug level More...
 
static __inline__ unsigned int WBGetDebugLevel (void)
 Returns the current debug level assigned by WBSetDebugLevel. More...
 
void WBDebugPrint (const char *pFmt,...) __attribute__((format(printf
 conditional debug message output More...
 
void void WBDebugDump (const char *szTitle, void *pData, int cbData)
 conditionally dumps binary data to debug message output More...
 
void WBDebugDumpGC (Display *pDisplay, GC hGC)
 dumps a GC's settings More...
 
void WBDebugDumpRegion (Region hRgn, int bRotate)
 dumps contents of a region More...
 
void WBDebugDumpEvent (XEvent *pEvent)
 dumps the contents of an XEvent More...
 
static __inline__ int WBCheckDebugLevel (unsigned int dwLevel)
 Check specified debug level against the value returned by WBGetDebugLevel() and return non-zero for a match. More...
 
void WBDumpFontInfo (const char *pSpec)
 Dump debug information about fonts according to pSpec. More...
 
void WBDebugDumpXColor (const char *szTitle, const XColor *pColor)
 Dump XColor members for debugging. More...
 
void WBDebugDumpColormap (const char *szTitle, const XStandardColormap *pMap)
 Dump XStandardColormap members for debugging. More...
 

Variables

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
 

Detailed Description

Functions, macros, and variables associated with debugging

Debug functions are only present in a debug build, and you can assign the 'debug level' for message generation. Message output goes to stderr by default. Code that is built for release will not execute anything inside of '()' for debug macros, so that your final code will be better optimized.

Macro Definition Documentation

◆ WB_DEBUG_DUMP

#define WB_DEBUG_DUMP (   L,
  X,
  Y,
 
)    WB_IF_DEBUG_LEVEL(L) { WBDebugDump(X,Y,Z); }

Preferred method of implementing conditional debug 'dump' output.

Parameters
LDebug level (bitmask of DebugLevel enumeration)
XA const pointer to a 0-byte terminated string containing the 'title' string
YA const void pointer to the data to be dumped
ZAn unsigned integer indicating the number of bytes to display

The remaining parameters are passed as-is to WBDebugDump()

Similar to WB_DEBUG_PRINT, this macro will conditionally dump binary data via the WBDebugDump() function. The first parameter, 'L', is the debug level (0 to 7) along with (optional) bits indicating which subsystems are applicable to this debug output. Specifying NO subsystem bits assumes ALL subsystems.
The remainng 3 parameters are passed to WBDebugDump as the title, data pointer, and size of the data (in bytes).

See also
DebugLevel

Definition at line 320 of file debug_helper.h.

◆ WB_DEBUG_PRINT

#define WB_DEBUG_PRINT (   L,
  ... 
)    WB_IF_DEBUG_LEVEL(L) { WBDebugPrint(__VA_ARGS__); }

Preferred method of implementing conditional debug output.

Parameters
LDebug level (bitmask of DebugLevel enumeration)

The remaining parameters are passed as-is to WBDebugPrint()

This macro conditionally generates debug output via WBDebugPrint(). Bits that are set in the debug level enable you to determine which debug messages you see and which ones remain 'hidden'. This macro easily allows you to implement filtered debug output. The first paramater, 'L', is the debug level (0 to 7) along with (optional) bits indicating which subsystems are applicable to this message. Specifying NO subsystem bits assumes ALL subsystems.
The remaining parameters, format string (and a variable number of parameters), are passed along to the WBDebugPrint function.

See also
DebugLevel

Definition at line 299 of file debug_helper.h.

◆ WB_ERROR_DUMP

#define WB_ERROR_DUMP (   X,
  Y,
 
)    WB_DEBUG_DUMP(DebugLevel_ERROR, X,Y,Z)

Preferred method of implementing an 'error level' binary dump for all subsystems.

Parameters
XA const pointer to a 0-byte terminated string containing the 'title' string
YA const void pointer to the data to be dumped
ZAn unsigned integer indicating the number of bytes to display

Preferred method of implementing an 'error level' binary dump for all subsystems

Definition at line 378 of file debug_helper.h.

◆ WB_ERROR_PRINT

#define WB_ERROR_PRINT (   ...)    WB_DEBUG_PRINT(DebugLevel_ERROR, __VA_ARGS__)

Preferred method of implementing an 'error level' debug message for all subsystems.

Preferred method of implementing an 'error level' debug message for all subsystems

Definition at line 356 of file debug_helper.h.

◆ WB_IF_DEBUG_LEVEL

#define WB_IF_DEBUG_LEVEL (   L)    if(WBCheckDebugLevel((L)))

Preferred method of implementing conditional debug 'if block' code.

Parameters
LDebug level (bitmask of DebugLevel enumeration)

Similar to WB_DEBUG_PRINT, this macro will conditionally execute a statement or block of code that follows. Example:

WB_IF_DEBUG_LEVEL(DebugLevel_WARN | DebugSubSystem_Keyboard)
{
// do something for warnings or higher debug level
}
See also
DebugLevel

Definition at line 339 of file debug_helper.h.

◆ WB_WARN_DUMP

#define WB_WARN_DUMP (   X,
  Y,
 
)    WB_DEBUG_DUMP(DebugLevel_WARN, X,Y,Z)

Preferred method of implementing a 'warning level' binary dump for all subsystems.

Parameters
XA const pointer to a 0-byte terminated string containing the 'title' string
YA const void pointer to the data to be dumped
ZAn unsigned integer indicating the number of bytes to display

Preferred method of implementing a 'warning level' binary dump for all subsystems

Definition at line 367 of file debug_helper.h.

◆ WB_WARN_PRINT

#define WB_WARN_PRINT (   ...)    WB_DEBUG_PRINT(DebugLevel_WARN, __VA_ARGS__)

Preferred method of implementing a 'warning level' debug message for all subsystems.

Preferred method of implementing a 'warning level' debug message for all subsystems

Definition at line 349 of file debug_helper.h.

Enumeration Type Documentation

◆ DebugLevel

enum DebugLevel

Debug level enumeration.

Debug Level enumeration and subsystem idetification enumeration

Bits 0 to 3 identify the level (0 = none, 7 = excessive)
The remaining bits identify the subsystem filters (no bits set for ALL)

See also
WBParseStandardArguments() in platform_helper.c, 'aszDebugSubSys[]' array

Definition at line 51 of file debug_helper.h.

Function Documentation

◆ WBCheckDebugLevel()

static __inline__ int WBCheckDebugLevel ( unsigned int  dwLevel)
static

Check specified debug level against the value returned by WBGetDebugLevel() and return non-zero for a match.

Parameters
dwLevelA combination of one or more 'DebugLevel_' and 'DebugSubSystem_' flags to check
Returns
A non-zero value if the specified debug level matches that returned by WBGetDebugLevel(), zero otherwise.

Various 'debug print' macros need to know what the current debug level is in order to filter their output. This function provides a standard way in which to obtain the debug level. It is defined 'inline' to minimize any performance impact and to allow optimization.

Header File: debug_helper.h

Definition at line 239 of file debug_helper.h.

◆ WBDebugDump()

void void WBDebugDump ( const char *  szTitle,
void *  pData,
int  cbData 
)

conditionally dumps binary data to debug message output

Parameters
szTitleThe title of the debug dump
pDataA pointer to the data to be dumped
cbDatathe number of bytes to dump

Allows you to generate a custom 'binary data dump' in an easily readable hex/ASCII format, using the debug message output

This function is enabled even for a non-debug build. To have conditional debug output ONLY for a debug build (or given debug level), use the various 'WB_DEBUG_PRINT()' (and related) macros.

Header File: debug_helper.h

Definition at line 658 of file platform_helper.c.

◆ WBDebugDumpColormap()

void WBDebugDumpColormap ( const char *  szTitle,
const XStandardColormap *  pMap 
)

Dump XStandardColormap members for debugging.

Parameters
szTitleA const pointer to a string, to be displayed as the title for debug output
pMapA const pointer to an XStandardColormap structure.

Call this to do a debug dump of XStandardColormap information

Header File: pixmap_helper.h

Definition at line 1518 of file pixmap_helper.c.

◆ WBDebugDumpEvent()

void WBDebugDumpEvent ( XEvent *  pEvent)

dumps the contents of an XEvent

Parameters
pEventan Event structure obtained via 'XNextEvent' or similar

Debug function that dumps out all of the members of the XNextEvent. It assumes that the event is genuine; that is, the 'display' 'window' etc. are valid.

This function is enabled even for a non-debug build. To have conditional debug output ONLY for a debug build (or given debug level), use the various 'WB_DEBUG_PRINT()' (and related) macros.

Header File: debug_helper.h

Definition at line 8752 of file window_helper.c.

◆ WBDebugDumpGC()

void WBDebugDumpGC ( Display *  pDisplay,
GC  hGC 
)

dumps a GC's settings

Parameters
pDisplayA pointer to the display
hGCThe graphics context to dump

Debug function that dumps out all of the settings for a GC that can be retrieved using normal API functions.

This function is enabled even for a non-debug build. To have conditional debug output ONLY for a debug build (or given debug level), use the various 'WB_DEBUG_PRINT()' (and related) macros.

Header File: debug_helper.h

Definition at line 8712 of file window_helper.c.

◆ WBDebugDumpRegion()

void WBDebugDumpRegion ( Region  hRgn,
int  bRotate 
)

dumps contents of a region

Parameters
hRgnThe region to dump
bRotateTrue if you want to rotate the output 90 degrees (useful for very WIDE regions)

Debug function that dumps out the contents of a region

This function is enabled even for a non-debug build. To have conditional debug output ONLY for a debug build (or given debug level), use the various 'WB_DEBUG_PRINT()' (and related) macros.

Header File: debug_helper.h

Definition at line 8821 of file window_helper.c.

◆ WBDebugDumpXColor()

void WBDebugDumpXColor ( const char *  szTitle,
const XColor *  pColor 
)

Dump XColor members for debugging.

Parameters
szTitleA const pointer to a string, to be displayed as the title for debug output
pColorA const pointer to an XColor structure.

Call this to do a debug dump of XColor information

Header File: pixmap_helper.h

Definition at line 1538 of file pixmap_helper.c.

◆ WBDebugPrint()

void WBDebugPrint ( const char *  pFmt,
  ... 
)

conditional debug message output

Parameters
pFmtA pointer to a 'printf' compatible format string

Additional parameters are those required by the format string

Sends output to the 'debug device' which is (by default) stderr using a function call convention similar to 'printf'.

This function is enabled even for a non-debug build. To have conditional debug output ONLY for a debug build (or given debug level), use the various 'WB_DEBUG_PRINT()' (and related) macros.

Header File: debug_helper.h

◆ WBDumpFontInfo()

void WBDumpFontInfo ( const char *  pSpec)

Dump debug information about fonts according to pSpec.

Parameters
pSpecAn ASCII specification for font matching

Use this function to gain insight into the available fonts. Output is dumped to stderr using the debug output functions.

Header File: font_helper.h

Definition at line 415 of file font_helper.c.

◆ WBGetDebugLevel()

static __inline__ unsigned int WBGetDebugLevel ( void  )
static

Returns the current debug level assigned by WBSetDebugLevel.

Returns
The current debug level and flags

Various 'debug print' macros need to know what the current debug level is in order to filter their output. This function provides a standard way in which to obtain the debug level. It is defined 'inline' to minimize any performance impact and to allow optimization.

Header File: debug_helper.h

Definition at line 124 of file debug_helper.h.

◆ WBSetDebugLevel()

void WBSetDebugLevel ( unsigned int  iLevel)

set debug level

This function should typically be called once, at the beginning of the program. Any changes made to the debug level will be applied 'live'

Pass the debug level as 'iLevel' 0 for none, 1 for minimal, 2 for more, etc. up to 7

Header File: debug_helper.h

Definition at line 603 of file platform_helper.c.