X11workbench Toolkit  1.0
Dialog (Frame) Windows

Modules

 Definitions
 
 Structures
 

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

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

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

◆ WBDialogEntry

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

◆ 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

Function Documentation

◆ DLGAssignOwner()

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 523 of file dialog_window.c.

◆ DLGDestroyDialogWindow()

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 533 of file dialog_window.c.

◆ DLGDestroyDialogWindow2()

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 538 of file dialog_window.c.

◆ DLGGetDialogControl()

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 1350 of file dialog_window.c.

◆ DLGGetDialogControlEntry()

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 1369 of file dialog_window.c.

◆ DLGGetDialogWindowStruct()

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 509 of file dialog_window.h.

◆ DLGGetDialogWindowUserData()

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 1338 of file dialog_window.c.

◆ DLGGetFirstDialogControl()

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 1388 of file dialog_window.c.

◆ DLGGetNextDialogControl()

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 1398 of file dialog_window.c.

◆ DLGGetPrevDialogControl()

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 1422 of file dialog_window.c.

◆ DLGNotifyDlg()

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 638 of file dialog_window.h.

◆ DLGNotifyDlgAsync()

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 673 of file dialog_window.h.

◆ DLGPixelHeight()

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 178 of file dialog_window.c.

◆ DLGPixelWidth()

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 183 of file dialog_window.c.

◆ DLGRecalcLayout()

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 1331 of file dialog_window.c.

◆ DLGSetUserCallback()

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 586 of file dialog_window.c.