X11 Work Bench Toolkit  1.0
Debug Helper

Macros

#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_DEBUG_PRINT(L,...)
 Preferred method of implementing conditional debug output. More...
 
#define WB_DEBUG_DUMP(L, X, Y, Z)
 Preferred method of implementing conditional debug 'dump' output. More...
 
#define WB_IF_DEBUG_LEVEL(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...
 

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_MASK = ~7L
}
 Debug level enumeration. More...
 

Functions

void WBDumpFontInfo (const char *pSpec)
 Dump debug information about fonts according to pSpec. More...
 
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...
 

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

#define WB_DEBUG_DUMP (   L,
  X,
  Y,
 
)
Value:
{ \
if(!((L) & DebugSubSystem_MASK) || !(WBGetDebugLevel() & DebugSubSystem_MASK) \
|| (((L) & WBGetDebugLevel()) & DebugSubSystem_MASK) != 0) \
{ \
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 679 of file window_helper.h.

#define WB_DEBUG_PRINT (   L,
  ... 
)
Value:
{ \
if(!((L) & DebugSubSystem_MASK) || !(WBGetDebugLevel() & DebugSubSystem_MASK) \
|| (((L) & WBGetDebugLevel()) & DebugSubSystem_MASK) != 0) \
{ \
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 652 of file window_helper.h.

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

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

#define WB_IF_DEBUG_LEVEL (   L)
Value:
(!((L) & DebugSubSystem_MASK) || !(WBGetDebugLevel() & DebugSubSystem_MASK) \
|| (((L) & WBGetDebugLevel()) & DebugSubSystem_MASK) != 0))

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:

{
// do something for warnings or higher debug level
}
See Also
DebugLevel

Definition at line 705 of file window_helper.h.

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

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

Enumeration Type Documentation

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)

Enumerator
DebugLevel_None 

none (no debug output)

DebugLevel_ERROR 

errors (output whenever debug cmopiled in)

DebugLevel_WARN 

warnings (all debug levels)

DebugLevel_Minimal 

minimal, implies warnings and important information

DebugLevel_Light 

light, implies basic process/flow information

DebugLevel_Medium 

medium, implies process/flow tracing

DebugLevel_Heavy 

heavy, implies detailed process/flow tracing

DebugLevel_Chatty 

chatty, implies details about flow decisions

DebugLevel_Verbose 

verbose, implies details regarding information used for decision making

DebugLevel_Excessive 

excessive, implies more information that you probably want

DebugLevel_MASK 

mask for allowed 'level' values (none through Excessive)

DebugSubSystem_ALL 

'ALL' is the default unless masked bits are non-zero

DebugSubSystem_RESTRICT 

only show specific subsystems (prevents zero masked value)

DebugSubSystem_BITSHIFT 

bit # for 'lowest' subsystem bit

DebugSubSystem_Init 

initialization/termination

DebugSubSystem_Application 

application-level

DebugSubSystem_Window 

generic window processing

DebugSubSystem_Menu 

generic menu processing

DebugSubSystem_Event 

generic event processing

DebugSubSystem_Dialog 

dialog box (container window)

DebugSubSystem_DialogCtrl 

dialog controls

DebugSubSystem_Frame 

Frame windows.

DebugSubSystem_Keyboard 

generic keyboard processing

DebugSubSystem_Mouse 

generic mouse event processing

DebugSubSystem_Font 

font manager

DebugSubSystem_Settings 

settings manager

DebugSubSystem_Selection 

selection processing

DebugSubSystem_Pixmap 

pixmap handling

DebugSubSystem_Expose 

expose/paint handling

DebugSubSystem_MASK 

mask for allowed 'subsystem' bits

Definition at line 757 of file window_helper.h.

Function Documentation

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

Header File: window_helper.h

Definition at line 8973 of file window_helper.c.

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.

Header File: window_helper.h

Definition at line 9057 of file window_helper.c.

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.

Header File: window_helper.h

Definition at line 9017 of file window_helper.c.

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

Header File: window_helper.h

Definition at line 9126 of file window_helper.c.

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

Conditionally sends output to the 'debug device' which is (by default) stderr using a function call convention similar to 'printf'. When debug is disabled this function has no effect.

Header File: window_helper.h

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.

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: window_helper.h

Definition at line 542 of file window_helper.h.

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: window_helper.h

Definition at line 8944 of file window_helper.c.