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_DEFINE_PROFILE(__name) static int __wb_profile_##__name = -1
	Declaration of a profiling variable and description. More...

#define	WB_ENABLE_PROFILE(__name, __desc)
	Declaration of a profiling variable and description. More...

#define	WB_START_PROFILE(__name) WBStartProfile(__wb_profile_##__name)
	Start profiling using the specified profile variable. More...

#define	WB_STOP_PROFILE(__name) WBStopProfile(__wb_profile_##__name)
	Stop profiling using the specified profile variable. 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_MAXIMUM = 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_DrawText = 0x00100000, DebugSubSystem_Clipboard = 0x00200000, DebugSubSystem_TextObject = 0x00400000, DebugSubSystem_RESERVED2 = 0x00800000, DebugSubSystem_RESERVED3 = 0x01000000, DebugSubSystem_RESERVED4 = 0x02000000, DebugSubSystem_RESERVED5 = 0x04000000, DebugSubSystem_RESERVED6 = 0x08000000, DebugSubSystem_RESERVED7 = 0x10000000, DebugSubSystem_RESERVED8 = 0x20000000, DebugSubSystem_RESERVED9 = 0x40000000, DebugSubSystem_MAX = 0x40000000, DebugSubSystem_MASK = ~7L }
	Debug level enumeration. More...

Functions
void	WBSetDebugLevel (unsigned int iLevel)
	set debug level More...

static __inline__ WB_UINT64	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, WBGC 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 (WB_UINT64 dwLevel)
	Check specified debug level against the value returned by WBGetDebugLevel() and return non-zero for a match. More...

static void	WBDumpFontStruct (const XFontStruct *pFont)
	debug function to dump font struct members

static void	WBDumpMatchingFontNames (Display pDisplay, const char szFontName)
	debug function to dump matching font names

static void	WBDumpFontSet (Display *pDisplay, XFontSet fontSet)
	debug function to dump font set members

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,
		Z
	)	WB_IF_DEBUG_LEVEL(L) { WBDebugDump(X,Y,Z); }

Preferred method of implementing conditional debug 'dump' output.

Parameters

L	Debug level (bitmask of DebugLevel enumeration)
X	A const pointer to a 0-byte terminated string containing the 'title' string
Y	A const void pointer to the data to be dumped
Z	An 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 385 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

L	Debug 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 364 of file debug_helper.h.

◆ WB_DEFINE_PROFILE

#define WB_DEFINE_PROFILE ( __name ) static int __wb_profile_##__name = -1

Declaration of a profiling variable and description.

Parameters

__name The variable's unique name suffix for profiling purposes. This will be used to construct an actual variable name.

This will create a static variable based on '__name' and pre-assign it to an invalid value.

Definition at line 414 of file debug_helper.h.

◆ WB_ENABLE_PROFILE

#define WB_ENABLE_PROFILE	(	__name,
		__desc
	)

Value:

{ if(__wb_profile_##__name < 0) \
                                           __wb_profile_##__name = WBRegisterProfileVar(__FILE__, __LINE__, __FUNCTION__, \
                                                                                        WB_STRINGIZE(__name), __desc); }

Declaration of a profiling variable and description.

Parameters

__name	The variable's unique name suffix for profiling purposes. This will be used to construct an actual variable name.
__desc	The variable's description as a text string.

This will register a static variable based on '__name' with the profiling system, along with the description. Debug builds only.

NOTE: if this is unique to a particular function, you should include the function name as part of '__desc'

Definition at line 426 of file debug_helper.h.

◆ WB_ERROR_DUMP

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

Parameters

X	A const pointer to a 0-byte terminated string containing the 'title' string
Y	A const void pointer to the data to be dumped
Z	An unsigned integer indicating the number of bytes to display

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

Definition at line 496 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 474 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

L	Debug 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 404 of file debug_helper.h.

◆ WB_START_PROFILE

#define WB_START_PROFILE ( __name ) WBStartProfile(__wb_profile_##__name)

Start profiling using the specified profile variable.

Parameters

__name The variable's unique name suffix for profiling purposes (must have been declared with WB_ENABLE_PROFILE(), above)

Use this macro to begin profiling a portion of a function. you must call 'WB_STOP_PROFILE()' for the counters to be meaningful.

Definition at line 439 of file debug_helper.h.

◆ WB_STOP_PROFILE

#define WB_STOP_PROFILE ( __name ) WBStopProfile(__wb_profile_##__name)

Stop profiling using the specified profile variable.

Parameters

__name The variable's unique name suffix for profiling purposes (must have been declared with WB_ENABLE_PROFILE(), above)

Use this macro to stop profiling a portion of a function. you must have called 'WB_START_PROFILE()' for the counters to be meaningful.

Definition at line 450 of file debug_helper.h.

◆ WB_WARN_DUMP

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

Parameters

X	A const pointer to a 0-byte terminated string containing the 'title' string
Y	A const void pointer to the data to be dumped
Z	An unsigned integer indicating the number of bytes to display

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

Definition at line 485 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 467 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 28 bits (lower DWORD) identify the subsystem filters (no bits set for ALL)

End-users may use any of the bits in the upper DWORD as the debug level is an 'unsigned long long' (64-bit) value. However, enumerations only work for 32-bit integers with 32-bit compilers, so there are no definitions for those bits here.

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

Definition at line 93 of file debug_helper.h.

Function Documentation

◆ WBCheckDebugLevel()

static __inline__ int WBCheckDebugLevel ( WB_UINT64 dwLevel )

static

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

Parameters

dwLevel A 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 300 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

szTitle	The title of the debug dump
pData	A pointer to the data to be dumped
cbData	the 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 802 of file platform_helper.c.

◆ WBDebugDumpColormap()

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

Dump XStandardColormap members for debugging.

Parameters

szTitle	A const pointer to a string, to be displayed as the title for debug output
pMap	A const pointer to an XStandardColormap structure.

Call this to do a debug dump of XStandardColormap information

Header File: pixmap_helper.h

Definition at line 2188 of file pixmap_helper.c.

◆ WBDebugDumpEvent()

void WBDebugDumpEvent ( XEvent * pEvent )

dumps the contents of an XEvent

Parameters

pEvent an 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 9253 of file window_helper.c.

◆ WBDebugDumpGC()

void WBDebugDumpGC	(	Display *	pDisplay,
		WBGC	hGC
	)

dumps a GC's settings

Parameters

pDisplay	A pointer to the display
hGC	The 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 9206 of file window_helper.c.

◆ WBDebugDumpRegion()

void WBDebugDumpRegion	(	Region	hRgn,
		int	bRotate
	)

dumps contents of a region

Parameters

hRgn	The region to dump
bRotate	True 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 9322 of file window_helper.c.

◆ WBDebugDumpXColor()

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

Dump XColor members for debugging.

Parameters

szTitle	A const pointer to a string, to be displayed as the title for debug output
pColor	A const pointer to an XColor structure.

Call this to do a debug dump of XColor information

Header File: pixmap_helper.h

Definition at line 2208 of file pixmap_helper.c.

◆ WBDebugPrint()

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

conditional debug message output

Parameters

pFmt	A 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

pSpec An 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 2212 of file font_legacy.c.

◆ WBGetDebugLevel()

static __inline__ WB_UINT64 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 185 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 747 of file platform_helper.c.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ WB_DEBUG_DUMP

◆ WB_DEBUG_PRINT

◆ WB_DEFINE_PROFILE

◆ WB_ENABLE_PROFILE

◆ WB_ERROR_DUMP

◆ WB_ERROR_PRINT

◆ WB_IF_DEBUG_LEVEL

◆ WB_START_PROFILE

◆ WB_STOP_PROFILE

◆ WB_WARN_DUMP

◆ WB_WARN_PRINT

Enumeration Type Documentation

◆ DebugLevel

Function Documentation

◆ WBCheckDebugLevel()

◆ WBDebugDump()

◆ WBDebugDumpColormap()

◆ WBDebugDumpEvent()

◆ WBDebugDumpGC()

◆ WBDebugDumpRegion()

◆ WBDebugDumpXColor()

◆ WBDebugPrint()

◆ WBDumpFontInfo()

◆ WBGetDebugLevel()

◆ WBSetDebugLevel()