X11 Work Bench Toolkit  1.0
Dialog (Frame) Windows

Data Structures

struct  __DIALOG_WINDOW__
 DIALOG_WINDOW structure (internal), an extension of WBDialogWindow. More...
 
struct  __WB_DIALOG_ENTRY__
 Structure identifying one of the controls that appears on a dialog window. More...
 
struct  __WB_DIALOG_WINDOW__
 Structure identifying a dialog (frame) window. More...
 

Typedefs

typedef struct __DIALOG_WINDOW__ DIALOG_WINDOW
 DIALOG_WINDOW structure (internal), an extension of WBDialogWindow. More...
 
typedef struct __WB_DIALOG_ENTRY__ WBDialogEntry
 Structure identifying one of the controls that appears on a dialog window. More...
 
typedef struct __WB_DIALOG_WINDOW__ WBDialogWindow
 Structure identifying a dialog (frame) window. More...
 

Enumerations

enum  WBDialogWindowFlags {
  WBDialogWindow_APP_WINDOW = 1, WBDialogWindow_VISIBLE = 2, WBDialogWindow_DOMODAL = 4, WBDialogWindow_CENTERMOUSE = 8,
  WBDialogWindow_HRESIZE = 0x100, WBDialogWindow_VRESIZE = 0x200, WBDialogWindow_MAX = 0x80000000L
}
 enumeration for the iFlags member of WBDialogWindow More...
 
enum  WBDialogEntryFlags {
  WBDialogEntry_VISIBLE = 0x1, WBDialogEntry_EDIT = 0x2, WBDialogEntry_MULTILINE = 0x4, WBDialogEntry_ALLCHARS = 0x8,
  WBDialogEntry_HResize = 0x00040000, WBDialogEntry_VResize = 0x00080000, WBDialogEntry_ResizeMask = 0x000c0000, WBDialogEntry_VAlignFixed = 0x00000000,
  WBDialogEntry_VAlignTop = 0x00100000, WBDialogEntry_VAlignBottom = 0x00200000, WBDialogEntry_VAlignCenter = 0x00300000, WBDialogEntry_VAlignMask = 0x00300000,
  WBDialogEntry_HAlignFixed = 0x00000000, WBDialogEntry_HAlignLeft = 0x00400000, WBDialogEntry_HAlignRight = 0x00800000, WBDialogEntry_HAlignCenter = 0x00c00000,
  WBDialogEntry_HAlignMask = 0x00c00000, WBDialogEntry_AlignMask = 0x00f00000, WBDialogEntry_Reserved24 = 0x01000000, WBDialogEntry_Reserved25 = 0x02000000,
  WBDialogEntry_Reserved26 = 0x04000000, WBDialogEntry_PRESSED = 0x08000000, WBDialogEntry_CAN_HAVE_FOCUS = 0x10000000, WBDialogEntry_HAS_FOCUS = 0x20000000,
  WBDialogEntry_PUSHBUTTON = 0x40000000, WBDialogEntry_DEFAULT = 0x80000000
}
 enumeration for the iFlags member of WBDialogEntry More...
 

Functions

void DLGAssignOwner (WBDialogWindow *pDlg, Window wIDOwner)
 Assign owning window to dialog. More...
 
void DLGRecalcLayout (Window wID)
 Force re-calculation of dialog window (and control) layout. More...
 
int DLGPixelHeight (WBDialogWindow *pDlg, int iHeight)
 Height of a single dialog unit (in pixels) More...
 
int DLGPixelWidth (WBDialogWindow *pDlg, int iWidth)
 Width of a single dialog unit (in pixels) More...
 
void DLGSetUserCallback (WBDialogWindow *pDLG, WBWinEvent pCallBack)
 Assign the callback function for a dialog window. More...
 
int DLGProcessHotKey (WBDialogWindow *pDLG, XEvent *pEvent)
 return non-zero if a hot-key was processed and no further processing should be done. Otherwise returns zero.
 
static __inline__ WBDialogWindowDLGGetDialogWindowStruct (Window wID)
 Returns a pointer to the dialog window's WBDialogWindow structure. More...
 
void * DLGGetDialogWindowUserData (Window wID)
 Returns a pointer to the dialog window's 'user data' assigned at create time. More...
 
void DLGDestroyDialogWindow (Window wID)
 Destroy a modeless dialog window via its window ID. More...
 
void DLGDestroyDialogWindow2 (WBDialogWindow *pDialogWindow)
 Destroy a modeless dialog window via a pointer to its WBDialogWindow structure. More...
 
Window DLGGetDialogControl (WBDialogWindow *pDialog, int iControlID)
 returns the Window ID of a member control of the dialog window using the 'control ID' More...
 
WBDialogEntryDLGGetDialogControlEntry (WBDialogWindow *pDialog, Window idControl)
 returns a pointer to the WBDialogEntry for a member control using the control's Window ID More...
 
Window DLGGetFirstDialogControl (WBDialogWindow *pDialog)
 Return the Window ID of the FIRST dialog control within the 'tab order'. More...
 
Window DLGGetNextDialogControl (WBDialogWindow *pDialog, Window idControl)
 Return the Window ID of the NEXT dialog control within the 'tab order', based on the specified control window ID. More...
 
Window DLGGetPrevDialogControl (WBDialogWindow *pDialog, Window idControl)
 Return the Window ID of the PREVIOUS dialog control within the 'tab order', based on the specified control window ID. More...
 
static __inline__ void DLGNotifyDlg (WBDialogWindow *pDLG, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify dialog window by calling the window's own callback function directly with an event. More...
 
static __inline__ void DLGNotifyDlgAsync (WBDialogWindow *pDLG, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify dialog window by posting an event that will ASYNCHRONOUSLY be sent to the dialog window's callback function. More...
 

Detailed Description

Dialog (Frame) Windows are specialized frame windows that normally execute as MODAL windows ( see WBShowModal() and WBEndModal() ).
A lot of specialized processing needs to be done for a proper dialog window, including all of the hot keys necessary to change focus and activate 'default' buttons and controls. Additionally, it is often desirable to create a dialog window 'on the fly' from a resource that can be language-dependent or content-dependent (or both). For this reason the Dialog portion of the X11 Work Bench Toolkit API supports dialog window creation from a text resource, using registered identifier names within the resource text.

Typedef Documentation

DIALOG_WINDOW structure (internal), an extension of WBDialogWindow.

typedef struct __DIALOG_WINDOW__
{
WBDialogWindow wbDLG; // WBDialogWIndow structure, required to be at the beginning
WBDialogEntry *pwContents; // WBAlloc'd array of child window/control information as
// WBDialogEntry following order of windows creation and tab order
int nContents; // size of 'pwContents' when pwContents is not NULL
int nMaxContents; // extent of 'pwContents' when pwContents is not NULL
char *szTitle; // title bar string (WBAlloc'd pointer, must WBFree on destroy)
WBWinEvent pDLGCallback; // pointer to dialog window callback function
struct __DIALOG_WINDOW__ *pNext; // internal use only, pointer to next entry in chain (linked list)

Dialog 'owner' window structure, kept internally as part of a link list. This structure keeps track of the child (control) windows and global properties. See also WB_DIALOG_PROP and WBDialogPropList.

See Also
WBDialogEntry, WBDialogWindow

Structure identifying one of the controls that appears on a dialog window.

typedef struct __WB_DIALOG_ENTRY__
{
unsigned int ulTag; // tag word DIALOG_ENTRY_TAG
Window wID; // window ID of control
Atom aClass; // control class identifier
int iID; // control unique identifier (number or atom, as appropriate, unique to dialog window)
int iFlags; // visibility, focus, etc.
int iX, // horizontal position of upper left corner of control (client-relative)
iY, // vertical position of upper left corner of control (client-relative)
iWidth, // width of control
iHeight; // height of control

Public members of the structure that identifies a dialog control. This structure identifies one of the controls that appears on a dialog window. Each control will uniquely map to one of these structures.

See Also
WBDialogWindow

Structure identifying a dialog (frame) window.

typedef struct __WB_DIALOG_WINDOW__
{
unsigned int ulTag; // tag word, always assigned to DIALOG_WINDOW_TAG
Window wID; // window ID of the dialog (frame) window
Window wIDOwner; // window ID of the dialog's OWNER (can be 'None', should be assigned for Modal dialogs)
void *pUserData; // user data that's assignable via API
int iFlags; // bitmask of attribute flags (see 'WBDialogWindowFlags' enumeration)
int iClientX, // horizontal position of upper left corner of client area, relative to the window
iClientY, // vertical position of upper left corner of client area, relative to the window
iClientWidth, // width of the dialog window's client area
iClientHeight; // height of the dialog window's client area
XColor clrFG, // foreground pixel color
clrBG, // background pixel color
clrBD; // border pixel color

This structure identifies the dialog (frame) window. The public members are documented in this file. Private members store information that is only accessible using the API functions (such as an array of WBDialogEntry structures).

See Also
WBDialogEntry

Enumeration Type Documentation

enumeration for the iFlags member of WBDialogEntry

Enumerator
WBDialogEntry_VISIBLE 

visible item

WBDialogEntry_EDIT 

user-editable text

WBDialogEntry_MULTILINE 

for edit controls, prevents trapping <ENTER>

WBDialogEntry_ALLCHARS 

prevents trapping <ESC> <ENTER> and anything else

WBDialogEntry_HResize 

dialog box flag, can be resized horizontally

WBDialogEntry_VResize 

dialog box flag, can be resized vertically

WBDialogEntry_ResizeMask 

resize mask for dialog box

WBDialogEntry_VAlignFixed 

default position re-alignment with respect to center (as a percentage, no stretching)

WBDialogEntry_VAlignTop 

resize maintains position/size with respect to top

WBDialogEntry_VAlignBottom 

resize maintains position/size with respect to bottom

WBDialogEntry_VAlignCenter 

re-alignment with respect to center (as a percentage, stretching allowed)

WBDialogEntry_VAlignMask 

vertical alignment mask

WBDialogEntry_HAlignFixed 

default position re-alignment with respect to center (as a percentage, no stretching)

WBDialogEntry_HAlignLeft 

resize maintains position/size with respect to left

WBDialogEntry_HAlignRight 

resize maintains position/size with respect to right

WBDialogEntry_HAlignCenter 

re-alignment with respect to center (as a percentage, stretching allowed)

WBDialogEntry_HAlignMask 

horizontal alignment mask

WBDialogEntry_AlignMask 

alignment mask (both horizontal and vertical)

WBDialogEntry_Reserved24 

reserved bit 24

WBDialogEntry_Reserved25 

reserved bit 25

WBDialogEntry_Reserved26 

reserved bit 26

WBDialogEntry_PRESSED 

for pushbuttons, causes it to be drawn 'pressed'

WBDialogEntry_CAN_HAVE_FOCUS 

set when item CAN have focus.

WBDialogEntry_HAS_FOCUS 

set when item gets focus. cleared when no focus

WBDialogEntry_PUSHBUTTON 

set for 'pushbuttons' (which override 'default' for <ENTER>)

WBDialogEntry_DEFAULT 

set for "default" controls

Definition at line 274 of file dialog_window.h.

enumeration for the iFlags member of WBDialogWindow

Enumerator
WBDialogWindow_APP_WINDOW 

Application Window flag.

set this flag for an application top-level dialog window so that whenver it is destroyed the application will exit

WBDialogWindow_VISIBLE 

Visibility flag.

set this to make the window immediately visible.

See Also
WBDialogWindow_CENTERMOUSE, WBDialogWindow_DOMODAL
WBDialogWindow_DOMODAL 

Modality flag.

When this flag is set, the act of creating the dialog window will also call WBShowModal() automatically. Also implies WBDialogWindow_VISIBLE, WBDialogWindow_CENTERMOUSE

WBDialogWindow_CENTERMOUSE 

Auto-center mouse pointer.

When this flag is set, the act of creating the dialog window will center the mouse over the dialog box.
NOTE: This only works properly when WBDialogWindow_VISIBLE is ALSO set.

WBDialogWindow_HRESIZE 

Horizontal Resize flag.

When this flag is set, the dialog can be re-sized horizontally with the UI

WBDialogWindow_VRESIZE 

Vertical Resize flag.

When this flag is set, the dialog can be re-sized vertically with the UI

WBDialogWindow_MAX 

MAX flag (reserved)

Identifies the maximum value of assignable bit flags

Definition at line 226 of file dialog_window.h.

Function Documentation

void DLGAssignOwner ( WBDialogWindow pDlg,
Window  wIDOwner 
)

Assign owning window to dialog.

The 'owning' window defines the window that the dialog belongs to such that when the dialog is destroyed (and currently has focus) this window will automatically be raised and assigned the input focus. This is NOT the same as the parent window!

Header File: dialog_window.h

Definition at line 518 of file dialog_window.c.

void DLGDestroyDialogWindow ( Window  wID)

Destroy a modeless dialog window via its window ID.

Use this function to destroy a modeless dialog window using the window ID of the dialog (frame) window. This also causes the 'WBDialogWindow' structure to be destroyed. Use caution if you retained a pointer to it.

Header File: dialog_window.h

Definition at line 528 of file dialog_window.c.

void DLGDestroyDialogWindow2 ( WBDialogWindow pDialogWindow)

Destroy a modeless dialog window via a pointer to its WBDialogWindow structure.

Use this function to destroy a modeless dialog window using the WBDialogWindow for the dialog (frame) window. This also causes the 'WBDialogWindow' structure to be destroyed. Use caution if you retained a pointer to it, to avoid re-using the (now) invalid pointer.

Header File: dialog_window.h

Definition at line 533 of file dialog_window.c.

Window DLGGetDialogControl ( WBDialogWindow pDialog,
int  iControlID 
)

returns the Window ID of a member control of the dialog window using the 'control ID'

To obtain the Window ID of a member control, using the control's ID, call this function.

Header File: dialog_window.h

Definition at line 1235 of file dialog_window.c.

WBDialogEntry* DLGGetDialogControlEntry ( WBDialogWindow pDialog,
Window  idControl 
)

returns a pointer to the WBDialogEntry for a member control using the control's Window ID

This is usually the preferred method of obtaining information about a dialog control. Call this function to obtain a pointer to the WBDialogEntry for a control, passing the WBDialogWindow pointer and the window ID. The return value from DLGGetDialogControl() can be passed directly as the control's Window ID.

Header File: dialog_window.h

Definition at line 1254 of file dialog_window.c.

static __inline__ WBDialogWindow* DLGGetDialogWindowStruct ( Window  wID)
static

Returns a pointer to the dialog window's WBDialogWindow structure.

Use this function to obtain a pointer to the WBDialogWindow structure for the dialog (frame) window.

Header File: dialog_window.h

Definition at line 442 of file dialog_window.h.

void* DLGGetDialogWindowUserData ( Window  wID)

Returns a pointer to the dialog window's 'user data' assigned at create time.

Use this function to obtain a pointer to the 'user data' for the dialog (frame) window. This function returns NULL if there is no WBDialogWindow structure associated with the window, or if there is no user data assigned.

Header File: dialog_window.h

Definition at line 1223 of file dialog_window.c.

Window DLGGetFirstDialogControl ( WBDialogWindow pDialog)

Return the Window ID of the FIRST dialog control within the 'tab order'.

Each dialog window has what can be called a 'tab order' in which the FIRST control listed in the resource is the FIRST control in the tab order, the next control listed in the resource is the NEXT control, and so on. Tab order has nothing to do with the control's position within the dialog window. It is solely dependent on its order in the resource.

Header File: dialog_window.h

Definition at line 1273 of file dialog_window.c.

Window DLGGetNextDialogControl ( WBDialogWindow pDialog,
Window  idControl 
)

Return the Window ID of the NEXT dialog control within the 'tab order', based on the specified control window ID.

Each dialog window has what can be called a 'tab order' in which the FIRST control listed in the resource is the FIRST control in the tab order, the next control listed in the resource is the NEXT control, and so on. Tab order has nothing to do with the control's position within the dialog window. It is solely dependent on its order in the resource.
If the specified control ID is the LAST one, this function returns the FIRST dialog control's window ID

Header File: dialog_window.h

Definition at line 1283 of file dialog_window.c.

Window DLGGetPrevDialogControl ( WBDialogWindow pDialog,
Window  idControl 
)

Return the Window ID of the PREVIOUS dialog control within the 'tab order', based on the specified control window ID.

Each dialog window has what can be called a 'tab order' in which the FIRST control listed in the resource is the FIRST control in the tab order, the next control listed in the resource is the NEXT control, and so on. Tab order has nothing to do with the control's position within the dialog window. It is solely dependent on its order in the resource.
If the specified control ID is the FIRST one, this function returns the LAST dialog control's window ID

Header File: dialog_window.h

Definition at line 1307 of file dialog_window.c.

static __inline__ void DLGNotifyDlg ( WBDialogWindow pDLG,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify dialog window by calling the window's own callback function directly with an event.

Use this function when immediate notification is needed, and there is no possibility of a blocking call, recursion, or invalid state as a result of the event processing.

See Also
DLGNotifyDlgAsync()

Header File: dialog_window.h

Definition at line 571 of file dialog_window.h.

static __inline__ void DLGNotifyDlgAsync ( WBDialogWindow pDLG,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify dialog window by posting an event that will ASYNCHRONOUSLY be sent to the dialog window's callback function.

Use this function whenever immediate notification is NOT needed, or if there is a possibility of a blocking call, recursion, or invalid state as a result of a direct call to the window's callback function.

See Also
DLGNotifyDlg()

Header File: dialog_window.h

Definition at line 606 of file dialog_window.h.

int DLGPixelHeight ( WBDialogWindow pDlg,
int  iHeight 
)

Height of a single dialog unit (in pixels)

Return the height of a dialog unit, in pixels. Currently hard-coded to '1'

Header File: dialog_window.h

Definition at line 176 of file dialog_window.c.

int DLGPixelWidth ( WBDialogWindow pDlg,
int  iWidth 
)

Width of a single dialog unit (in pixels)

Return the width of a dialog unit, in pixels. Currently hard-coded to '1'

Header File: dialog_window.h

Definition at line 181 of file dialog_window.c.

void DLGRecalcLayout ( Window  wID)

Force re-calculation of dialog window (and control) layout.

Forcing re-calculation of the layout implies that size, position, and content information is to be re-evaluated and updated, as needed, in an implementation-specific manner.

Header File: dialog_window.h

Definition at line 1216 of file dialog_window.c.

void DLGSetUserCallback ( WBDialogWindow pDLG,
WBWinEvent  pCallBack 
)

Assign the callback function for a dialog window.

The dialog's callback function is similar to that of a regular window, except that any events that are NOT handled (function returns zero) will be processed by a special 'default handler' that deals with the specific nuances associated with dialog windows. As a result it is important to be careful when processing certain kinds of events. When in doubt, return zero anyway.
NOTE: not all events will pass through the callback. Some are handled solely by the dialog window default processing

Header File: dialog_window.h

Definition at line 581 of file dialog_window.c.