X11workbench Toolkit
1.0
|
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... | |
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.
int CHGetArgC | ( | void | ) |
retrieves the argument count 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.
const char* const* CHGetArgV | ( | void | ) |
retrieves the array of arguments 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.
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
argc | The 'argc' as passed-in to main() |
argv | The '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]
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.
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.
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.
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.
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.
|
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.
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.
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.
Display* WBInit | ( | const char * | szDisplayName | ) |
initializes default objects for the specified Display (required)
szDisplayName | A null-byte terminated ASCII string containing the DISPLAY name, or NULL NULL values causes the display to initialize using GetStartupDisplayName() |
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.
int WBInitClipboardSystem | ( | Display * | pDisplay, |
const char * | szDisplayName | ||
) |
initializes clipboard sub-system
pDisplay | The 'Display' associated with this clipboard (reserved, must match 'WBInitDisplay' call or be NULL) |
szDisplayName | A null-byte terminated ASCII string containing the DISPLAY name, or NULL NULL values causes the display to initialize using GetStartupDisplayName() |
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.
int WBInitDisplay | ( | Display * | pDisplay | ) |
initializes default objects for the specified Display
pDisplay | A pointer to an open Display object, to become the default display for the X11 WorkBench Toolkit. |
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.
void WBInitSizeHints | ( | XSizeHints * | pSH, |
Display * | pDisplay, | ||
int | iMinHeight, | ||
int | iMinWidth | ||
) |
initializes the XSizeHints structure with standard attributes
pSH | Pointer to the XSizeHints structure |
pDisplay | Pointer to the Display (NULL for default) |
iMinHeight | Minimum height of the window |
iMinWidth | Minimum 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.
void WBInitWindowAttributes | ( | XSetWindowAttributes * | pXSWA, |
unsigned long | lBorderPixel, | ||
unsigned long | lBackgroundPixel, | ||
Colormap | clrMap, | ||
int | iBitGravity | ||
) |
initializes the XSetWIndowAttributes structure with minimal attributes
pXSWA | A pointer to the (un-initialized) XSetWindowAttributes structure |
lBorderPixel | The color value for the border pixel |
lBackgroundPixel | The color value for the background pixel |
clrMap | The colormap, typically the value returned by WBDefaultColormap() |
iBitGravity | The '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.
int WBMain | ( | int | argc, |
char * | argv[], | ||
char * | envp[] | ||
) |
Startup function, equivalent to 'main()' - provided for convenience.
argc | An integer that indicates the number of elements in 'argv'. On exit, it is updated based on the arguments that were parsed. |
argv | An array of char *, the list of arguments passed as 'argv' to 'main()', minus toolkit-specific entries |
envp | An array of char *, the list of arguments passed as 'envp', plus anything toolkit-specific |
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.
int WBParseStandardArguments | ( | int * | pargc, |
char *** | pargv, | ||
char *** | penvp | ||
) |
parses standard C arguments as passed to 'main()'
pargc | A pointer to an integer, containing 'argc'. On exit, it is updated based on the arguments that were parsed. |
pargv | A 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() |
penvp | A 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() |
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.
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.
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.
void WBThreadFreeDisplay | ( | Display * | pThreadDisplay | ) |
un-initializes a Display for a thread that was allocated by WBThreadInitDisplay()
pThreadDisplay | a 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.
Display* WBThreadInitDisplay | ( | void | ) |
initializes default Display for a thread (must call WBInit() first)
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.
void WBToolkitUsage | ( | void | ) |
Displays 'usage' for toolkit options to stderr.
Header File: platform_helper.h
Definition at line 700 of file platform_helper.c.
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.
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.
Definition at line 106 of file platform_helper.c.