X11workbench Toolkit  1.0
Dialog Box Controls

Modules

 'Standard Control Name' Atoms
 
 Notification Atoms
 
 Control Window Properties
 
 Definitions
 
 Structures
 
 Data Types
 

Functions

void WBDialogControlsInit (void)
 Initialization function for dialog controls. More...
 
WBDialogControlWBDialogControlCreate (Atom aClass, WBDialogWindow *pOwner, WBDialogEntry *pDialogEntry, int iX, int iY, int iWidth, int iHeight, const char *szTitle, const char *szPropertyList)
 Create a dialog control window. More...
 
void DLGRegisterControlCallback (WBDialogControl *pDialogControl, const char *szClassName, WBWinEvent pCallback)
 Register the dialog control's callback function and class name. More...
 
int WBDialogControlSetDialogProp (WBDialogControl *pCtrl, WB_DIALOG_PROP *pPropVal)
 Low-level dialog control property assignment. More...
 
void WBDialogControlDelDialogProp (WBDialogControl *pCtrl, Atom aProp)
 Low-level dialog control property removal. More...
 
const WB_DIALOG_PROPWBDialogControlGetDialogProp (WBDialogControl *pCtrl, Atom aProp)
 Low-level dialog control property retrieval. More...
 
static __inline__ const WBDialogPropListWBDialogControlGetPropList (WBDialogControl *pCtrl)
 Low-level dialog control property list retrieval. More...
 
int WBDialogControlSetPropList (WBDialogControl *pCtrl, const char *szPropList)
 Mid-level dialog control property list assignment. More...
 
int WBDialogControlSetProperty (WBDialogControl *pCtrl, Atom aPropName, const char *szPropVal)
 Mid-level dialog control property assignment (character string) More...
 
void WBDialogControlSetProperty2 (WBDialogControl *pCtrl, Atom aPropName, void *szPropVal)
 Mid-level dialog control property list assignment (generic pointer) More...
 
const char * WBDialogControlGetProperty (WBDialogControl *pCtrl, Atom aPropName)
 Mid-level dialog control property retrieval (character string) More...
 
void * WBDialogControlGetProperty2 (WBDialogControl *pCtrl, Atom aPropName)
 Mid-level dialog control property list retrieval (generic pointer) More...
 
static __inline__ WBDialogControlDLGGetDialogControlStruct (Window wID)
 Returns a pointer to the WBDialogControl structure for a dialog control with validation. May return NULL. More...
 
static __inline__ WBDialogControlWBGetDialogEntryControlStruct (WBDialogWindow *pDialog, int iControlID)
 Returns a pointer to the WBDialogControl structure for a dialog control based on its ID and containing Dialog Window. May return NULL. More...
 
const char * WBDialogControlGetCaption (WBDialogControl *pCtrl)
 Obtain a pointer to the assigned text for the 'CAPTION' property of a dialog control. More...
 
void WBDialogControlSetCaption (WBDialogControl *pCtrl, const char *szCaption)
 Assign text to the 'CAPTION' property of a dialog control. More...
 
static __inline__ int WBDialogControlGetCaptionInt (WBDialogControl *pCtrl)
 Returns an integer from the text of the 'CAPTION' property of a dialog control. More...
 
static __inline__ void WBDialogControlSetCaptionInt (WBDialogControl *pCtrl, int iValue, const char *szFormat)
 Assign an integer as text to the 'CAPTION' property of a dialog control. More...
 
static __inline__ long WBDialogControlGetCaptionLong (WBDialogControl *pCtrl)
 Returns a long integer from the text of the 'CAPTION' property of a dialog control. More...
 
static __inline__ void WBDialogControlSetCaptionLong (WBDialogControl *pCtrl, long lValue, const char *szFormat)
 Assign a long integer as text to the 'CAPTION' property of a dialog control. More...
 
void WBDialogControlSetPixmap (WBDialogControl *pCtrl, Pixmap pixmap)
 Assign the PIXMAP (image) property for a control. More...
 
Pixmap WBDialogControlGetPixmap (WBDialogControl *pCtrl)
 Obtain the assigned PIXMAP (image) property for a control. More...
 
void WBDialogControlSetIconPixmap (WBDialogControl *pCtrl, Pixmap pixmap, Pixmap pixmap2)
 Assign the ICON (image) property for a control, which consists of 2 pixmaps. More...
 
Pixmap WBDialogControlGetIconPixmap (WBDialogControl *pCtrl, Pixmap *pPixmap2)
 Obtain the assigned ICON (image) property for a control, which consists of 2 pixmaps. More...
 
void WBDialogControlSetCheck (WBDialogControl *pCtrl, int iCheck)
 Assign the TEXT property for a control, which is different from the CAPTION or Title. More...
 
int WBDialogControlGetCheck (WBDialogControl *pCtrl)
 Retrieve the 'CHECKED' property from a dialog control. Returns '0' (un-checked) if not applicable. More...
 
static __inline__ void WBDialogControlSetText (WBDialogControl *pCtrl, const char *szText)
 Assign the TEXT property for a control, which is different from the CAPTION or Title. More...
 
static __inline__ const char * WBDialogControlGetText (WBDialogControl *pCtrl)
 Obtain the assigned TEXT property for a control, which is different from the CAPTION or Title. More...
 
static __inline__ WBDialogControlDLGGetDialogControlStructFromID (WBDialogWindow *pDialog, int iControlID)
 Returns a pointer to the WBDialogControl structure for a dialog control with validation. May return NULL. More...
 
static __inline__ void DLGSetControlCaption (WBDialogWindow *pDialog, int iControlID, const char *szCaption)
 Convenience function to assign a dialog control's caption based on its control ID. More...
 
static __inline__ const char * DLGGetControlCaption (WBDialogWindow *pDialog, int iControlID)
 Convenience function to query a dialog control's caption based on its control ID. More...
 
static __inline__ void DLGSetControlText (WBDialogWindow *pDialog, int iControlID, const char *szText)
 Convenience function to assign a dialog control's TEXT based on its control ID. More...
 
static __inline__ const char * DLGGetControlText (WBDialogWindow *pDialog, int iControlID)
 Convenience function to query a dialog control's TEXT based on its control ID. More...
 
static __inline__ int DLGSetControlProperty (WBDialogWindow *pDialog, int iControlID, Atom aPropName, const char *szPropVal)
 Convenience function to assign a text property for a dialog control based on its control ID. More...
 
static __inline__ const char * DLGGetControlProperty (WBDialogWindow *pDialog, int iControlID, Atom aPropName)
 Convenience function to query a text property for a dialog control based on its control ID. More...
 
int DLGScrollBarHandler (Window wID, WBDialogControl *pCtrl, XEvent *pEvent)
 Scroll bar event filter for dialog control callback function. Generates scroll events. More...
 
static __inline__ void DLGNotifyOwner (WBDialogControl *pDialogControl, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify Owner by calling the owner window's callback function directly with an event. More...
 
static __inline__ void DLGNotifySelf (WBDialogControl *pDialogControl, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify 'self' by calling the window's own callback function directly with an event. More...
 
static __inline__ void DLGNotifyOwnerAsync (WBDialogControl *pDialogControl, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify Owner by posting an event that will ASYNCHRONOUSLY be sent to the owner window's callback function. More...
 
static __inline__ void DLGNotifySelfAsync (WBDialogControl *pDialogControl, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
 Notify 'self' by posting an event that will ASYNCHRONOUSLY be sent to the window's callback function. More...
 
void DLGCDestroyProperties (WBDialogPropList *pPropList)
 Destroy Properties for a dialog control. More...
 
LISTINFODLGCListInfoConstructor (Window wOwner, int nMax, int nFlags, void *(*pfnAllocator)(const void *, int), void(*pfnDestructor)(void *), void(*pfnDisplay)(WBDialogControl *, void *, int, GC, WB_GEOM *, XFontSet), int(*pfnSort)(const void *, const void *))
 Create LISTINFO structure for a list type control. More...
 
void DLGCListInfoDestructor (LISTINFO *pListInfo)
 Destroy a LISTINFO structure. More...
 
void DLGCDefaultListControlDisplayProc (WBDialogControl *pList, void *pData, int iSelected, GC gc, WB_GEOM *pGeom, XFontSet fontSet)
 The default 'display proc' for displaying a list item from a LISTINFO structure. More...
 

Detailed Description

Structures and API functions used for dialog controls

Function Documentation

◆ DLGCDefaultListControlDisplayProc()

void DLGCDefaultListControlDisplayProc ( WBDialogControl pList,
void *  pData,
int  iSelected,
GC  gc,
WB_GEOM pGeom,
XFontSet  fontSet 
)

The default 'display proc' for displaying a list item from a LISTINFO structure.

Parameters
pListA pointer to a WBDialogControl structure for the list type control
pDataA pointer to the data to display
iSelectedA flag indicating whether the item has been selected (1 = selected, 0 = not selected)
gcThe graphics context for displaying the data
pGeoma WB_GEOM representing the rectangular area to draw the item in.
fontSetAn XFontSet to use when displaying the text. May be 'None', which will use the default font set for the display
Returns
void

Pass this function's address as 'pfnDisplay' when calling DLGCListInfoConstructor to get a default display handler for your listbox items.

Header File: dialog_support.h

Definition at line 1786 of file dialog_support.c.

◆ DLGCDestroyProperties()

void DLGCDestroyProperties ( WBDialogPropList pPropList)

Destroy Properties for a dialog control.

Parameters
pPropListA pointer to the property list for the dialog control
Returns
void

Call this function to destroy the property list for a dialog control

Header File: dialog_support.h

Definition at line 1071 of file dialog_support.c.

◆ DLGCListInfoConstructor()

LISTINFO* DLGCListInfoConstructor ( Window  wOwner,
int  nMax,
int  nFlags,
void *(*)(const void *, int)  pfnAllocator,
void(*)(void *)  pfnDestructor,
void(*)(WBDialogControl *, void *, int, GC, WB_GEOM *, XFontSet)  pfnDisplay,
int(*)(const void *, const void *)  pfnSort 
)

Create LISTINFO structure for a list type control.

Parameters
wOwnerthe Window ID for the owner of the LISTINFO structure
nMaxthe initial maximum size of the list (can be increased, but needs re-allocation)
nFlagsA binary flag indicating various properties, such as 'sorted'
pfnAllocatorA pointer to a constructor callback for a new list item. Use NULL for default
pfnDestructorA pointer to a destructor callback for the list item. Use NULL for default
pfnDisplayA pointer to a 'display' callback
pfnSortA pointer to a 'sort' callback. NULL uses the default
Returns
An allocated pointer to a LISTINFO structure. To free this pointer, call DLGCListINfoDestructor()

Call this function to create a LISTINFO structure associated with a list type control

See also
LISTINFO

Header File: dialog_support.h

Definition at line 1286 of file dialog_support.c.

◆ DLGCListInfoDestructor()

void DLGCListInfoDestructor ( LISTINFO pListInfo)

Destroy a LISTINFO structure.

Parameters
pListInfoA pointer to a LISTINFO structure created by DLGCListInfoConstructor()
Returns
void

Call this function to destroy the LISTINFO structure created by DLGCListInfoConstructor()

Header File: dialog_support.h

Definition at line 1325 of file dialog_support.c.

◆ DLGGetControlCaption()

static __inline__ const char* DLGGetControlCaption ( WBDialogWindow pDialog,
int  iControlID 
)
static

Convenience function to query a dialog control's caption based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control

Often it is desirable to query control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the final query. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to query for the caption.

Header File: dialog_controls.h

Definition at line 970 of file dialog_controls.h.

◆ DLGGetControlProperty()

static __inline__ const char* DLGGetControlProperty ( WBDialogWindow pDialog,
int  iControlID,
Atom  aPropName 
)
static

Convenience function to query a text property for a dialog control based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control
aPropNameAtom for the property to be assigned
Returns
A (const) pointer to the (text) data associated with the property, or NULL

Often it is desirable to query control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the final query. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to query for the text property.

See also
WBDialogControlGetProperty()

Header File: dialog_controls.h

Definition at line 1111 of file dialog_controls.h.

◆ DLGGetControlText()

static __inline__ const char* DLGGetControlText ( WBDialogWindow pDialog,
int  iControlID 
)
static

Convenience function to query a dialog control's TEXT based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control

Often it is desirable to query control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the final query. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to query for the caption.

Header File: dialog_controls.h

Definition at line 1035 of file dialog_controls.h.

◆ DLGGetDialogControlStruct()

static __inline__ WBDialogControl* DLGGetDialogControlStruct ( Window  wID)
static

Returns a pointer to the WBDialogControl structure for a dialog control with validation. May return NULL.

Parameters
wIDWindow ID of the dialog control
Returns
Pointer to WBDialogControl structure associated with the dialog control, or NULL if error or nonexistent

This is the preferred function for obtaining a pointer to the WBDialogControl structure for a dialog control window

Header File: dialog_controls.h

Definition at line 489 of file dialog_controls.h.

◆ DLGGetDialogControlStructFromID()

static __inline__ WBDialogControl* DLGGetDialogControlStructFromID ( WBDialogWindow pDialog,
int  iControlID 
)
static

Returns a pointer to the WBDialogControl structure for a dialog control with validation. May return NULL.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control
Returns
Pointer to WBDialogControl structure associated with the dialog control, or NULL if error or nonexistent

This is the preferred function for obtaining a pointer to the WBDialogControl structure for a dialog control window using the control ID and owning dialog window

Header File: dialog_controls.h

Definition at line 908 of file dialog_controls.h.

◆ DLGNotifyOwner()

static __inline__ void DLGNotifyOwner ( WBDialogControl pDialogControl,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify Owner by calling the owner window's 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
DLGNotifyOwnerAsync()

Header File: dialog_controls.h

Definition at line 1689 of file dialog_controls.h.

◆ DLGNotifyOwnerAsync()

static __inline__ void DLGNotifyOwnerAsync ( WBDialogControl pDialogControl,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify Owner by posting an event that will ASYNCHRONOUSLY be sent to the owner 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 owner window's callback function.

See also
DLGNotifyOwner()

Header File: dialog_controls.h

Definition at line 1779 of file dialog_controls.h.

◆ DLGNotifySelf()

static __inline__ void DLGNotifySelf ( WBDialogControl pDialogControl,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify 'self' 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.

Often it's useful to consilidate processing for a single type of event, such as clicking on a scrollbar or pressing an arrow key. Both send completely different event sequences to the control, but have similar processing after a certain point. If each of these generates a 'scroll' type event, and the event is sent to the control's callback, the 'scroll' functionality can be consolidated for both types of event handlers and you avoid duplication and the potential for additional 'bugginess'.

See also
DLGNotifySelfAsync()

Header File: dialog_controls.h

Definition at line 1743 of file dialog_controls.h.

◆ DLGNotifySelfAsync()

static __inline__ void DLGNotifySelfAsync ( WBDialogControl pDialogControl,
Atom  aNotify,
long  lData0,
long  lData1,
long  lData2,
long  lData3,
long  lData4 
)
static

Notify 'self' by posting an event that will ASYNCHRONOUSLY be sent to the 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.

Often it's useful to consilidate processing for a single type of event, such as clicking on a scrollbar or pressing an arrow key. Both send completely different event sequences to the control, but have similar processing after a certain point. If each of these generates a 'scroll' type event, and the event is sent to the control's callback, the 'scroll' functionality can be consolidated for both types of event handlers and you avoid duplication and the potential for additional 'bugginess'.

See also
DLGNotifySelf()

Header File: dialog_controls.h

Definition at line 1823 of file dialog_controls.h.

◆ DLGRegisterControlCallback()

void DLGRegisterControlCallback ( WBDialogControl pDialogControl,
const char *  szClassName,
WBWinEvent  pCallback 
)

Register the dialog control's callback function and class name.

Parameters
pDialogControlA pointer to the WBDialogControl structure that is associated with the dialog control window
szClassNameAn optional 'class name' string to be used for debug and tracing (may be NULL)
pCallbackThe callback function to assign to the control window

Registers the callback function for the dialog control. Also assigns the class name string pointer (for debug and trace purposes), which may be different from the default in the case of a subclassed control. This will normally be called immediately after creating the control using WBDialogControlCreate()

Header File: dialog_controls.h

Definition at line 355 of file dialog_controls.c.

◆ DLGScrollBarHandler()

int DLGScrollBarHandler ( Window  wID,
WBDialogControl pCtrl,
XEvent *  pEvent 
)

Scroll bar event filter for dialog control callback function. Generates scroll events.

Parameters
wIDThe Window ID of the dialog control
pCtrlA pointer to the WBDialogControl structure for the dialog control
pEventThe event to query and possibly filter
Returns
A zero if the event is to pass on to the rest of the callback; otherwise, the return value for the dialog control's callback function (the callback function must return this value unmodified)

When a dialog control needs to process events for scroll bars, it should FIRST call this function to ensure that they are handled properly in a standardized manner. If the return value is non-zero, that value must be returned unmodified (the dialog control callback handler uses this value). Otherwise, processing can continue.
Scroll events are send via a ClientMessage using aSCROLL_NOTIFY .

Header File: dialog_controls.h

Definition at line 1876 of file dialog_support.c.

◆ DLGSetControlCaption()

static __inline__ void DLGSetControlCaption ( WBDialogWindow pDialog,
int  iControlID,
const char *  szCaption 
)
static

Convenience function to assign a dialog control's caption based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control
szCaptionpointer to ASCII string containing the new caption

Often it is desirable to assign control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the assignment. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to assign the caption.

Header File: dialog_controls.h

Definition at line 939 of file dialog_controls.h.

◆ DLGSetControlProperty()

static __inline__ int DLGSetControlProperty ( WBDialogWindow pDialog,
int  iControlID,
Atom  aPropName,
const char *  szPropVal 
)
static

Convenience function to assign a text property for a dialog control based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control
aPropNameAtom for the property to be assigned
szPropVala pointer to the (text) data to assign to the property

Often it is desirable to assign control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the assignment. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to assign the property's text value.

See also
WBDialogControlSetProperty()

Header File: dialog_controls.h

Definition at line 1074 of file dialog_controls.h.

◆ DLGSetControlText()

static __inline__ void DLGSetControlText ( WBDialogWindow pDialog,
int  iControlID,
const char *  szText 
)
static

Convenience function to assign a dialog control's TEXT based on its control ID.

Parameters
pDialogPointer to the WBDialogWindow structure of the parent
iControlIDDialog control ID for the desired control
szTextpointer to ASCII string containing the new text

Often it is desirable to assign control properties using the WBDialogWindow structure for the dialog (frame) window and the control's ID, rather than writing several lines of code to query for the correct information, test for validity, etc. and THEN make the assignment. When the control ID is known, but the Window or WBDialogControl structure pointer is not, use THIS function to assign the caption.

Header File: dialog_controls.h

Definition at line 1004 of file dialog_controls.h.

◆ WBDialogControlCreate()

WBDialogControl* WBDialogControlCreate ( Atom  aClass,
WBDialogWindow pOwner,
WBDialogEntry pDialogEntry,
int  iX,
int  iY,
int  iWidth,
int  iHeight,
const char *  szTitle,
const char *  szPropertyList 
)

Create a dialog control window.

Returns
Pointer to a WBDialogControl structure associated with the dialog control window
Parameters
aClassThe class name atom for the window being created (may be None)
pOwnerThe owner window (usually a dialog frame window)
pDialogEntryA pointer to the WBDialogEntry structure associated with the control (the one I will be using)
iXThe horizontal position of the upper left corner of the control window (relative to the owner window)
iYThe vertical position of the upper left corner of the control window (relative to the owner window)
iWidthThe width of the control window
iHeightThe height of the control window
szTitleA null-byte terminated string containing the 'title' text for the control (may be NULL)
szPropertyListA set of newline terminated strings, ending with a null-byte, containing property/value pairs for initial property assignment
Returns
A pointer to a WBDialogControl structure identifying the control

Use this function to create a dialog conrol window, returning a pointer to the WBDialogControl class containing its properties.

Header File: dialog_controls.h

Definition at line 363 of file dialog_controls.c.

◆ WBDialogControlDelDialogProp()

void WBDialogControlDelDialogProp ( WBDialogControl pCtrl,
Atom  aProp 
)

Low-level dialog control property removal.

Header File: dialog_controls.h

Definition at line 977 of file dialog_support.c.

◆ WBDialogControlGetCaption()

const char* WBDialogControlGetCaption ( WBDialogControl pCtrl)

Obtain a pointer to the assigned text for the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
Returns
A const char pointer to the text (owned by the WBDialogControl structure)

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should only query it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 554 of file dialog_support.c.

◆ WBDialogControlGetCaptionInt()

static __inline__ int WBDialogControlGetCaptionInt ( WBDialogControl pCtrl)
static

Returns an integer from the text of the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
Returns
An integer value converted from the text using 'atoi()'

This is a convenience wrapper function around sscanf() and WBDialogControlGetCaption().

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should query it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 568 of file dialog_controls.h.

◆ WBDialogControlGetCaptionLong()

static __inline__ long WBDialogControlGetCaptionLong ( WBDialogControl pCtrl)
static

Returns a long integer from the text of the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
Returns
A long integer value converted from the text using 'atol()'

This is a convenience wrapper function around sscanf() and WBDialogControlGetCaption().

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should query it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 630 of file dialog_controls.h.

◆ WBDialogControlGetCheck()

int WBDialogControlGetCheck ( WBDialogControl pCtrl)

Retrieve the 'CHECKED' property from a dialog control. Returns '0' (un-checked) if not applicable.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
Returns
A value of '1' if the dialog box control is 'checked'; otherwise, zero (unchecked)

The CHECKED property is a special case, not represente by the property list. Assigning it carries some specific implications, which are managed by WBDialogControlSetCheck().

Header File: dialog_controls.h

Definition at line 765 of file dialog_support.c.

◆ WBDialogControlGetDialogProp()

const WB_DIALOG_PROP* WBDialogControlGetDialogProp ( WBDialogControl pCtrl,
Atom  aProp 
)

Low-level dialog control property retrieval.

Header File: dialog_controls.h

Definition at line 1048 of file dialog_support.c.

◆ WBDialogControlGetIconPixmap()

Pixmap WBDialogControlGetIconPixmap ( WBDialogControl pCtrl,
Pixmap *  pPixmap2 
)

Obtain the assigned ICON (image) property for a control, which consists of 2 pixmaps.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
pPixmap2A pointer to the storage for the returned transparency (mask) Pixmap for the ICON image. May be NULL
Returns
The foreground Pixmap for the ICON image. May be None if no Pixmap has been assigned.

The returned Pixmaps are owned by the control and should NOT be manipulated nor free'd. If you need to manipulate the Pixmaps, make copies and assign the copies as the new Pixmaps.

The ICON property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should only maintain it using this function. It is equivalent to the IMAGE or PIXMAP property.

Header File: dialog_controls.h

Definition at line 710 of file dialog_support.c.

◆ WBDialogControlGetPixmap()

Pixmap WBDialogControlGetPixmap ( WBDialogControl pCtrl)

Obtain the assigned PIXMAP (image) property for a control.

Parameters
pCtrlA pointer to the WBDialogControl structure for this control
Returns
The Pixmap that has been assigned to the control. May be 'None'.

The returned Pixmap is owned by the control and should NOT be manipulated nor free'd. If you need to manipulate the Pixmap, make a copy and assign the copy as the new Pixmap.

The PIXMAP property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should only query it using this function. It is equivalent to the IMAGE or ICON property.

Header File: dialog_controls.h

Definition at line 626 of file dialog_support.c.

◆ WBDialogControlGetProperty()

const char* WBDialogControlGetProperty ( WBDialogControl pCtrl,
Atom  aPropName 
)

Mid-level dialog control property retrieval (character string)

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
aPropNameAn atom representing the property name to query
Returns
A const char pointer to the actual property data. May be NULL.

This function returns the actual string pointer stored within the property list, and may be NULL. To modify an existing sring value, you should first make a copy of the string (as needed), then modify the copy and re-assign teh value via WBDialogControlSetProperty().

Header File: dialog_controls.h

Definition at line 823 of file dialog_support.c.

◆ WBDialogControlGetProperty2()

void* WBDialogControlGetProperty2 ( WBDialogControl pCtrl,
Atom  aPropName 
)

Mid-level dialog control property list retrieval (generic pointer)

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
aPropNameAn atom representing the property name to query
Returns
The actual pointer stored for the specified property. May be NULL.

Pointers assigned as a property must have been allocated using 'WBAlloc()'. Any existing pointer already assigned to this property will be automatically destroyed using 'WBFree()'. The memory block itself is considered to be 'owned' by the property list, and will be cleaned up when the control window is destroyed.

NOTE: use WBDialogControlSetProperty2() to directly assign WBAlloc'd pointer, and modify actual data returned by above Assigning different pointer in WBDialogControlGetProperty2() 'WBFree's the existing pointer. Destroying property list does the same thing.

Header File: dialog_controls.h

Definition at line 835 of file dialog_support.c.

◆ WBDialogControlGetPropList()

static __inline__ const WBDialogPropList* WBDialogControlGetPropList ( WBDialogControl pCtrl)
static

Low-level dialog control property list retrieval.

Header File: dialog_controls.h

Definition at line 391 of file dialog_controls.h.

◆ WBDialogControlGetText()

static __inline__ const char* WBDialogControlGetText ( WBDialogControl pCtrl)
static

Obtain the assigned TEXT property for a control, which is different from the CAPTION or Title.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
Returns
A const char pointer to the text property value. May be NULL

The TEXT property is a standard property for a dialog control. To preserve consistency use this function to query it, rather than querying the TEXT property directly.

Header File: dialog_controls.h

Definition at line 881 of file dialog_controls.h.

◆ WBDialogControlSetCaption()

void WBDialogControlSetCaption ( WBDialogControl pCtrl,
const char *  szCaption 
)

Assign text to the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
szCaptionA const char pointer to the text to assign

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should maintain it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 537 of file dialog_support.c.

◆ WBDialogControlSetCaptionInt()

static __inline__ void WBDialogControlSetCaptionInt ( WBDialogControl pCtrl,
int  iValue,
const char *  szFormat 
)
static

Assign an integer as text to the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
iValueAn integer value that is to be assigned as the caption using 'szFormat'
szCaptionA const char pointer to the 'printf' style format string (NULL assumes 'd')

This is a convenience wrapper function around snprintf() and WBDialogControlSetCaption().

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should maintain it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 597 of file dialog_controls.h.

◆ WBDialogControlSetCaptionLong()

static __inline__ void WBDialogControlSetCaptionLong ( WBDialogControl pCtrl,
long  lValue,
const char *  szFormat 
)
static

Assign a long integer as text to the 'CAPTION' property of a dialog control.

Parameters
pCtrlA pointer to the WBDialogControl structure for the dialog control
lValueAn integer value that is to be assigned as the caption using 'szFormat'
szCaptionA const char pointer to the 'printf' style format string (NULL assumes 'ld')

This is a convenience wrapper function around snprintf() and WBDialogControlSetCaption().

The CAPTION property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should maintain it using this function (or similar). It is equivalent to the 'Title'.

Header File: dialog_controls.h

Definition at line 659 of file dialog_controls.h.

◆ WBDialogControlSetCheck()

void WBDialogControlSetCheck ( WBDialogControl pCtrl,
int  iCheck 
)

Assign the TEXT property for a control, which is different from the CAPTION or Title.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
iCheckAn integer containing a positive number to set the 'check' state, zero to clear it, or a negative number to toggle the check state for "non-radio buttons". For a radio button, a negative value has the same effect as a positive one.

The CHECKED property is a special case, not represente by the property list. Assigning it carries some specific implications, which are managed by this function. As an example, whenever a radio button is checked, all of the other buttons within the group are un-checked.

Header File: dialog_controls.h

Definition at line 742 of file dialog_support.c.

◆ WBDialogControlSetDialogProp()

int WBDialogControlSetDialogProp ( WBDialogControl pCtrl,
WB_DIALOG_PROP pPropVal 
)

Low-level dialog control property assignment.

Header File: dialog_controls.h

Definition at line 870 of file dialog_support.c.

◆ WBDialogControlSetIconPixmap()

void WBDialogControlSetIconPixmap ( WBDialogControl pCtrl,
Pixmap  pixmap,
Pixmap  pixmap2 
)

Assign the ICON (image) property for a control, which consists of 2 pixmaps.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
pixmapThe foreground Pixmap for the ICON image (may be None). It must be for the same Display as the control.
pixmap2The transparency (mask) Pixmap for the ICON image (may be None). It must be for the same Display as the control.

The ICON property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should only maintain it using this function. It is equivalent to the IMAGE or PIXMAP property.

Assigning the Pixmaps causes the existing Pixmaps to be free'd using XFreePixmap(). Additionally, you should only assign Pixmaps that were allocated for the same Display as the control.

Header File: dialog_controls.h

Definition at line 648 of file dialog_support.c.

◆ WBDialogControlSetPixmap()

void WBDialogControlSetPixmap ( WBDialogControl pCtrl,
Pixmap  pixmap 
)

Assign the PIXMAP (image) property for a control.

Parameters
pCtrlA pointer to the WBDialogControl structure for this control
pixmapA Pixmap to be assigned (may be None). It must be for the same Display as the control.

The PIXMAP property is a standard property for a dialog control. Since it has its own data member in the WBDialogControl structure, you should only maintain it using this function. It is equivalent to the IMAGE or ICON property.

Assigning the Pixmap causes the existing Pixmap to be free'd using XFreePixmap(). Additionally, you should only assign a Pixmap that was allocated for the same Display as the control.

Header File: dialog_controls.h

Definition at line 564 of file dialog_support.c.

◆ WBDialogControlSetProperty()

int WBDialogControlSetProperty ( WBDialogControl pCtrl,
Atom  aPropName,
const char *  szPropVal 
)

Mid-level dialog control property assignment (character string)

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
aPropNameAn atom representing the property name to query
szPropValA const pointer to a string representing the property value. May be NULL

Strings are stored internally within the property list as a memory block allocated via 'WBAlloc()'. If an existing pointer is already present when a new string is assigned, it is destroyed via 'WBFree()'. The assigned value is then copied into a memory block allocated via 'WBAlloc()' and stored in the property list.

Header File: dialog_controls.h

Definition at line 795 of file dialog_support.c.

◆ WBDialogControlSetProperty2()

void WBDialogControlSetProperty2 ( WBDialogControl pCtrl,
Atom  aPropName,
void *  szPropVal 
)

Mid-level dialog control property list assignment (generic pointer)

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
aPropNameAn atom representing the property name to query
szPropValA WBAlloc'd pointer to binary data to be stored as the property, and owned by the control. May be NULL

Pointers assigned as a property must have been allocated using 'WBAlloc()' (or NULL). Any existing pointer already assigned to this property will be automatically destroyed using 'WBFree()'. The property itself is considered to be 'owned' by the property list, and will be cleaned up when the control window is destroyed.

NOTE: use WBDialogControlSetProperty2 to directly assign WBAlloc'd pointer, and modify the actual data. You should make sure you do not re-use the same pointer unless you take this into consideration. Assigning different pointer in WBDialogControlGetProperty2() 'WBFree's the existing pointer. Destroying property list does the same thing.

Header File: dialog_controls.h

Definition at line 812 of file dialog_support.c.

◆ WBDialogControlSetPropList()

int WBDialogControlSetPropList ( WBDialogControl pCtrl,
const char *  szPropList 
)

Mid-level dialog control property list assignment.

Header File: dialog_controls.h

Definition at line 788 of file dialog_support.c.

◆ WBDialogControlSetText()

static __inline__ void WBDialogControlSetText ( WBDialogControl pCtrl,
const char *  szText 
)
static

Assign the TEXT property for a control, which is different from the CAPTION or Title.

Parameters
pCtrlA ponter to the WBDialogControl structure for the control
szTextA const pointer to a string representing the 'TEXT' property value. May be NULL

The TEXT property is a standard property for a dialog control. To preserve consistency use this function to assign it, rather than assigning the TEXT property directly.

Header File: dialog_controls.h

Definition at line 857 of file dialog_controls.h.

◆ WBDialogControlsInit()

void WBDialogControlsInit ( void  )

Initialization function for dialog controls.

This function must be called once before using any of the Dialog Control functions. Normally an explicit call to this won't be necessary since Dialog (frame) Window support code in dialog_window.c does this automatically.

Header File: dialog_controls.h

Definition at line 471 of file dialog_support.c.

◆ WBGetDialogEntryControlStruct()

static __inline__ WBDialogControl* WBGetDialogEntryControlStruct ( WBDialogWindow pDialog,
int  iControlID 
)
static

Returns a pointer to the WBDialogControl structure for a dialog control based on its ID and containing Dialog Window. May return NULL.

Parameters
pDialogA pointer to a WBDialogWindow structure for the dialog window containing the control
iControlIDAn integer value indicating the 'ID' for the contained control
Returns
Pointer to WBDialogControl structure associated with the dialog control, or NULL if error or nonexistent

This is the preferred function for obtaining a pointer to the WBDialogControl structure for a dialog control window

Header File: dialog_controls.h

Definition at line 513 of file dialog_controls.h.