X11 Work Bench Toolkit  1.0
Main Dialog API Functions and definitions

Enumerations

enum  MessageBoxEnum {
  MessageBox_Error =0, MessageBox_Warning =1, MessageBox_Info =2, MessageBox_Asterisk =3,
  MessageBox_Question =4, MessageBox_BoldQuestion =5, MessageBox_WTF =6, MessageBox_Bang =7,
  MessageBox_Triangle =8, MessageBox_FaceOfDeath =9, MessageBox_JollyRoger =10, MessageBox_ThumbsUp =11,
  MessageBox_ThumbsDown =12, MessageBox_MiddleFinger =13, MessageBox_TeddyBear =14, MessageBox_Barney =15,
  MessageBox_App =16, MessageBox_ICON_MASK = 0x1f, MessageBox_Default = 0, MessageBox_OK = 0x20,
  MessageBox_Yes = 0x40, MessageBox_No = 0x80, MessageBox_Abort = 0x100, MessageBox_Retry = 0x200,
  MessageBox_Ignore = 0x400, MessageBox_Cancel = 0x800, MessageBox_OKCancel = 0x820, MessageBox_YesNo = 0xc0,
  MessageBox_YesNoCancel = 0x8c0, MessageBox_AbortRetry = 0x500, MessageBox_AbortRetryIgnore = 0x700, MessageBox_BUTTON_MASK = 0xfe0
}
 Message Box flag enumeration. More...
 
enum  FileDialogEnum {
  FileDialog_Open = 0, FileDialog_Save = 1, FileDialog_SaveAs = 2, FileDialog_Folder = 3,
  FileDialog_MASK = 0xf, FileDialog_ReadOnly = 0x10, FileDialog_NoOverwrite = 0x20, FileDialog_NoOverwritePrompt = 0x40,
  FileDialog_NoFolderNav = 0x80, FileDialog_Simple = 0x100, FileDialog_MODIFIER_MASK = 0xff0
}
 FileDialog enumeration. More...
 

Functions

WBDialogWindowDLGCreateDialogWindow (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...
 
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...
 
#define DIALOG_WINDOW_TAG   (*((const unsigned int *)"DLGW"))
 
#define DIALOG_ENTRY_TAG   (*((const unsigned int *)"DLGE"))
 

Detailed Description

High-level dialog box functions and definitions. Normally you will use these to create dialog boxes of various types.

Macro Definition Documentation

#define DIALOG_ENTRY_TAG   (*((const unsigned int *)"DLGE"))

tag for WB_DIALOG_ENTRY structure

Definition at line 115 of file dialog_window.h.

#define DIALOG_WINDOW_TAG   (*((const unsigned int *)"DLGW"))

tag for WB_DIALOG_WINDOW structure

Definition at line 114 of file dialog_window.h.

Enumeration Type Documentation

FileDialog enumeration.

Enumeration of bit flags for DLGFileDialog()
Specify one of the 'Type Flag' bits, and any 'Modifier Bits' that apply

Enumerator
FileDialog_Open 

Type Flag - File Open Dialog.

FileDialog_Save 

Type Flag - File Save Dialog.

FileDialog_SaveAs 

Type Flag - File Save As Dialog.

FileDialog_Folder 

Type Flag - Folder Dialog.

FileDialog_MASK 

bit mask for type flag

FileDialog_ReadOnly 

Modifier Flag - Read Only.

FileDialog_NoOverwrite 

Modifier Flag - No Overwrite.

FileDialog_NoOverwritePrompt 

Modifier Flag - No 'Overwrite Prompt' if overwriting.

FileDialog_NoFolderNav 

Modifier Flag - No 'Folder Navigation'.

FileDialog_Simple 

Modifier Flag - simple 'file name input'.

FileDialog_MODIFIER_MASK 

bit mask for modifier flag

Definition at line 739 of file dialog_window.h.

Message Box flag enumeration.

Use these bit-flags and masks for calls to DLGMessageBox()
You should 'or' one or more of the 'Button Bits' constants with one of the 'Icon' constants.

Legal combinations of 'or'd button bits include only the following:

  • MessageBox_OKCancel : MessageBox_OK | MessageBox_Cancel
  • MessageBox_YesNo : MessageBox_Yes | MessageBox_No
  • MessageBox_YesNoCancel : MessageBox_Yes | MessageBox_No | MessageBox_Cancel
  • MessageBox_AbortRetry : MessageBox_Abort | MessageBox_Retry
  • MessageBox_AbortRetryIgnore : MessageBox_Abort | MessageBox_Retry | MessageBox_Ignore
Enumerator
MessageBox_Error 

Icon - red stop sign.

MessageBox_Warning 

Icon - exclamation point on yellow triangle.

MessageBox_Info 

Icon - green circle.

MessageBox_Asterisk 

Icon - white asterisk on blue circle.

MessageBox_Question 

Icon - white question mark in green triangle.

MessageBox_BoldQuestion 

Icon - black question mark in yellow triangle.

MessageBox_WTF 

Icon - multiple question marks in red triangle.

MessageBox_Bang 

Icon - yellow circle with white exclamation point.

MessageBox_Triangle 

Icon - yellow triangle (nothing else)

MessageBox_FaceOfDeath 

Icon - white fright mask on black circle.

MessageBox_JollyRoger 

Icon - white skull and crossbones on black square.

MessageBox_ThumbsUp 

Icon - white thumb up on green square.

MessageBox_ThumbsDown 

Icon - white thumb down on red square.

MessageBox_MiddleFinger 

Icon - white 'middle finger' on red triangle.

MessageBox_TeddyBear 

Icon - brown and tan teddy bear on grey circle.

MessageBox_Barney 

Icon - purple T-Rex head on white circle (more like mozilla)

MessageBox_App 

Icon - application icon (from icon_app.xpm)

MessageBox_ICON_MASK 

mask for icon bits

MessageBox_Default 

Button Bits - default button (currently 'OK')

MessageBox_OK 

Button Bits - OK button.

MessageBox_Yes 

Button Bits - Yes button.

MessageBox_No 

Button Bits - No button.

MessageBox_Abort 

Button Bits - Abort button.

MessageBox_Retry 

Button Bits - Retry button.

MessageBox_Ignore 

Button Bits - Ignore button.

MessageBox_Cancel 

Button Bits - Cancel button.

MessageBox_OKCancel 

Button Bits - OK button plus Cancel button.

MessageBox_YesNo 

Button Bits - Yes button plus No button.

MessageBox_YesNoCancel 

Button Bits - Yes button plus No button and Cancel button.

MessageBox_AbortRetry 

Button Bits - Abort button plus Retry button.

MessageBox_AbortRetryIgnore 

Button Bits - Abort button plus Retry button and Ignore button.

MessageBox_BUTTON_MASK 

mask for button bits

Definition at line 649 of file dialog_window.h.

Function Documentation

WBDialogWindow* DLGCreateDialogWindow ( 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
szTitlePointer to a null-byte terminated string containing the title
szDialogResourcePointer to a null-byte terminated string containing the dialog resource
iXScreen X coordinate of upper left corner of dialog window (-1 for default)
iYScreen Y coordinate of upper left corner of dialog window (-1 for default)
iWidthdesired width of dialog window (-1 for default)
iHeightdesired height of dialog window (-1 for default)
pUserCallbackThe dialog window's callback function - see WBWinEvent
iFlagsVarious creation flags, see WBDialogWindowFlags
pUserDataA '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 249 of file dialog_window.c.

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
iTypeSee the MessageBoxEnum enumeration for a list of possible values
wIDOwnerThe owner's Window ID (or None)
szDefPathA null-byte terminated string containing the default path name (may be NULL for current directory)
szDefNameA null-byte terminated string contianing the default file name (may be NULL, no path specifiers allowed)
szExtAndDescListInformation 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 962 of file dialog_impl.c.

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
wIDOwnerOwner Window ID (or None)
szTitleA null-byte terminated string containing the title, to be displayed in the window manager's title area
szPromptA null-byte terminated string that is to be displayed in a message area on the dialog window
szDefaultA null-byte terminated string containing the default value. May be NULL
iWidthThe specified width of the dialog window, or -1 for default
iMaxCharThe 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 558 of file dialog_impl.c.

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
iTypeA combination of bits from the MessageBoxEnum enumeration
wIDOwnerThe Window ID of the owner (can be 'None')
szTitleA null-byte terminated string containing the title, to be displayed in the window manager's title area
szMessageA 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.

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
aXPMa pointer to an XPM array (as created by utilities like 'gimp').
szCopyrighta zero-byte terminated string containing the copyright information
clrTexta 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 1063 of file dialog_impl.c.