X11 Work Bench Toolkit  1.0
List Support

Data Structures

struct  __LISTINFO__
 Structure containing data for list-related dialog controls. More...
 
struct  _WB_LIST_CURSEL_
 Structure containing information about the current selection in a list. More...
 

Typedefs

typedef struct __LISTINFO__ LISTINFO
 Structure containing data for list-related dialog controls. More...
 
typedef struct _WB_LIST_CURSEL_ WBListCurSel
 Structure containing information about the current selection in a list. More...
 
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...
 
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, GC, WB_GEOM *, XFontSet), 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, GC, WB_GEOM *, XFontSet), 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...
 
#define DLGInitControlListInfoDefault(X)   DLGInitControlListInfo(X, ListInfoFlags_SORTED, DLGCDefaultListInfoAllocator, WBFree, NULL, NULL)
 wrapper macro for DLGInitControlListInfo() for standard WBAlloc'd text data 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

#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 1172 of file dialog_controls.h.

Typedef Documentation

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 __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.)
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, GC gcPaint, WB_GEOM *pGeom, XFontSet fontSet);
// generic function to display contents of item within 'pGeom' using GC
// 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)
See Also
DLGInitControlListInfo()

Structure containing information about the current selection in a list.

typedef struct _WB_LIST_CURSEL_
{
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)

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

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 1000 of file dialog_controls.h.

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 1014 of file dialog_controls.h.

Function Documentation

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

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

Parameters
pCtrlIdentifies the WBDialogControl structure
pDataPointer to the data for the added item (may be NULL with cbData == 0 for "null data")
cbDataData 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]
iIndexInsert 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 1387 of file dialog_support.c.

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 1070 of file dialog_support.c.

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
pCtrlIdentifies the WBDialogControl structure
iIndexIdentifies 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 1558 of file dialog_support.c.

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 1347 of file dialog_support.c.

int DLGGetControlListSelection ( WBDialogControl pCtrl)

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

Parameters
pCtrlIdentifies 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 1641 of file dialog_support.c.

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

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

Parameters
pCtrlIdentifies 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'
nSizeThe 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 1697 of file dialog_support.c.

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 1702 of file dialog_support.c.

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 1317 of file dialog_support.c.

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

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

Parameters
pCtrlPointer to the WBDialogControl structure
nFlagsFlags that identify the data type in the list
pfnAllocatorThe allocator that must be used when adding new data
pfnDestructorThe de-allocator that must be used when removing data (including cleanup)
pfnDisplayThe function that is called to display the data
pfnSortThe 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 1108 of file dialog_support.c.

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, GC, WB_GEOM *, XFontSet)  pfnDisplay,
int  bSort,
int(*)(const void *, const void *)  pfnSort 
)

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

Parameters
pCtrlPointer to the WBDialogControl structure
bFlagsIndicates whether to modify the Flags - 1 to modify, 0 to use the existing value
nFlagsFlags that identify the data type in the list
bAllocatorIndicates whether to modify the Allocator - 1 to modify, 0 to use the existing value
pfnAllocatorThe allocator that must be used when adding new data
bDestructorIndicates whether to modify the Destructor - 1 to modify, 0 to use the existing value
pfnDestructorThe de-allocator that must be used when removing data (including cleanup)
bDisplayIndicates whether to modify the Display function - 1 to modify, 0 to use the existing value
pfnDisplayThe function that is called to display the data
bSortIndicates whether to modify the Sort function - 1 to modify, 0 to use the existing value
pfnSortThe 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 1143 of file dialog_support.c.

void DLGSetControlListSelection ( WBDialogControl pCtrl,
int  iIndex 
)

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

Parameters
pCtrlIdentifies the WBDialogControl structure
iIndexIdentifies 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 1654 of file dialog_support.c.

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

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

Parameters
pCtrlIdentifies the WBDialogControl structure
iIndexIdentifies the index for the new selection state.
iSelStateThe 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 1693 of file dialog_support.c.