Functions
WBDialogWindow *	DLGCreateDialogWindow (Window wIDOwner, const char szTitle, const char szDialogResource, int iX, int iY, int iWidth, int iHeight, WBWinEvent pUserCallback, int iFlags, void *pUserData)
	create a dialog window using a text resource More...

int	DLGMessageBox (int iType, Window wIDOwner, const char szTitle, const char szMessage)
	Display a modal 'message box' dialog window with a specific title, message, and button combination. More...

char *	DLGInputBox (Window wIDOwner, const char szTitle, const char szPrompt, const char *szDefault, int iWidth, int iMaxChar)
	Displays a special purpose dialog window that retrieves a character string as input. More...

char *	DLGFileDialog (int iType, Window wIDOwner, const char szDefPath, const char szDefName, const char *szExtAndDescList)
	Display a modal File Dialog window, returning a WBAlloc'd pointer to a null-byte terminated string containing a fully qualified file or path name. More...

int	DLGColorDialog (Window wIDOwner, XStandardColormap pColorMap, XColor pColor)
	Display a modal Color Dialog window, returning the selected color in the XColor structure pointed to by 'pColor'. More...

WB_FONT	DLGFontDialog (Display *pDisplay, Window wIDOwner, WB_FONTC pDefault)
	Display a modal Font Dialog window, returning the selected font in the XColor structure pointed to by 'pColor'. More...

void	DLGSplashScreen (char aXPM[], const char szCopyright, unsigned long clrText)
	Display a splash screen for 5 seconds (with animation and copyright string), and then return. More...

Detailed Description

API Functions for the High Level Dialog Box API

Function Documentation

◆ DLGColorDialog()

int DLGColorDialog	(	Window	wIDOwner,
		XStandardColormap *	pColorMap,
		XColor *	pColor
	)

Display a modal Color Dialog window, returning the selected color in the XColor structure pointed to by 'pColor'.

Parameters

wIDOwner	The owner's Window ID (or None)
pColorMap	The XStandardColormap to use, or NULL to use the default colormap
pColor	A pointer to the XColor structure into which the chosen color is returned.

Returns: A value of -1 on cancel/error, a 0 if the color was not changed, or 1 if it was changed

Use this function to display a 'color choice' dialog box, and return the chosen color within an 'XColor' structure. Before calling this function, you need to assign a valid pixel value to the structure pointed to by 'pColor'. Typically it will be a color reference that was loaded using one of the applicable methods (such as 'XParseColor()').

This function does not call XAllocColor(), nor will it free the old color with XFreeColors() if it is changed. The responsibility for allocating and freeing colors lies with the caller.

Definition at line 1808 of file dialog_impl.c.

◆ DLGCreateDialogWindow()

WBDialogWindow* DLGCreateDialogWindow	(	Window	wIDOwner,
		const char *	szTitle,
		const char *	szDialogResource,
		int	iX,
		int	iY,
		int	iWidth,
		int	iHeight,
		WBWinEvent	pUserCallback,
		int	iFlags,
		void *	pUserData
	)

create a dialog window using a text resource

Returns: Pointer to WBDialogWindow structure that identifies the dialog (frame) window

Parameters

WIDOwner	A Window that owns the dialog box; Use 'None' to make it a stand-alone window
szTitle	Pointer to a null-byte terminated string containing the title
szDialogResource	Pointer to a null-byte terminated string containing the dialog resource
iX	Screen X coordinate of upper left corner of dialog window (-1 for default)
iY	Screen Y coordinate of upper left corner of dialog window (-1 for default)
iWidth	desired width of dialog window (-1 for default)
iHeight	desired height of dialog window (-1 for default)
pUserCallback	The dialog window's callback function - see WBWinEvent
iFlags	Various creation flags, see WBDialogWindowFlags
pUserData	A 'user data' pointer that is to be associated with the dialog window

Returns: A pointer to a WBDialogWindow structure for the newly created window

Use this high-level function to create a dialog window with a text resource. The text resource contains information about constructing the dialog window. Standard symbol names are supported, along with numeric symbols.

Within a specified object (control or dialog) custom properties are passed to the control (reserved) upon creation. All properties are specified using a single name, optionally followed by a value with a ':' separating the name and value. Properties and Values with embedded white space must be quoted.

A typical dialog window resource might look as follows:

BEGIN_DIALOG FONT:Variable HEIGHT:50 WIDTH:200 TITLE:"Sample Message Box Dialog Window"
  CONTROL:Icon ID:1000 X:2 Y:2 HEIGHT:20 WIDTH:20 VISIBLE
  CONTROL:Text ID:1001 X:24 Y:2 HEIGHT:20 WIDTH:172 VISIBLE
  CONTROL:DefPushButton ID:IDOK TITLE:OK X:80 Y:28 WIDTH:40 HEIGHT:18 VISIBLE
END_DIALOG

For more information, see Dialog Box Resources .

Header File: dialog_window.h

Definition at line 260 of file dialog_window.c.

◆ DLGFileDialog()

char* DLGFileDialog	(	int	iType,
		Window	wIDOwner,
		const char *	szDefPath,
		const char *	szDefName,
		const char *	szExtAndDescList
	)

Display a modal File Dialog window, returning a WBAlloc'd pointer to a null-byte terminated string containing a fully qualified file or path name.

Parameters

iType	See the FileDialogEnum enumeration for a list of possible values
wIDOwner	The owner's Window ID (or None)
szDefPath	A null-byte terminated string containing the default path name (may be NULL for current directory)
szDefName	A null-byte terminated string contianing the default file name (may be NULL, no path specifiers allowed)
szExtAndDescList	Information containing the known extensions and file types. May be NULL. See below for format.

Returns: Either a NULL on cancel/error, or a WBAlloc'd pointer to a null-byte terminated string containing a fully qualified file or path name

Use this to display an X11 Work Bench Toolkit custom File Dialog based on the specified parameters. These file dialogs have been intionally tweeked for better UI performance than other file dialogs.
When specifying the 'szExtAndDescList' parameter, point it to a string similar to the following:

static const char szExtAndDescList[]=
  "*.txt\tText Files\n"
  "*.doc\tDocument Files\n"
  "*.sh\tShell Script Files\n"
  "*.*\tOther Files\n";

This describes 3 file types with extensions '.txt', '.doc', and '.sh' with a 4th file type of 'other files' that encompasses everything else. Simple pattern matching is applied to each file name for the selected pattern.

NOTE: non-NULL return values must be free'd by the caller using WBFree()

Header File: dialog_window.h

Definition at line 957 of file dialog_impl.c.

◆ DLGFontDialog()

WB_FONT DLGFontDialog	(	Display *	pDisplay,
		Window	wIDOwner,
		WB_FONTC	pDefault
	)

Display a modal Font Dialog window, returning the selected font in the XColor structure pointed to by 'pColor'.

Parameters

pDisplay	The Display pointer for which to query font information (NULL implies default display)
wIDOwner	The owner's Window ID (or None)
pDefault	A default WB_FONTC that specifies the initial font to be displayed. 'None' causes the dialog handler to choose an apropriate font set, most likely a system default.

Returns: A valid WB_FONT on OK, or 'None' on cancel/error. The result must be free'd using XFreeFontSet()

Use this function to display a 'font choice' dialog box, that will allow the user to chose the font face, size, weight, and other characteristics from a list of available fonts.

The returned value (if not None) will need to be free'd using XFreeFontSet()

Definition at line 1935 of file dialog_impl.c.

◆ DLGInputBox()

char* DLGInputBox	(	Window	wIDOwner,
		const char *	szTitle,
		const char *	szPrompt,
		const char *	szDefault,
		int	iWidth,
		int	iMaxChar
	)

Displays a special purpose dialog window that retrieves a character string as input.

Parameters

wIDOwner	Owner Window ID (or None)
szTitle	A null-byte terminated string containing the title, to be displayed in the window manager's title area
szPrompt	A null-byte terminated string that is to be displayed in a message area on the dialog window
szDefault	A null-byte terminated string containing the default value. May be NULL
iWidth	The specified width of the dialog window, or -1 for default
iMaxChar	The maximum number of characters in the input string

Returns: A 'WBAlloc'd memory block containing a null-byte terminated input string, or NULL on cancel/error

Use this function to display an 'Input' box, and return back the text in an allocated buffer.

NOTE: non-NULL return values must be free'd by the caller using WBFree()

Header File: dialog_window.h

Definition at line 541 of file dialog_impl.c.

◆ DLGMessageBox()

int DLGMessageBox	(	int	iType,
		Window	wIDOwner,
		const char *	szTitle,
		const char *	szMessage
	)

Display a modal 'message box' dialog window with a specific title, message, and button combination.

Returns: The Control ID of the button that was pressed, or -1 (equivalent to 'IDCANCEL') on error

Parameters

iType	A combination of bits from the MessageBoxEnum enumeration
wIDOwner	The Window ID of the owner (can be 'None')
szTitle	A null-byte terminated string containing the title, to be displayed in the window manager's title area
szMessage	A null-byte terminated string that is to be displayed in a message area on the dialog window

Use this function to display a simple modal 'message box' dialog window, and return the button that was pressed for further processing.

Header File: dialog_window.h

Definition at line 231 of file dialog_impl.c.

◆ DLGSplashScreen()

void DLGSplashScreen	(	char *	aXPM[],
		const char *	szCopyright,
		unsigned long	clrText
	)

Display a splash screen for 5 seconds (with animation and copyright string), and then return.

Parameters

aXPM	a pointer to an XPM array (as created by utilities like 'gimp').
szCopyright	a zero-byte terminated string containing the copyright information
clrText	a pixel color value for the copyright text

This function will create an animated splash screen based on the dimensions of the pixmap passed to it, animating the pixmap with a 'diagonal gleam' from upper left to lower right, and draw the copyright string onto the lower 1/3 of the pixmap, vertically centered.

The copyright string can be multi-line. Care should be taken that it is not too wide for the display or the results of horizontally and vertically centering the string in the lower half may be unpredictable.

Header File: dialog_window.h

Definition at line 1977 of file dialog_impl.c.