Data Structures
struct	s_LISTINFO
	Structure containing data for list-related dialog controls. More...

struct	s_WBListCurSel
	Structure containing information about the current selection in a list. More...

Macros
#define	DLGInitControlListInfoDefault(X) DLGInitControlListInfo(X, ListInfoFlags_SORTED, DLGCDefaultListInfoAllocator, WBFree, NULL, NULL)
	wrapper macro for DLGInitControlListInfo() for standard WBAlloc'd text data More...

Typedefs
typedef struct s_LISTINFO	LISTINFO
	Structure containing data for list-related dialog controls. More...

typedef struct s_WBListCurSel	WBListCurSel
	Structure containing information about the current selection in a list. More...

Enumerations
enum	ControlListIndex { ControlListIndex_FIRST = 0, ControlListIndex_LAST = 0x7fffffff, ControlListIndex_INSERT_FIRST = -1, ControlListIndex_INSERT_LAST = 0x7fffffff, ControlListIndex_DELETE_ALL = -1, ControlListIndex_NONE = -1 }
	LIST-related constants for the index of an item within a list. More...

enum	ListInfoFlags { ListInfoFlags_SORTED = 1, ListInfoFlags_RESERVED1 = 2, ListInfoFlags_RESERVED2 = 4, ListInfoFlags_RESERVED3 = 8, ListInfoFlags_RESERVED4 = 0x10, ListInfoFlags_RESERVED5 = 0x20, ListInfoFlags_RESERVED6 = 0x40, ListInfoFlags_RESERVED7 = 0x80 }
	Create flags specified in the call to DLGInitControlListInfo() More...

Functions
void *	DLGCDefaultListInfoAllocator (const void *pData, int cbData)
	The default 'List Info' data allocator for a control's list info. More...

const char *	DLGGetControlListText (WBDialogControl *pCtrl, int iIndex)
	Retrieve the text poiner for a single list entry (listbox, combo, and tree controls only) More...

const void *	DLGGetControlListData (WBDialogControl *pCtrl, int iIndex)
	Retrieve the data pointer for a single list entry (listbox, combo, and tree controls only) More...

int	DLGInitControlListInfo (WBDialogControl pCtrl, 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 *))
	Initialize the 'List Entry' for a control, specifying various callbacks and flags. More...

int	DLGModifyControlListInfo (WBDialogControl pCtrl, int bFlags, int nFlags, int bAllocator, void (pfnAllocator)(const void , int), int bDestructor, void(pfnDestructor)(void ), int bDisplay, void(pfnDisplay)(WBDialogControl , void , int, WBGC, WB_GEOM , WB_FONTC), int bSort, int(pfnSort)(const void , const void *))
	Modify the 'List Entry' for a control, specifying various callbacks and flags. More...

int	DLGAddControlListEntry (WBDialogControl pCtrl, const char pData, long cbData, int iIndex)
	Add a list entry to a control's list info. More...

void	DLGDelControlListEntry (WBDialogControl *pCtrl, int iIndex)
	Delete a list entry from a control's list info at a specified index (or deletes ALL entries) More...

int	DLGGetControlListSelection (WBDialogControl *pCtrl)
	Obtain the current selection index for a single-selection list. More...

void	DLGSetControlListSelection (WBDialogControl *pCtrl, int iIndex)
	Assign the current selection index for a single-selection list. More...

void	DLGSetControlListSelectionValue (WBDialogControl *pCtrl, int iIndex, int iSelState)
	Assign the selection state for a specific index within a control's list info. More...

int	DLGGetControlListSelectionBits (WBDialogControl pCtrl, unsigned int piBits, int nSize)
	Query the selection state for multiple items within a control's list info. More...

char *	DLGGetControlListSelectionText (WBDialogControl *pCtrl)
	Query the selection text as multiple strings in an allocated buffer. More...

Detailed Description

Designed specifically for dialog controls, 'List Support' APIs and structures contain lists of objects or strings that are 'self-maintained' via special callback functions assigned to the 'List Info' structure.

Macro Definition Documentation

◆ DLGInitControlListInfoDefault

#define DLGInitControlListInfoDefault ( X ) DLGInitControlListInfo(X, ListInfoFlags_SORTED, DLGCDefaultListInfoAllocator, WBFree, NULL, NULL)

wrapper macro for DLGInitControlListInfo() for standard WBAlloc'd text data

This macro creates a standard WBAlloc'd text data list entry using DLGCDefaultListInfoAllocator() and WBFree, for sorted text data with standard display and sort comparison functions NOTE: using DLGInitControlListInfoDefault implies string data that's WBAlloc'd. For some other scheme of maintaining and copying data pointers for a listbox, substitute your own function pointers as needed.

Definition at line 1508 of file dialog_controls.h.

Typedef Documentation

◆ LISTINFO

LISTINFO

Structure containing data for list-related dialog controls.

Internally maintained structure containing list-related control data including selection information and function callbacks for allocation, de-allocation, display, and sorting.

typedef struct s_LISTINFO
{
  int nItems, nMaxItems;              // size/max size of aItems (must re-alloc to increase nMaxItems)
  int nPos, nTop;                     // scroll position and position of top item
  int nHeight, nItemHeight;           // height (in items) and height of item (in pixels)
  int nFlags;                         // flags (sorted, etc.)
  WB_GEOM geomDisplay;                // the (cached) geometry that defines the "display area" (not scrollbars, border)
  Window wOwner;                      // owning window [to be notified on change]
  void *(*pfnAllocator)(const void *, int); // copy constructor to call for each item that's added
                                      // typically this will call 'WBAlloc' followed by 'memcpy'
                                      // if NULL, the caller-supplied pointer is assigned to 'aItems' as-is
  void (*pfnDestructor)(void *);      // destructor to call for each item that's removed
                                      // typically this will point to 'WBFree'
                                      // if NULL, the caller-supplied pointer is ignored
  void (*pfnDisplay)(WBDialogControl *pControl, void *pData, int iSelected, WBGC gcPaint, WB_GEOM *pGeom, WB_FONTC pFont);
                                      // generic function to display contents of item within 'pGeom' using WBGC
                                      // typically one of the listbox 'display item' functions
  int (*pfnSort)(const void *, const void *); // sort proc (NULL implies strcmp)
  void *aItems[1];                    // array of item data (remainder of struct)
} LISTINFO;

See also: DLGInitControlListInfo()

◆ WBListCurSel

WBListCurSel

Structure containing information about the current selection in a list.

typedef struct s_WBListCurSel
{
  int iCurSel;      // current selection
  int iTopIndex;    // index of item at top of window
  int iHeight;      // calculated height of window in "entries" (see next member)
  int iEntryHeight; // cached display height of each entry (calculated by Expose handler)
} WBListCurSel;

Typically used in a listbox or combo box, this structure specifies the current list selection info for a listbox, combo box, or tree control.
NOTE: this structure must immediately follow the WBDialogControl members in the control's structure for a control that has the CONTROL_SupportListInfo flag.

Enumeration Type Documentation

◆ ControlListIndex

enum ControlListIndex

LIST-related constants for the index of an item within a list.

See also: DLGGetControlListText(), DLGGetControlListData(), DLGAddControlListEntry(), DLGDelControlListEntry()

Enumerator
ControlListIndex_FIRST	first list index
ControlListIndex_LAST	last list index
ControlListIndex_INSERT_FIRST	always insert at beginning
ControlListIndex_INSERT_LAST	always insert at end
ControlListIndex_DELETE_ALL	delete all
ControlListIndex_NONE	"no selection"

Definition at line 1319 of file dialog_controls.h.

◆ ListInfoFlags

enum ListInfoFlags

Create flags specified in the call to DLGInitControlListInfo()

Enumerator
ListInfoFlags_SORTED	list is sorted
ListInfoFlags_RESERVED1	reserved 1
ListInfoFlags_RESERVED2	reserved 2
ListInfoFlags_RESERVED3	reserved 3
ListInfoFlags_RESERVED4	reserved 4
ListInfoFlags_RESERVED5	reserved 5
ListInfoFlags_RESERVED6	reserved 6
ListInfoFlags_RESERVED7	reserved 7

Definition at line 1333 of file dialog_controls.h.

Function Documentation

◆ DLGAddControlListEntry()

int DLGAddControlListEntry	(	WBDialogControl *	pCtrl,
		const char *	pData,
		long	cbData,
		int	iIndex
	)

Add a list entry to a control's list info.

Parameters

pCtrl	Identifies the WBDialogControl structure
pData	Pointer to the data for the added item (may be NULL with cbData == 0 for "null data")
cbData	Data size in bytes. May also indicate copy method (default allocator uses cbData < 0 to copy as string, > 0 as binary data). cbData is zero to assign 'pData' "as-is" (i.e. without copying) [allocator/deallocator should be NULL for this to work]
iIndex	Insert point. Can be an actual index (inserts after that point) or one of the ControlListIndex_INSERT_xxx' enumerations.

Returns: Non-zero on error, zero on success

Although there are some specific nuances associated with the use of this function (such as 'string copy') the 'pData' and 'cbData' parameters are passed along without modification to the allocator function. Whenever DefaultListInfoAllocator() is used, a cbData value less than zero indicates that pData points to a null-byte terminated string, and whenever cbData is equal to zero, the pointer value of 'pData' is assigned to the internal list entry 'as-is'.

Header File: dialog_controls.h

Definition at line 1430 of file dialog_support.c.

◆ DLGCDefaultListInfoAllocator()

void* DLGCDefaultListInfoAllocator	(	const void *	pData,
		int	cbData
	)

The default 'List Info' data allocator for a control's list info.

Header File: dialog_controls.h

Definition at line 1134 of file dialog_support.c.

◆ DLGDelControlListEntry()

void DLGDelControlListEntry	(	WBDialogControl *	pCtrl,
		int	iIndex
	)

Delete a list entry from a control's list info at a specified index (or deletes ALL entries)

Parameters

pCtrl	Identifies the WBDialogControl structure
iIndex	Identifies the index of the entry to delete, or is < 0 (i.e. ControlListIndex_DELETE_ALL) to delete ALL entries

Use this function to remove one or all entries from the control's list info

Header File: dialog_controls.h

Definition at line 1601 of file dialog_support.c.

◆ DLGGetControlListData()

const void* DLGGetControlListData	(	WBDialogControl *	pCtrl,
		int	iIndex
	)

Retrieve the data pointer for a single list entry (listbox, combo, and tree controls only)

Header File: dialog_controls.h

Definition at line 1390 of file dialog_support.c.

◆ DLGGetControlListSelection()

int DLGGetControlListSelection ( WBDialogControl * pCtrl )

Obtain the current selection index for a single-selection list.

Parameters

pCtrl Identifies the WBDialogControl structure

Returns: The index of the selected item, or ControlListIndex_NONE

In a single-selection list, or in a list where multiple selection operations are being performed, there is one item that has a 'selected' state. This function returns the index for that item.

Header File: dialog_controls.h

Definition at line 1675 of file dialog_support.c.

◆ DLGGetControlListSelectionBits()

int DLGGetControlListSelectionBits	(	WBDialogControl *	pCtrl,
		unsigned int *	piBits,
		int	nSize
	)

Query the selection state for multiple items within a control's list info.

Parameters

pCtrl	Identifies the WBDialogControl structure
piBits	(reserved) A pointer to a block of memory that is 'nSize' integers in length, where the index is a LSB bit within the integer. A '1' bit indicates 'selected', a '0' bit indicates 'not selected'
nSize	The size of the 'piBits' array as a number of int elements.

Returns: 0 for no sel, > 0 for the number of selections, < 0 on error. If 'piBits is NULL, it returns the necessary size for the array (in integers)

The 'piBits' and 'nSize' parameters must indicate a memory block of sufficient size, or an error will be returned. Use a NULL value of 'piBits' to obtain the necessary size of the array, if it is not known. To determine if a specific bit is set, use a formula similar to the following

piBits[(iIndex >> 32)] & (1 << (iIndex & 31)) ? TRUE : FALSE

where 'iIndex' represents the index of the bit you wish to query.

Header File: dialog_controls.h

Definition at line 1731 of file dialog_support.c.

◆ DLGGetControlListSelectionText()

char* DLGGetControlListSelectionText ( WBDialogControl * pCtrl )

Query the selection text as multiple strings in an allocated buffer.

The return value is a single allocated buffer (using 'WBAlloc') containing a set of string entries, each separated by a newline character, corresponding to the selected list entries (TEXT elements only).
The return value is NULL if there are no selections or on error.
For non-NULL return values, the caller must use 'WBFree()' to destroy the allocated buffer.

Header File: dialog_controls.h

Definition at line 1736 of file dialog_support.c.

◆ DLGGetControlListText()

const char* DLGGetControlListText	(	WBDialogControl *	pCtrl,
		int	iIndex
	)

Retrieve the text poiner for a single list entry (listbox, combo, and tree controls only)

Header File: dialog_controls.h

Definition at line 1360 of file dialog_support.c.

◆ DLGInitControlListInfo()

int DLGInitControlListInfo	(	WBDialogControl *	pCtrl,
		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
	)

Initialize the 'List Entry' for a control, specifying various callbacks and flags.

Parameters

pCtrl	Pointer to the WBDialogControl structure
nFlags	Flags that identify the data type in the list
pfnAllocator	The allocator that must be used when adding new data
pfnDestructor	The de-allocator that must be used when removing data (including cleanup)
pfnDisplay	The function that is called to display the data
pfnSort	The compare function that is called to sort the data

Returns: non-zero on error, zero on success

This is a generic method by which a control's list entry can be initialized. If the control's list consists entirely of text data, you can simplify the process by using DLGInitControlListInfoDefault()

Header File: dialog_controls.h

Definition at line 1172 of file dialog_support.c.

◆ DLGModifyControlListInfo()

int DLGModifyControlListInfo	(	WBDialogControl *	pCtrl,
		int	bFlags,
		int	nFlags,
		int	bAllocator,
		void ()(const void *, int)	pfnAllocator,
		int	bDestructor,
		void()(void )	pfnDestructor,
		int	bDisplay,
		void()(WBDialogControl , void , int, WBGC, WB_GEOM , WB_FONTC)	pfnDisplay,
		int	bSort,
		int()(const void , const void *)	pfnSort
	)

Modify the 'List Entry' for a control, specifying various callbacks and flags.

Parameters

pCtrl	Pointer to the WBDialogControl structure
bFlags	Indicates whether to modify the Flags - 1 to modify, 0 to use the existing value
nFlags	Flags that identify the data type in the list
bAllocator	Indicates whether to modify the Allocator - 1 to modify, 0 to use the existing value
pfnAllocator	The allocator that must be used when adding new data
bDestructor	Indicates whether to modify the Destructor - 1 to modify, 0 to use the existing value
pfnDestructor	The de-allocator that must be used when removing data (including cleanup)
bDisplay	Indicates whether to modify the Display function - 1 to modify, 0 to use the existing value
pfnDisplay	The function that is called to display the data
bSort	Indicates whether to modify the Sort function - 1 to modify, 0 to use the existing value
pfnSort	The compare function that is called to sort the data

Returns: non-zero on error, zero on success

This is a generic method by which the parameters of a control's list entry can be modified. If the entry does not already exist, a new entry will be initialized with 'default' parameters assigned using the same values you would get with DLGInitControlListInfoDefault()

Header File: dialog_controls.h

Definition at line 1207 of file dialog_support.c.

◆ DLGSetControlListSelection()

void DLGSetControlListSelection	(	WBDialogControl *	pCtrl,
		int	iIndex
	)

Assign the current selection index for a single-selection list.

Parameters

pCtrl	Identifies the WBDialogControl structure
iIndex	Identifies the new selection index. May be ControlListIndex_NONE for NO selection.

In a single-selection list, or in a list where multiple selection operations are being performed, there is one item that has a 'selected' state. This function assigns the index for that item.

Header File: dialog_controls.h

Definition at line 1688 of file dialog_support.c.

◆ DLGSetControlListSelectionValue()

void DLGSetControlListSelectionValue	(	WBDialogControl *	pCtrl,
		int	iIndex,
		int	iSelState
	)

Assign the selection state for a specific index within a control's list info.

Parameters

pCtrl	Identifies the WBDialogControl structure
iIndex	Identifies the index for the new selection state.
iSelState	The new selection state for that index (reserved)

In a multi-selection list, each item has a specified 'selection state' that identifies whether or not the item is selected. This function assigns that value for a single item.

Header File: dialog_controls.h

Definition at line 1727 of file dialog_support.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DLGInitControlListInfoDefault

Typedef Documentation

◆ LISTINFO

◆ WBListCurSel

Enumeration Type Documentation

◆ ControlListIndex

◆ ListInfoFlags

Function Documentation

◆ DLGAddControlListEntry()

◆ DLGCDefaultListInfoAllocator()

◆ DLGDelControlListEntry()

◆ DLGGetControlListData()

◆ DLGGetControlListSelection()

◆ DLGGetControlListSelectionBits()

◆ DLGGetControlListSelectionText()

◆ DLGGetControlListText()

◆ DLGInitControlListInfo()

◆ DLGModifyControlListInfo()

◆ DLGSetControlListSelection()

◆ DLGSetControlListSelectionValue()