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...
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. 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_PROP *	WBDialogControlGetDialogProp (WBDialogControl *pCtrl, Atom aProp)
	Low-level dialog control property retrieval. More...
static __inline__ const WBDialogPropList *	WBDialogControlGetPropList (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__ WBDialogControl *	DLGGetDialogControlStruct (Window wID)
	Returns a pointer to the WBDialogControl structure for a dialog control with validation. May return NULL. More...
static __inline__ WBDialogControl *	WBGetDialogEntryControlStruct (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__ WBDialogControl *	DLGGetDialogControlStructFromID (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...
LISTINFO *	DLGCListInfoConstructor (Window wOwner, int nMax, int nFlags, void *(*pfnAllocator)(const void *, int), void(*pfnDestructor)(void *), void(*pfnDisplay)(WBDialogControl *, void *, int, WBGC, WB_GEOM *, WB_FONTC), 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, WBGC gc, WB_GEOM *pGeom, WB_FONTC pFont)
	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,
		WBGC	gc,
		WB_GEOM *	pGeom,
		WB_FONTC	pFont
	)

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

Parameters

pList	A pointer to a WBDialogControl structure for the list type control
pData	A pointer to the data to display
iSelected	A flag indicating whether the item has been selected (1 = selected, 0 = not selected)
gc	The graphics context for displaying the data
pGeom	a WB_GEOM representing the rectangular area to draw the item in.
pFont	A WB_FONTC 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 1756 of file dialog_support.c.

DLGCDestroyProperties()

void DLGCDestroyProperties

(

WBDialogPropList *

pPropList

)

Destroy Properties for a dialog control.

Parameters

pPropList

A 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, WBGC, WB_GEOM *, WB_FONTC)	pfnDisplay,
		int(*)(const void *, const void *)	pfnSort
	)

Create LISTINFO structure for a list type control.

Parameters

wOwner	the Window ID for the owner of the LISTINFO structure
nMax	the initial maximum size of the list (can be increased, but needs re-allocation)
nFlags	A binary flag indicating various properties, such as 'sorted'
pfnAllocator	A pointer to a constructor callback for a new list item. Use NULL for default
pfnDestructor	A pointer to a destructor callback for the list item. Use NULL for default
pfnDisplay	A pointer to a 'display' callback
pfnSort	A 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

pListInfo

A 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog control ID for the desired control
aPropName	Atom 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog 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

wID	Window 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog 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

pDialogControl	A pointer to the WBDialogControl structure that is associated with the dialog control window
szClassName	An optional 'class name' string to be used for debug and tracing (may be NULL)
pCallback	The 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

wID	The Window ID of the dialog control
pCtrl	A pointer to the WBDialogControl structure for the dialog control
pEvent	The 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 1846 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog control ID for the desired control
szCaption	pointer 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog control ID for the desired control
aPropName	Atom for the property to be assigned
szPropVal	a 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

pDialog	Pointer to the WBDialogWindow structure of the parent
iControlID	Dialog control ID for the desired control
szText	pointer 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

aClass	The class name atom for the window being created (may be None)
pOwner	The owner window (usually a dialog frame window)
pDialogEntry	A pointer to the WBDialogEntry structure associated with the control (the one I will be using)
iX	The horizontal position of the upper left corner of the control window (relative to the owner window)
iY	The vertical position of the upper left corner of the control window (relative to the owner window)
iWidth	The width of the control window
iHeight	The height of the control window
szTitle	A null-byte terminated string containing the 'title' text for the control (may be NULL)
szPropertyList	A 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

pCtrl

A 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

pCtrl

A 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

pCtrl

A 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

pCtrl

A 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

pCtrl	A ponter to the WBDialogControl structure for the control
pPixmap2	A 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

pCtrl

A 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

pCtrl	A ponter to the WBDialogControl structure for the control
aPropName	An 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

pCtrl	A ponter to the WBDialogControl structure for the control
aPropName	An 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

pCtrl

A 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

pCtrl	A pointer to the WBDialogControl structure for the dialog control
szCaption	A 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

pCtrl	A pointer to the WBDialogControl structure for the dialog control
iValue	An integer value that is to be assigned as the caption using 'szFormat'
szCaption	A 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

pCtrl	A pointer to the WBDialogControl structure for the dialog control
lValue	An integer value that is to be assigned as the caption using 'szFormat'
szCaption	A 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

pCtrl	A ponter to the WBDialogControl structure for the control
iCheck	An 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

pCtrl	A ponter to the WBDialogControl structure for the control
pixmap	The foreground Pixmap for the ICON image (may be None). It must be for the same Display as the control.
pixmap2	The 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

pCtrl	A pointer to the WBDialogControl structure for this control
pixmap	A 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

pCtrl	A ponter to the WBDialogControl structure for the control
aPropName	An atom representing the property name to query
szPropVal	A 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

pCtrl	A ponter to the WBDialogControl structure for the control
aPropName	An atom representing the property name to query
szPropVal	A 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

pCtrl	A ponter to the WBDialogControl structure for the control
szText	A 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

pDialog	A pointer to a WBDialogWindow structure for the dialog window containing the control
iControlID	An 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.