| Header file: | listbox.h |
| Object name: | fLISTBOX |
| Object index: | 1 of 1 Object |
The fLISTBOX is just that - a listbox. You can add strings to this window, and it's just a list - you can then select items from that list and do whatever you need to do with it. How useful is this component? More useful than you think... not only can you add a list of choices, you could make this into a scrolling status/history window... which is very handy at times.
This component is derived from _GUIBASE, and inherits the properties from that.
| Name | Description | Value |
| lbUsual | This is the usual primary style for listboxes. All this does... is nothing much. Just use this one, unless you have a need for another one. | WS_EX_CLIENTEDGE |
| lbRaisedBorder | This style makes the listbox have a raised 3D border instead of the usual sunken 3D border (as the listbox would have with the lbUsual style). | WS_EX_WINDOWEDGE |
| lbNoStyle | This style is no style - which might be useful if you, say, wish to have just a single black line for a border - which will happen if you specify this style. | 0 (Zero) |
| Name | Description | Value |
| lbNormal | This is the style that you will probably use the most - just a standard listbox, with strings in it, yeah, just your average Joe-Bloggs listbox. | WS_BORDER | LBS_HASSTRINGS | LBS_NOINTEGRALHEIGHT | LBS_NOTIFY | AvWind | WS_VSCROLL | WS_HSCROLL |
| lbNormalSorted | This style is just like your standard list box, except that it sorts the contents of the listbox automatically, as you add items. This is handy for alphabetical lists, but if you don't want sorting, this can be rather messy. | LBS_STANDARD | WS_BORDER | LBS_HASSTRINGS | LBS_NOINTEGRALHEIGHT | LBS_NOTIFY | AvWind |
| lbMultiColumn | This style creates a listbox with mutliple columns, which could be useful for displaying several pieces of data at once. I've seen this used in databases - and it certainly makes displaying some information a snap. Unfortunately, I don't know how to add multiple columns, and the information is not exactly forthcoming. If you know, please pass on this information! | LBS_HASSTRINGS | LBS_NOINTEGRALHEIGHT | LBS_NOTIFY | LBS_MULTICOLUMN | AvWind |
| The following options are a little different. Whereas the above options are a mixture of styles to create one type of object, the following styles are by themselves. You can mix them up to make more customised objects. You mix the styles with the OR (|) operator. You can even mix them with the above styles to enhance them further. Mix and match away! | ||
| lsUsual | This isn't an individual style, but it's the styles that you pretty much are going to want even if you make a mix and match style. So do include this style, and then mix some others, to make your custom style. | LBS_NOTIFY | LBS_HASSTRINGS | LBS_NOINTEGRALHEIGHT | AvWind |
| lsShowVerticalScrollBar | This style forces the control to show a vertical scrollbar at all times. Normally, the listbox will only show a scrollbar when it is required. | LBS_DISABLENOSCROLL |
| lsShowHorizontalScrollBar | This style forces the listbox to display a horizontal scrollbar at all times. If you do not have this style, you will not ever have a horizontal scrollbar. | WS_HSCROLL |
| lsMultiSelect | This function allows the user to select multiple items from the listbox at once. | LBS_EXTENDEDSEL |
| lsCantSelect | This style disables the user's ability to be able to select anything from the listbox outright. Good for history/status windows, when you just want to put data in the listbox. | LBS_NOSEL |
| lsAutoSort | This style makes the listbox sort it's contents, as the list items are added. Could be handy for alphabetical lists - but annoying if you really don't want a sort. By the way, if you want to have a list that starts off with "Choose one...", then you really can't sort it. Try adding spaces to the front of the string first - like " Choose One...". | LBS_SORT |
| lsSortStandard | This style is just like the AutoSort style, except that it also adds the lsBorder style, and the LBS_NOTIFY style (to send extra events). If I were you, just use the lsAutoSort style, and then add the other styles that you want on top of that. | LBS_STANDARD |
| lsExpandTabs |
This style forces the listbox to expand tabs in the strings that you add to the listbox. According to the Win32 SDK Reference Manual, the tabs are expanded to "32 Dialog Units", and the rest of the explanation had me doubting the sanity of the Windows API development team. I just have to copy the description for you (taken from the Win32 SDK Reference Manual): "Enables a list box to recognize and expand tab characters when drawing its strings. The default tab positions are 32 dialog box units. A dialog box unit is a horizontal or vertical distance. One horizontal dialog box unit is equal to one-fourth of the current dialog box base-width unit. Windows calculates these units based on the height and width of the current system font. The GetDialogBaseUnits function returns the current dialog box base units in pixels." If you understood that, then you are doing much better than I... | lsExpandTabs |
| lsSendKeyMessages | This style makes the listbox send the keyboard keys to the parent window via the WM_VKEYTOITEM message. Ordinarily I wouldn't bother with this style - if you really want to trap the keys, it's probably easier to trap the keys with the OnKeyPress event provided by the GUI Controller. However, this one is here for those die-hard API programmers (no offence intended). | LBS_WANTKEYBOARDINPUT |
| lsBorder | This style gives the window a simple black line border, provided that the window does not have a 3D border already applied. | WS_BORDER |
| Prototype | Description |
|
void CreateWin(fFORM* Parent, int PrimaryOptions, int SecondaryOptions); void CreateWin(fFORM* Parent, int ID, int PrimaryOptions, int SecondaryOptions); void CreateWin(HWND Parent, int PrimaryOptions, int SecondaryOptions); void CreateWin(HWND Parent, int ID, int PrimaryOptions, int SecondaryOptions); | All of these functions create a listbox (strangely enough). Parent is the parent window, be that a fFORM object or a standard HWND. ID is the ID of the window. PrimaryOptions is the primary options for the window, as specified by the table at the top of this document. SecondaryOptions are the secondary options for the window, as specified by the second table in this document. |
| int AddItem(char* Item); | This function adds an item to the listbox - just a simple string item. The value returned is the index of the new item. |
| void InsertItem(int Index, char* Item); | This function inserts an item at the specified Index - and the item becomes that item at Index. Please note that if you have a sorting listbox, the list will not be sorted. Why not? Well, if you are going to take the time to insert an item, it's pretty obvious that you don't want to sort it. |
|
void AddItemData(char* Item, int Data); void InsertItemData(int Index, char* Item, int Data); | These functions work just like their AddItem() and InsertItem() counterparts, except that they also add a specified value to the item. Each item has a spare four-byte (long int length) storage area associated with it. This area is for use by the programmer, for whatever you may wish to store there. You can use it to determine, say, what item in an array corresponds to a particular item. You can return the data with the GetItemData() function, documented further on. You can change (or add) this data with the ChangeItemData() function, which is also documented later on. |
| void RemoveItem(int Index); | This function removes the list item specified by Index. |
| void Clear(void); | This function empties out the listbox - clears everything. |
| void ChangeItemData(int Index, int Data); | This function changes the associated data with the item specified by Index. Please see AddItemData() and InsertItemData() for a description of this extra data. |
| int GetItemLength(int Index); | This function returns the length of the item specified by Index. |
| char* GetItem(int Index); | This function returns the item that is at Index. |
| int GetItemData(int Index); | This function returns the extra data associated with an item. For an explanation of this, please see the description for AddItemData() and InsertItemData() above. |
| int GetNumberItems(void); | This function returns the number of items in the listbox. This is the absolute number of items in the listbox, and is not zero based. |
| int GetSelectedItem(void); | If you have only have a single-select listbox (the default) then you can use this function to determine what item was selected. This function returns the index of the selected item. |
| void SetSelectedItem(int Index); | This function sets what item is selected, but only in a single-select listbox (the default type). Index specifies what item to select. |
| int GetNumberSelected(void); | If you have a multi-select listbox, then this is the function to use to obtain the number of selected items. You can use the next two functions to retrieve the items that were actually selected. |
| void GetSel(void); | This function actually asks Windows what items were selected. A list of these items are then stored away, ready to be read with the next function. You must call this function before you attempt to use the next function. |
| int GetSelected(int Index); | This function returns the item that was selected. Now this is a little tricky, so pay attention. You would call this function the number of times that there are items selected to get all of the selected items. Say, for example, that there are 5 items selected. So you ask first for item 0 (Zero), then move onto 1, 2, 3, and finally 4. The number returned is the index of the item that is selected. Let's say that you selected items 3, 6, 8, 9, and 15 in the listbox. Asking for item 0 (Zero) would return 3. Asking for item 1 would return 6, and so forth. You see? |
| void CleanUpSel(void); | This function cleans up the memory that was allocated to determine the selected items. You don't have to call this function, as the class will delete this memory when it is destroyed, but it is good practice to release the memory back to Windows. |
| int GetTopItemIndex(void); | This function returns the index of the item that is at the top of the list on the screen. |
| void SetTopItemIndex(int Index); | This function sets the item that is at the top of the list on the screen. |
| int GetPointIndex(int x, int y); | This function returns the index of the item that is at the point (x,y). In the case of the listbox, (0,0) is at the top left hand corner of the listbox. |
| int SelectItem(char* Search, int Start); | This function searches for an item and if found, selects that item. Search can be the first few characters of the item that you wish to look for. Start specifies the item after which to search for. The function returns the index of the item that was selected, or CB_ERR if it can not find an item. |
| void FillWithFileNames(int Attributes, char* FileSpec); | This function fills the listbox with the directory listing of the specified directory. You can specify a file specification with FileSpec too - so "C:\Windows\*.exe" would be perfectly valid and quite useful. |
Please note that the events listed here are done in pairs; one as a property, and the other as a function. The property is assigned a function name, ie. Object.OnClick = &FunctionName, whilst the function is called to verify that an event has occured. Please see the chapter on event handling for information on how to use these correctly.
| Prototype | Description | Sent under |
|
bool CheckChange(wParam, lParam); void (*OnChange)(fLISTBOX* Sender); | This event occurs when a change occurs in the listbox - generally it will mean that a user selected something else than what was already selected from the listbox. | WM_COMMAND |
|
bool CheckCancel(wParam, lParam); void (*OnSelCancel)(fLISTBOX* Sender); | This event occurs when the user 'cancels' the selection in a list box. Exactly how do you cancel a selction in a list box? I don't know, but it seems to be possible. | WM_COMMAND |
|
bool CheckDoubleClick(wParam, lParam); void (*OnDoubleClick)(fLISTBOX* Sender); | This event occurs when the user double clicks an item in the listbox. It is occasionally handy to know when this occurs - you know, to actually do something... | WM_COMMAND |
The following snippet gives a basic idea of how to use this component.
//Create an instance of the listbox, and then
//create a listbox...
fLISTBOX ListBox;
ListBox.CreateWin(&Window, LISTBOX_ID, lbUsual, lbNormal);
//Just add a few items...
ListBox.AddItem("Hello there!");
ListBox.AddItem("This is");
ListBox.AddItem("a simple");
ListBox.AddItem("test.");
//Insert an item after "Hello there!"...
ListBox.InsertItem(1, "Hello World!");
//Now delete the first item...
ListBox.RemoveItem(0);
//Determine which item is selected.
... = ListBox.GetSelectedItem();
//Or determine those selected with a multiple selection listbox...
ListBox.GetSel(); //Initialise...
for (int Temp = 0; Temp < ListBox.GetNumberSelected(); Temp++)
{
//Now just read off the selected items...
... = ListBox.GetSelected(Temp);
//The number returned is the INDEX of a selected item.
}
ListBox.CleanUpSel(); //Clean up.
| Back to index | The FreeFoote Foundation Classes Documentation |