A short overview of the ListBoxEx library contained in wlib.lib - created by John Findlay
library version 1.00
Current list and bookmarks for library functions
The ListBoxEx control is similar to the common ListBox except that it supports multiple columns and can have a header bar and grid lines as does the ListView control.
The hidden columns can be scrolled into view as can the hidden rows.
Multiple selection and single selection is supported.
LBXS_BORDER | Creates a control with a thin line border. |
LBXS_NOCLICKHEADER | The header items cannot be clicked. |
LBXS_NOCOLUMNHEADER | No column header items. |
LBXS_NOSCROLL | No scroll bars are displayed. |
LBXS_SHOWSELALWAYS | Even without focus the selected row is always shown. |
LBXS_SINGLESEL | The default is multiple selection - use this if single selection is needed. |
LBXS_SUNKEN | Same as WS_EX_CLIENTEDGE |
Extended Styles:
LBXS_EX_GRIDLINES | Creates a control with a grid lines separating the rows and columns. |
LBXS_EX_FULLROWSELECT | The default selection is only for the left-most item in a row. Use this for full row selection. |
LBXS_EX_NOTIFYCLICK | The parent Window will be notified when a row has received a mouse click. |
LBXS_EX_NOTIFYDBCLICK | The parent Window will be notified when a row has received a double mouse click. |
LBXS_EX_CHECKBOXES | Check box's will be displayed to the left on the first column. Check box's can be used with LBXS_SINGLESEL so this is another way to have multiple selection. |
LBXS_EX_NOTIFYHIGHLITE | Use this to receive notification of which row is highlighted. This is not the same as selected. |
LBXS_EX_TOOLTIP | Enables tooltip for the first column of row. The user must supply a pointer to a null terminated array of chars. See below for example usage. |
Notification Messages:
LBXN_CLICK | The parent Window will receive this message when either a mouse click or a double mouse click has been received depending on which was specified with the extended style flags. |
LBXN_HDRCLICK | The parent Window will receive this message when a header button has been clicked. |
LBXN_HIGHLITE | Returns the index of the highlighted row in 'wParam'. If no row is highlighted returns -1. |
LBXN_TTTEXT | Used for ToolTip window text. The row
index will be passed in wParam. Example usage case LBXN_TTTEXT:{ |
The syntax and explanation of each function (please see the testlbx.c listing for example usage)
syntax:
This creates the ListBoxEx control - the control is always a child of the parent window and will usually have various styles specified. The default style is, no border, with header, header click enabled, multiple selection and selection highlight limited to the left most item or column.
Here is a typical call to create a ListBoxEx
g_hWndLbx = CreateListBoxEx(
LBXS_EX_FULLROWSELECT | LBXS_EX_GRIDLINES |
LBXS_EX_NOTIFYDBCLICK,
LBXS_BORDER | LBXS_SHOWSELALWAYS | LBXS_SUNKEN,
20, 20, 300, 300, hWndParent, NUMCOLS, LBX_ID );
Various styles are specified.
The first parameter specifies the extended style for the ListBoxEx control.
Next is the style parameter.
The next four parameters specify the start position and width & height of the control. x y cx cy
Next comes the Window handle of the parent, then NUMCOLS specifies the number of columns and finally the control identifier.
Return values:
If successful the function returns the handle to the newly created control. If successful NULL is returned.
syntax:
int Lbx_AddRowAll( HWND hwndLbx, int nCols, char ** str );
This appends a new row to the list, consisting of 'nCols' number of items to add. nCols will normally be the specified number of columns when creating the ListBoxEx control. This is the most efficient way to create and add items to the ListBoxEx control.
hwndLbx -> the handle of the ListBoxEx control returned from CreateListBoxEx()
nCols -> the number of column items passed using char ** str
str -> a pointer to pointer to an array of chars. See example listing for two ways of using char **. One using a static declaration, the other using malloc().
Return values:
When successful this function returns '0'. If unsuccessful it will return -1.
syntax:
int Lbx_AddRow( HWND hwndLbx, char * str );
This appends a new row to the list, consisting of one item, the left most item. The other items may be inserted later by using the function Lbx_AddItem.
hwndLbx -> the handle of the ListBoxEx control returned from CreateListBoxEx()
str -> a pointer to an array of chars containing the string.
Return values:
When successful this function returns '0'. If unsuccessful it will return -1.
syntax:
int Lbx_AddItem( HWND hwndLbx, int row, int item, char * str );
Lbx_AddItem sets the string in one position in a row. Any column item can be changed using this function.
Return Values:
VOID
syntax:
void Lbx_DeleteAllRows( HWND hwndLbx );
Lbx_DeleteAllRows resets the LixtBoxEx control so that it contains no items. The LixtBoxEx control maintains the same number of columns as when created and the column header names remain unchanged.
Return Values:
VOID
syntax:
void Lbx_DeleteRow( HWND hwndLbx, int row );
Lbx_DeleteRow deletes one row. The list is zero based so if for example you have a count of 30 and want to delete the last row, you would send 29.
Return Values:
If successful returns 0, if unsuccessful return -1.
syntax:
void Lbx_FindRow( HWND hwndLbx, int istart, char * str );
Lbx_FindRow searches the list for the string contained in the array of chars pointed to by str and starting at position istart. Only the left most column is searched.
Return Values:
If successful returns the zero based index of the row where the string was found, if unsuccessful the return will be -1.
syntax:
COLORREF Lbx_GetBkColor( HWND hwndLbx );
Lbx_GetBkColor returns the colour of the background as a COLORREF value.
syntax:
BOOL Lbx_GetCheckMark( HWND hwndLbx, int index );
Lbx_GetCheckMark returns the status of a row's check mark, FALSE if no check mark, TRUE if check marked.
syntax:
int Lbx_GetColWidth( HWND hwndLbx, int icol );
Lbx_GetColWidth returns the width in pixels of the specified column 'icol'.
syntax:
int Lbx_GetCurSel( HWND hwndLbx );
Lbx_GetCurSel returns the index to the currently selected row or -1 if no row is selected. For multiple selection lists Lbx_GetCurSel returns the first item the user selected before selecting other items. Therefore the extended list may be either from lower to higher, or from higher to lower.
syntax:
HANDLE Lbx_GetFont( HWND hwndLbx );
Lbx_GetFont returns the handle to the currently selected font.
syntax:
int Lbx_GetHighItem( HWND hwndLbx );
Lbx_GetHighItem returns the index to the item that currently is highlighted while the mouse is over said item. Returns -1 if there are no highlighted items.
syntax:
HANDLE Lbx_GetItemState( HWND hwndLbx, int row );
Lbx_GetItemState returns the currently selected state of the item 'row'. If selected return TRUE, if not selected return FALSE.
syntax:
void Lbx_GetItemText( HWND hwndLbx, int row, int col, char * str, int buffsize );
Lbx_GetItemText retrieves the string from the row and column specified, 'row' and 'col'.
str -> points to a char buffer. The returned string will be NULL terminated.
buffsize -> is the size of the char buffer. If the buffer is not large enough to hold the string, including the NULL terminator undefined behaviour is invoked.
syntax:
int Lbx_GetRowCount( HWND hwndLbx );
Lbx_GetRowCount returns the number of rows that are currently contained in the ListBoxEx.
syntax:
void Lbx_GetRowText( HWND hwndLbx, int nCols, int row, char ** str, int bufsize );
Lbx_GetRowText retrieves all row items in one call into separate char arrays.
hwndLbx -> handle to the ListBoxEx control.
nCols -> the number of column items being requested.
row -> the row being requested.
str -> pointer to pointer to array of chars.
bufsize -> the buffer size. This is the size of one buffer, all buffers are assumed be be of the same size.
The example listing TestLbx.c shows one way to do this using allocated memory.
char * str[NUMCOLS];
// create an array of char pointers
for (int i = 0; i<NUMCOLS; i++) // allocated a block or mem for each item
str[i] = malloc( 16 ); // and set each
pointer to this memory
//
row
Lbx_GetRowText( g_hWndLbx, NUMCOLS, 2, str, 16 ); // call the function
strcpy(strMess, str[0]);
// copy first item from array str[0]
strcat(strMess, "\n" );
// add a line break
for (int i = 1; i<NUMCOLS; i++){ // get
the rest of the items
strcat(strMess, str[i]);
//
and copy them into the remaining arrays
strcat(strMess, "\n" );
// add a line break
}
for (int i = 0; i<NUMCOLS; i++) // free the
memory when finished
free(str[i]);
You can retrieve each item separately using Lbx_GetItemText
syntax:
int Lbx_GetRowTextBuffer( HWND hwndLbx, int nCols, int row, char * str, int bufsize, char * wkbuf, int wkbufsize, char sep );
Lbx_GetRowTextBuffer retrieves all row items in one call into one buffer. The strings are concatenated by this call. Optionally a separation character can be inserted between each item as they are being concatenated.
hwndLbx -> handle to the ListBoxEx control.
nCols -> the number of column items being requested.
row -> the row being requested.
str -> pointer to array of chars.
bufsize -> the buffer size.
wkbuf -> a working buffer. This must be at least the size of the largest string item.
wkbufsize -> the size the this buffer.
sep -> the separation character. If this is zero no separation character will be inserted.
Return Values:
Whilst the routine is concatenating a check is made to see if the remaining bytes in char array 'str' is large enough to accommodate the next string item, if there is not enough room for the next item the concatenation is aborted and the function returns -1. If no problems are encountered whilst retrieving and concatenating the items the function returns 0.
The size of buffer 'str' should be
str[((number of columns + 1) * largest item size)]
and wkbuf should be large enough to hold the largest item.
An efficient concatenation algorithm has been used for this function.
syntax:
int Lbx_GetRowsPerPage( HWND hwndLbx );
Lbx_GetRowsPerPage returns the number of rows that can fit wiyhin the height of the control.
syntax:
int Lbx_GetSelCount( HWND hwndLbx );
Lbx_GetSelCount returns the number of selected rows. When in multiple selection mode it returns the number of selected rows, when in single selection mode it returns 1 if there is a selection. If no row are selected it returns -1.
syntax:
int Lbx_GetStringWidth( HWND hwndLbx, char * str );
Lbx_GetStringWidth is a helper function that returns the width of a specified string using the specified ListBoxEx controls currently selected font. Use this to determine the required width of a column. Use Lbx_SetColWidth to adjust.
syntax:
COLORREF Lbx_GetTextColor( HWND hwndLbx );
Lbx_GetTextColor returns the current colour used for the text. A COLORREF value is returned.
syntax:
int Lbx_InsertRow( HWND hwndLbx, int row, char * str );
Lbx_InsertRow inserts a row into position row of the list. Only the left most column item is inserted using the arrays of chars pointer to by str. You can later add the other items, filling in the empty columns with Lbx_AddItem. The position to insert must be prior to the last row.
Use Lbx_AddRow to append, use Lbx_InsertRow to insert.
Return Values:
If successful the function returns 0. If not successful the function will return -1.
syntax:
int Lbx_InsertRowAll( HWND hwndLbx, int nCols, int row, char ** str );
Lbx_InsertRowAll inserts a row into position row of the list. All column items up to nCols will be inserted.
hwndLbx -> handle to the ListBoxEx control.
nCols -> the number of column items to insert.
row -> the row to insert. The position to insert must be prior to the last row.
str -> pointer to pointer to array of chars.
Return Values:
If successful the function returns 0. If not successful the function will return -1.
syntax:
BOOL Lbx_Scroll( HWND hwndLbx, int dx, int dy );
Lbx_Scroll scrolls the ListBoxEx window.
hwndLbx -> handle to the ListBoxEx control.
dx -> the number of pixels to scroll horizontally. +ve and -ve values are used for direction.
dy -> the number of pixels to scroll vertically. +ve and -ve values are used for direction.
Return Values:
Returns TRUE if successful or FALSE otherwise.
syntax:
void Lbx_SetBkColor( HWND hwndLbx, COLORREF colref );
Lbx_SetBkColor set the background colour for the controls display area.
Exapmle:
Lbx_SetBkColor( hwndLbx, RGB( 192, 192, 192 ));
Return Values:
No return value.
syntax:
void Lbx_SetCheckMark( HWND hwndLbx, int index, BOOL fCheck );
Lbx_SetCheckMark set the check mark of a row item. To check 'fCheck' should be TRUE, to un-check fCheck should be FALSE.
Return Values:
No return value.
syntax:
void Lbx_SetColHeadTxt( HWND hwndLbx, int iCol, char * str );
Lbx_SetColHeadText set the text for one column header.
iCol -> the zero based index of the column.
Return Values:
No return value.
syntax:
void Lbx_SetColHeadTxtAll( HWND hwndLbx, int nCols, char ** str );
Lbx_SetColHeadTextAll sets 'nCols' number of column header texts.
nCol -> the number of column headers starting from zero.
str -> is a pointer to pointer to array of chars. See example listing TestLbx.c
Return Values:
No return value.
syntax:
void Lbx_SetColWidth( HWND hwndLbx, int iCol, int width );
Lbx_SetColWidth sets iCol column width in pixels.
iCol -> the zero based index of the column.
width -> the required width in pixels.
Return Values:
No return value.
syntax:
void Lbx_SetColWidthAll( HWND hwndLbx, int nCols, int * width );
Lbx_SetColWidthAll sets nCols number of column widths starting at zero.
nCols -> the number of column widths to adjust.
width -> the required width in pixels. This is a pointer to array of ints. See example listing TestLbx.c
Return Values:
No return value.
syntax:
void Lbx_SetFont( HWND hwndLbx, HANDLE hFont );
Lbx_SetFont sets the font 'hFont' as the current font.
hFont -> the handle to the font.
Return Values:
No return value.
syntax:
void Lbx_SetSelected( HWND hwndLbx, int row, BOOL fCheck );
Lbx_SetSelected highlights of de-selects a specified row..
row -> the row to either select or un-select.
fCheck -> boolean True or False.
Return Values:
No return value.
syntax:
void Lbx_SetTextColor( HWND hwndLbx, COLORREF colref );
Lbx_SetTextColor sets the colour of the text.
colref -> the handle to the font.
Example
Lbx_SetTextColor( hwndLbx, RGB( 228, 0, 0 );
Return Values:
No return value.
syntax:
void Lbx_ShowWindow( HWND hwndLbx, DWORD show );
Lbx_ShowWindow shows or hides the control.
show -> can be SW_SHOW or SW_HIDE.
Return Values:
No return value.
syntax:
void Lbx_SortRows( HWND hwndLbx );
Lbx_SortRows performs an ascending sort using the left most column (column '0') values or strings as the sort criteria.
Return Values:
No return value.
syntax:
void Lbx_SortRowsEx( HWND hwndLbx, int (*comp)(int a, int b), long lval );
Lbx_SortRowsEx is a more flexible sort that allows the user to control the sort criteria. This function uses an application-defined comparison function to sort the items of a list-view control. The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent. The index of each row is passed to the used defined comparison function.
hwndLbx -> the controls handle
comp -> pointer to the user supplied comparison function that expects three ints passed.
a -> first index of row to compare
b -> second index to compare
lval -> value passed by the user.
Example comparison function with the call:
Lbx_SortRowsEx( g_hWndLbx, compare, 1 ); // pass the address of func compare() and lval as '1'
int CALLBACK compare( int a, int b, int
sign )
{
// get two strings to compare in cmpstr1 & cmpstr2
// row col
Lbx_GetItemText( g_hWndLbx, a, 0, cmpstr1, 200 );
Lbx_GetItemText( g_hWndLbx, b, 0, cmpstr2, 200 );
if (!sign)
return strcmp( cmpstr1, cmpstr2 );
else
return -strcmp( cmpstr1, cmpstr2 );
}
The compare function must retrevie the strings into suitable char arrays and then compare then with a function such as the run time libraries strcmp(). The passed lval in this case is '1' causing the second strcmp function to be used. When retreving the strings one can select any column item therefore sorting using any column as the sort criteria.
Return Values:
No return value.
int Lbx_GetTopSel( HWND hwndLbx )
syntax:
int Lbx_GetTopSel( HWND hwndLbx );
Lbx_GetTopSel retrieves the top-most selected item in a multiple selection.
Return Values:
If there are no selected items returns -1, otherwise returns the top-most selected item.
syntax:
int Lbx_TopVisibleRow( HWND hwndLbx );
Lbx_TopVisibleRow returns the zero based index of the row at the top of the controls window display.
syntax:
void Lbx_Update( HWND hwndLbx );
Lbx_Update updates the display.
Return Values:
No return value.
syntax:
void Lbx_libvers();
Lbx_libvers displays a MessageBox showing the version of the library.
Return Values:
No return value.