| Header file: | combobox.h |
| Object name: | fCOMBOBOX |
| Object index: | 1 of 1 Object |
The combobox is a wrapper for the window class combobox (obviously). A combobox is a drop down list containing multiple items of text, of which the user can select one. Also, the combobox can include an edit control, for adding more items to the list. There are many options to change to specify how the control works and what it does.
This component is derived from _GUIBASE, and inherits the properties from that.
| Name | Description | Value |
| cbUsual | This is the usual primary style for this object. Unless you don't want a border of any style, you will use this. | WS_EX_CLIENTEDGE |
| 0 | Should you wish to not have a 3D border, you can use 0 (Zero) for the primary style. Generally you should use the cbUsual style. | 0 |
| Name | Description | Value |
| cbNormal | This would be a usual combobox, with the options that you would usually use for a combobox. | WS_VISIBLE | WS_CHILD | CBS_HASSTRINGS | CBS_DROPDOWN | CBS_NOINTEGRALHEIGHT | CBS_AUTOHSCROLL | WS_VSCROLL |
| 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 style to enhance it further. Mix and match away! | ||
| cbAutoScroll | This style makes the edit control on the combo box scroll if the text is longer than the area provided. If this style is not applied, then you will only be able to type in as much text as you can fit into that area. | CBS_AUTOHSCROLL |
| cbScrollBarInList | By default, when the number of items in a drop down list fills the available area for the list, the extra items get cut off. With this style, if the list goes longer than the available area, you will be able to scroll through the list with the supplied scrollbar. | WS_VSCROLL |
| cbHorizontalScrollBar | When the list is shown, not all items may fit in the available width. If you would like, you can set this style, and then a horizontal scrollbar will be shown on the bottom of the list, allowing you to scroll to see the rest of the whole length of the item(s). | WS_HSCROLL |
| cbShowScrollBarAlways | With this style, the scrollbars that you have specified will always be shown. If they are not required, they will be disabled, but still visible. | CBS_DISABLENOSCROLL |
| cbDropDown | This style makes a standard combobox with an edit control. You can type data into the edit control on the combobox. | CBS_DROPDOWN |
| cbDropDownList | You may not want an edit control that you can type things into - and with this style, you will no longer be able to type things into it. Instead, an item must be selected from the list, and when it is, that item's text will be displayed in the box. | CBS_DROPDOWNLIST |
| cbHasStrings | Why exactly you would want a combobox without strings in it beats me (numbers would have to be shown as strings), but Microsoft seems to think that maybe you don't want to show strings. If you create your own style from scratch, be sure to include this style. It allows the combo box list to contain strings. Apparently, if your combobox is ownerdrawn, you may not want this style, as otherwise Windows' creates a list of strings internally which you don't otherwise need. | CBS_HASSTRINGS |
| cbNoAutoResize | And yet another obscure option that is on by default and that will annoy you: the combobox will resize it's width as it feels is required to fit in all the information. Yes, that might be nice, but when you carefully lay out a window, to pixel accuracy, the last thing you need is to have a combobox that dynamically resizes itself. Setting this style prevents that from happening. | CBS_NOINTEGRALHEIGHT |
| cbSimpleEditList | You can extend the combo box component one step further should you want to. As you know, the combo box is an edit component plus a listbox which can be shown or hidden with an extra button. But what if the listbox was static, and didn't go away? Wouldn't that be handy sometimes? Well, here you can have it. Set this style, and you will end up with an edit control, and a list box control directly underneath it, all controlled via a combobox interface. The control still works exactly the same way. The listbox can not be hidden - it will always be visible. | CBS_SIMPLE |
| cbSort | This style makes the combobox automatically alphabetically sort the contents of the combo box. Could be handy. | CBS_SORT |
| cbOwnerDraw | Now we get tricky. If you want, you can draw your own combobox. Just set this style and intercept some of the events, and away you go! Please note that with this style, each item has the same height. | CBS_OWNERDRAWFIXED |
| cbOwnerDrawDiffHeight | This style is just like the above style, except that each item in the list can have a different height. You can set the height of each item with the functions provided - see the methods table for those. | CBS_OWNERDRAWVARIABLE |
| cbConvertToLowercase | For the edit control part: any character that is typed in will automatically be converted to it's lowercase counterpart (if applicable). Only valid if you have an edit control that you can type into. | CBS_LOWERCASE |
| cbConvertToUppercase | This style is just like the above style, except that it converts all characters to uppercase (if applicable). | CBS_UPPERCASE |
| Prototype | Description |
| int AddItem(char* Item); | Adds an item to the list, with the text specified by item. Simple and elegant. If you have sorting turned on, the list will automatically be re-sorted. The return value is the index of the item, after sorting. |
| int AddItem(char* Item, int Data); | This function is the same as the above, but it associates a value with the added item. This could be an index of an array, for example - or anything that you want to associate with an item. You can retrieve this value with GetItemData(), documented below. |
| void InsertItem(int Index, char* Item); | This function also adds a string, but instead of just appending the string to the end of the list, you can insert it at a specified spot. Index is the position into which you wish to insert the string. Please note that using this function will not cause the combobox to re-sort it's list. |
| void RemoveItem(int Index); | This function removes the item at Index. |
| void Clear(void); | You don't want any more items in the combo box? Use this function, and they will all be deleted. |
| void FillWithDirectoryListing(int Attributes, char* FileSpec); |
This little function fills the list with the contents of a directory, with the specified attributes and with the specified file specification. Attributes can be one or more of the following: (taken from the Win32 SDK Reference) DDL_ARCHIVE - Includes archived files. DDL_DIRECTORY - Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]). DDL_DRIVES - Includes drives. Drives are listed in the form [-x-], where x is the drive letter. DDL_EXCLUSIVE - Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified. DDL_HIDDEN - Includes hidden files. DDL_READONLY - Includes read-only files. DDL_READWRITE - Includes read-write files with no additional attributes. DDL_SYSTEM - Includes system files. You can mix the above styles with the OR (|) operator. As for the FileSpec parameter - you use any normal wildcards, plus a drive and directory if you don't want the list to be filled with the current directory. An example of FileSpec would be "C:\Windows\*.*" or "C:\*.bat". One last thing to note: the filenames will be short file names. Please keep this in mind. This function is provided by Windows. |
| int FindString(int Start, char* String); | This function will search for String starting from Start in the items in the list. If it should find the string, or a part of the first few letters in the string, it will return the index of the string. If you want to find a complete string, and not a string starting with the letters provided, then please use the next function. If the string is not in the combobox, CB_ERR is returned. |
| int FindStringExact(int Start, char* String); | This function searches for String after Start. If the function finds the string, it will return the index of that string. If the function gets to the end of the list, it will return to the top and continue searching until it reaches start again. To search the whole list, specify -1 as Start. If the string is not in the combobox, CB_ERR is returned. |
| int FindSelectString(int Start, char* Prefix); | This function looks for a string starting with Prefix, after Start, and if it finds that string, it selects it. It will then return the index of that item. |
| int GetNumberItems(void); | This function will return the number of items in the list. |
| int GetCurrentSelection(void); | This function will return the index of the currently selected item. |
| void SetCurrentSelection(int Index); | This function sets the current selection - the item specified by Index will be selected, and displayed in the box at the top. |
| int GetTopItemIndex(void); | This function returns the index of the item that is at the top of the list, if the list has been scrolled. |
| void SetTopIndex(int Index); | This function sets the item that is at the top of the list. The item specified by Index will end up at the top of the list. The list will scroll if required to make this item end up at the top of the list. |
| char* GetItemText(int Index); | This function retrieves the text for the item specified by Index. |
| int GetItemData(int Index); | This function returns the integer value associated with a particular item. You can set this value with the next function. |
| int SetItemData(int Index, int Data); | This function sets a integer value to be associated with an item. This could be used to associate an index in an array to an item in the list. |
| int GetSelectionStart(void); | This function gets the current selections start - this applies to the edit control part of the combo box. If you have typed text in it, and then selected that text, this function returns the character after which the selction starts, and if nothing is selected, this returns the position of the cursor. |
| int GetSelectionEnd(void); | This function is the same as the above function, except that it gets the end of the selected text. |
| void SetSelection(int Start, int End); | This function sets the text that is selected in the edit control at the top. |
| void SetMaxTextLength(int Length); | This function sets the number of characters that you can type into the edit control at the top. |
| bool IsListDown(void); | If the list is down, then this function will return TRUE, otherwise, it will return FALSE. |
| void SetListDownState(bool Set); | This function sets whether the list is down or not. Passing TRUE will make the list come down, but passing FALSE will make the list go up again. |
| void SetExtendedStyle(bool Set); | There is one extended style for comboboxes, but it can not be set by primary options. Why not beats me. However, with this function, passing TRUE will enable this extended style. Passing FALSE will turn it off. Enough suspense? Are you really wondering what this is now? Well, normally the list can be opened (if the combobox has focus) by pressing F4 or pressing the down arrow. However, if you set this style, pressing F4 will no longer open the list. I suppose there is a use for this... |
| void SetSelectionFieldHeight(int Height); | This sets the height (in pixels) of the edit control at the top of the combobox. |
| void SetItemsHeight(int Height); | This function sets the height of all the items in the combobox list. The height is in Pixels. |
| void SetItemHeight(int Index, int Height); | This function sets the height of one item - the item specified by Index. The height is in pixels. |
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 CheckChanged(wParam, lParam); void (*OnSelectionChange)(fCOMBOBOX* Sender); | This event occurs when the user has changed the selection, by clicking an item or changing the selection with the cursor keys. | WM_COMMAND |
|
bool CheckSelectionCanceled(wParam, lParam); void (*OnSelectionCancel)(fCOMBOBOX* Sender); | This event occurs when the user cancels a selection. How would you do that? Say the user has the list open, and then they click somewhere else, not inside that control, causing the combobox to lose focus and the list to close. This event will be sent in that case. | WM_COMMAND |
|
bool CheckSelectionOk(wParam, lParam); void (*OnSelectionOk)(fCOMBOBOX* Sender); | This event occurs when the user properly selects an item from the list. | WM_COMMAND |
|
bool CheckOpenList(wParam, lParam); void (*OnListOpen)(fCOMBOBOX* Sender); | This event occurs when the user opens the list. | WM_COMMAND |
|
bool CheckCloseList(wParam, lParam); void (*OnListClose)(fCOMBOBOX* Sender); | This event occurs when the list is closed by the user. | WM_COMMAND |
|
bool CheckItemDoubleClick(wParam, lParam); void (*OnItemDoubleClick)(fCOMBOBOX* Sender); | This event occurs when the user double clicks on an item. I think this event is more useful when the combobox is acting as an edit control and a static list control. | WM_COMMAND |
|
bool CheckEditChange(wParam, lParam); void (*OnEditChange)(fCOMBOBOX* Sender); | This event occurs when the user changes the text in the edit control, and after Windows has updated the screen. | WM_COMMAND |
|
bool CheckEditUpdate(wParam, lParam); void (*OnEditUpdate)(fCOMBOBOX* Sender); | This event occurs when the user has changed the contents of the edit control, but before Windows displays the updated text. | WM_COMMAND |
The following snippet gives a basic idea of how to use this component.
fCOMBOBOX Combo;
Combo.CreateWin(Window, "--Choose One--", ID_CB, cbNormal, cbUsual);
Combo.AddItem("--Choose One--");
Combo.AddItem("Hello!!");
Combo.AddItem("GoodBye!!");
Combo.AddItem("G'Day!");
Combo.AddItem("See you!");
//How do you set the length of the list?
//You may have noticed that there is no function
//for this. Well, the height of the control is
//how you change how many items are in the list.
//Say you have the following line:
Combo.SetSize(100,200);
//The edit portion will not end up 200 pixels high.
//Instead, this will leave the edit portion at it's
//normal height, and make the list drop down 200
//pixels. You see?
| Back to index | The FreeFoote Foundation Classes Documentation |