X11 Work Bench Toolkit  1.0
Application Startup and Shutdown

Functions

void CHRegisterArgs (int argc, char **argv)
 registers arguments from the command line for later use More...
 
void CHOnExit (void)
 frees resources used by Configuration 'helper' functions More...
 
const char *const * CHGetArgV (void)
 retrieves the array of arguments stored by CHRegisterArgs() More...
 
int CHGetArgC (void)
 retrieves the argument count stored by CHRegisterArgs() More...
 
void PXM_OnExit (void)
 Frees resources allocated by Pixmap utility functions. More...
 
void WBPlatformOnInit (void)
 Resource initialization on startup. More...
 
void WBPlatformOnExit (void)
 Resource 'free-up' on exit (must call) 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...
 
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...
 
int WBParseStandardArguments (int *pargc, char ***pargv, char ***penvp)
 parses standard C arguments as passed to 'main()' More...
 
void WBToolkitUsage (void)
 Displays 'usage' for toolkit options to stderr. More...
 
const char * GetStartupAppName (void)
 returns a pointer to a copy of the application name from argv[0] 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...
 

Variables

int bQuitFlag
 'Quit' Flag - you should check this periodically in your main message loop and exit whenever it is TRUE (non-zero) More...
 

Detailed Description

Functions and variables associated with application startup and shutdown

Required functions for API startup and shutdown, resource pre-allocation, and final cleanup, as well as useful utilities for argument parsing, and querying options.

Function Documentation

int CHGetArgC ( void  )

retrieves the argument count stored by CHRegisterArgs()

Returns
the 'argc' value stored by CHRegisterArgs()

Use this function to retrieve the stored 'argc' value from CHRegisterArgs()

Header File: conf_help.h

Definition at line 624 of file conf_help.c.

const char* const* CHGetArgV ( void  )

retrieves the array of arguments stored by CHRegisterArgs()

Returns
the 'argv' value stored by CHRegisterArgs()

Use this function to retrieve the stored 'argv' value from CHRegisterArgs()

Header File: conf_help.h

Definition at line 629 of file conf_help.c.

void CHOnExit ( void  )

frees resources used by Configuration 'helper' functions

call this prior to normal application exit to free resources. Called by WBExit() .

Header File: conf_help.h

Definition at line 166 of file conf_help.c.

void CHRegisterArgs ( int  argc,
char **  argv 
)

registers arguments from the command line for later use

Parameters
argcThe 'argc' as passed-in to main()
argvThe 'argv' as passed-in to main()

This function registers the arguments from 'argv' as passed in to the main() for the application, and keeps an independent record of their contents for future use by any part of the program that might have use for this kind of information.

Header File: conf_help.h

Definition at line 158 of file conf_help.c.

const char* GetStartupAppName ( void  )

returns a pointer to a copy of the application name from argv[0]

Returns
A const pointer to a zero-byte terminated string containing a copy of the application name

This function is only valid if you call WBParseStandardArguments() on startup

Header File: window_helper.h

Definition at line 1838 of file window_helper.c.

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

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

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

void PXM_OnExit ( void  )

Frees resources allocated by Pixmap utility functions.

Call this to free resources allocated by the PXM functions. Called by WBExit()

Header File: pixmap_helper.h

Definition at line 1185 of file pixmap_helper.c.

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

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

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 222 of file clipboard_helper.c.

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

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 141 of file clipboard_helper.c.

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

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

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 .

Header File: window_helper.h

Definition at line 1856 of file window_helper.c.

int WBParseStandardArguments ( int *  pargc,
char ***  pargv,
char ***  penvp 
)

parses standard C arguments as passed to 'main()'

In order to support a large number of default switches and parameters that are supported by the X11workbench Toolkit API, you should pass pointers to the parameters that were passed to 'main()' by the C startup code to this function.
Returns 0 on success, non-zero (or error code) otherwise.
The values for 'argc' (as *pargc) 'argv' (as *pargv) and 'envp' (as *penvp) will likely be modified from their original values as part of the processing. If you want to retain the original values, pass 'copies' to this function and use the copies for normal argument processing (as with 'getarg').

Header File: window_helper.h

Definition at line 1515 of file window_helper.c.

void WBPlatformOnExit ( void  )

Resource 'free-up' on exit (must call)

Call this function right before exiting the application if you have made use of any system-specific resources from 'platform_helper.h'. WBExit() does this automatically. Among other things, it will delete any temporary files that were created via WBTempFile().
It should also be safe to call this function from within a 'signal' handler.

Header File: platform_helper.h

Definition at line 156 of file platform_helper.c.

void WBPlatformOnInit ( void  )

Resource initialization on startup.

Call this function right before using any 'platform_helper' functions to initialize any global resources from 'platform_helper.h'. WBInit() does this automatically. It should only be called once.

Header File: platform_helper.h

Definition at line 111 of file platform_helper.c.

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

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

void WBToolkitUsage ( void  )

Displays 'usage' for toolkit options to stderr.

Header File: window_helper.h

Definition at line 1814 of file window_helper.c.

Variable Documentation

bQuitFlag

'Quit' Flag - you should check this periodically in your main message loop and exit whenever it is TRUE (non-zero)

Quit Flag - assign to TRUE (non-zero) when it's time to exit. This may be done asynchronously at any point in time.
Signal procs that terminate the application, as well as the main frame window's 'Destroy' handler, and any 'Exit' functions, should all set this to TRUE (non-zero) to force the application to exit.

extern int bQuitFlag;

Definition at line 133 of file window_helper.c.