X11workbench 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...
 
int WBMain (int argc, char *argv[], char *envp[])
 Startup function, equivalent to 'main()' - provided for convenience. More...
 
void WBUsage (void)
 Optional startup function, sends 'usage' (help) info to stderr - application-defined function. 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...
 
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...
 
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

◆ CHGetArgC()

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 630 of file conf_help.c.

◆ CHGetArgV()

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 635 of file conf_help.c.

◆ CHOnExit()

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.

◆ CHRegisterArgs()

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.

◆ GetStartupAppName()

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

Definition at line 729 of file platform_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.

◆ PXM_OnExit()

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 133 of file pixmap_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 743 of file window_helper.h.

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

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

◆ WBMain()

int WBMain ( int  argc,
char *  argv[],
char *  envp[] 
)

Startup function, equivalent to 'main()' - provided for convenience.

Parameters
argcAn integer that indicates the number of elements in 'argv'. On exit, it is updated based on the arguments that were parsed.
argvAn array of char *, the list of arguments passed as 'argv' to 'main()', minus toolkit-specific entries
envpAn array of char *, the list of arguments passed as 'envp', plus anything toolkit-specific
Returns
A non-zero value indicating the exit/return code (which only uses the low 8 bits)

Use this function in your application, in lieu of 'main()', to ensure that everything is initialized and cleaned up properly, and so that command line arguments are correctly handled. It avoids having to add a call to 'WBParseStandardArguments()' and other startup functions from within your application's 'main()'.

NOTE: Your application must either have a 'main()' or a 'WBMain'. Internally, 'main()' is declared 'weak' and simply calls 'WBMain()' with proper initialization and termination. If you want to process this yourself, use 'main()' instead.

Header File: platform_helper.h

/sa WBParseStandardArguments() WBPlatformOnInit() WBPlatformOnExit()

Definition at line 164 of file X11workbench.c.

◆ WBParseStandardArguments()

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

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

Parameters
pargcA pointer to an integer, containing 'argc'. On exit, it is updated based on the arguments that were parsed.
pargvA pointer to a char **, initially the list of arguments passed as 'argv'. On exit, the char ** value may change; if it does, it will need to be free'd using WBFree()
penvpA pointer to a char **, initially the list of arguments passed as 'envp'. May be NULL. On exit, the char ** value may change; if it does, it will need to be free'd using WBFree()
Returns
A negative value if an error occurred, a positive value if the application should exit, and a zero value if the arguments were parsed correctly.

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, before processing the arguments and environment strings with your own application.
The function will parse the parameters and environment, and then returns 0 on success, a negative value on error, and a positive value (indicating 'close the application') 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, using pointers that were allocated via WBAlloc(). If you want to retain the original values, make copies of the 'argc', 'argv', and 'envp' parameters, and then pass the address of the 'copies' to this function. Then, use the copies (which may be WBAlloc()'d) for normal argument processing (as with 'getarg').
NOTE: you can compare the copy to the original pointer values for argv and envp to determine whether they were 'WBAlloc()'d in order to free them later. However, when an application exits its memory is typically free'd automatically, so the benefit of doing this is small.

For consistency, a negative return should display a 'usage()' banner (see WBToolkitUsage(), below). Any non-zero return value should cause the application to close.

Header File: platform_helper.h

Definition at line 271 of file platform_helper.c.

◆ WBPlatformOnExit()

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, prior to '__exit()'.

Header File: platform_helper.h

Definition at line 233 of file platform_helper.c.

◆ WBPlatformOnInit()

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. It's ok to call it before calling WBInit(), however.
Header File: platform_helper.h

Definition at line 188 of file platform_helper.c.

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

◆ WBToolkitUsage()

void WBToolkitUsage ( void  )

Displays 'usage' for toolkit options to stderr.

Header File: platform_helper.h

Definition at line 700 of file platform_helper.c.

◆ WBUsage()

void WBUsage ( void  )

Optional startup function, sends 'usage' (help) info to stderr - application-defined function.

Define this function in your application (automatically called by internally defined 'main()' when 'WBParseStandardArguments()' returns an error) to display a customized 'help' message that documents the command line options and/or other 'help' information for the application.

The default (weak) version simply calls WBToolkitUsage()

Header File: platform_helper.h

/sa WBToolkitUsage()

Definition at line 181 of file platform_helper.c.

Variable Documentation

◆ bQuitFlag

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 106 of file platform_helper.c.