  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Nine — Dialog Functions (continued)
This section contains information about the programming elements used with combo boxes. A combo box is a unique type of control, defined by the ‘combobox’ class, that combines much of the functionality of a list box and an edit control. Combo boxes can be created using the COMBOBOX or CONTROL dialog resource statements.
A combo box consists of a list box and a selection field. The list box presents the options that a user can select from, and the selection field displays the current selection. If the selection field is an edit control, the user can enter information not available in the list; otherwise, the user can only select items in the list.
The Windows common controls library includes three main styles of combo box, as shown in the following table:
| Combo box type | Resource Style Constant | Description | ||||
|---|---|---|---|---|---|---|
| Simple | CBS_SIMPLE | Displays the list at all times and shows the selected item in an edit control. | ||||
| Drop-down | CBS_DROPDOWN | Displays the list when the icon is clicked and shows the selected item in an edit control. | ||||
| Drop-down list (drop list) | CBS_DROPDOWNLIST | Displays the list when the icon is clicked and shows the selected item in a static control. |
The following screen shots each show the various kinds of combo boxes as they might appear. In the first screen shot, the user has selected an item in the simple combo box. The user can also type a new value in the edit box of this control. The list has been sized in resource code and is only large enough to accommodate two items.
In the second screen shot, the user has typed new text in the edit control of the drop-down combo box. The user could also have selected an existing item. The list box expands to accommodate as many items as possible.
In the third screen shot, the user has opened the drop-down list combo box. The list box expands to accommodate as many items as possible. The user cannot enter new text.
There are also a number of combo box styles that define specific properties. Combo box styles define specific properties of a combo box. Styles can be combined, however, some styles apply only to certain combo box types. For a table of combo box styles, see Combo Box Styles.
Windows “ownerdraw” and “subclassing” are not supported.
The list box is the portion of a combo box that displays fixed items a user can select. Typically, a script initializes the contents of the list box during the load procedure. Any list item selected by the user is the current selection. Unlike certain list box styles, multiple items cannot be selected. In simple and drop-down combo boxes, the user can type in the selection field instead of selecting a list item. In these cases, there is no current selection, and it is the script’s responsibility to add the item to the list and make it the current selection, as appropriate.
The current selection is the list box item that the user has selected; the selected text appears in the selection field of the combo box. However, in the case of a simple combo box or a drop-down combo box, the current selection is only one form of possible user input in a combo box while the user can also type text in the edit portion of the combo box.
The current selection is identified by the zero-based index of the selected list item. A script can set and retrieve it at any time using the ComboBoxSelectItem and ComboBoxGetSelectIndex functions respectively. The associated dialog ‘action’ procedure receives notification when the user changes the current selection for a combo box.
When a combo box is created, there is no current selection. This is also true for a simple or drop-down combo box if the user has edited the contents of the selection field. To determine the current selection, a script can use the ComboBoxGetSelectIndex function. Note that as the user selects an item, the order of contents of the edit portion is updated after the list portion is selected. Therefore, if the script retrieves the edit field during a selection change notification, it will be out of date.
A drop-down combo box or drop-down list box sends the CBN_CLOSEUP notification code via the action dialog box procedure when the drop-down list closes. If the user changed the current selection, the combo box also sends the CBN_SELCHANGE notification code when the drop-down list closes. To execute a specific process each time the user selects a list item, you can handle either the CBN_SELCHANGE or CBN_CLOSEUP notification code. Typically, you would wait for the CBN_CLOSEUP notification code before processing a change in the current selection. This can be particularly important if a significant amount of processing is required.
A script can also process the CBN_SELENDOK and CBN_SELENDCANCEL notification codes. The system sends CBN_SELENDOK when the user selects a list box item or selects an item and then closes the list box. This indicates that the user has finished and that the selection should be processed. CBN_SELENDCANCEL is sent when the user selects an item, but then selects another control, presses the Escape key while the drop-down list is open, or closes the dialog box. This indicates that the user's selection should be ignored. CBN_SELENDOK is sent before every CBN_SELCHANGE message.
In a simple combo box, the system sends the CBN_DBLCLK notification code when the user double-clicks a list item. In a drop-down combo box or drop-down list, a single click hides the list, so it is not possible to double-click an item.
Certain notifications apply only to combo boxes containing drop-down lists. When a drop-down list is opened or closed, the action procedure receives a notification. If the list box is being opened, the CBN_DROPDOWN is sent; while if the list is being closed, a CBN_CLOSEUP is sent.
A script can open the list of a drop-down combo box or drop-down list box by using the ComboBoxShowDropDown function. [TBD It can determine whether the list is open by using the CB_GETDROPPEDSTATE message and can determine the coordinates of a drop-down list by using the CB_GETDROPPEDCONTROLRECT message]. The script can also retrieve and increase the width of a drop-down list by using the ComboBoxGetDropWidth and ComboBoxSetDropWidth functions, respectively.
When a script creates a combo box, it typically initializes the combo box by adding one or more items to the list box. Later, an application may add or delete list items, reinitialize the list, or retrieve item information from the list.
A script adds list box items to a combo box via a number of functions to add, insert or load the list box section. The specified item is added to the end of the list or, in a sorted combo box, in its correct sorted position based on the item’s string. In an unsorted combo box, an application can use the ComboBoxInsertItem function to insert an item at a specific position. Once added, a list item is identified by its position.
By using the ComboBoxFindItem or ComboBoxFindItemExact functions, a script can determine the position of a list item. ComboBoxFindItem finds an item whose string begins with the specified string while ComboBoxFindItemExact function finds an item whose string matches the string exactly. Neither message is case-sensitive.
A script can remove a list item by using the ComboBoxDeleteItem function. If an application needs to reinitialize the combo box list, it can first clear its entire contents by using the ComboBoxReset function and the add items.
The ComboBoxGetItemText function will associate the string with a list item. To get the number of list box items in a combo box, use the ComboBoxGetItemCount function.
9.15.6 Combo Box — Edit Control
The top or always visible portion of a combo box is the edit control or selection field. A script can retrieve or set the contents of the selection field and can determine or set the edit selection. The script can also limit the amount of text a user can type in the selection field. When the contents of the selection field change, a notification is sent to the action procedure.
To retrieve the content of the selection field, the ComboBoxGetEditText function can be used. To set the contents of the selection field of a simple or drop-down combo box, the ComboBoxSetEditText function is used.
Initially, the amount of text that the user can type into the selection field is limited by the size of the selection field. However, if the combo box has the CBS_AUTOHSCROLL style, the text can continue beyond the size of the selection field. An application can use the CB_LIMITTEXT message to limit the amount of text a user can type into the selection field, regardless of whether the control has the CBS_AUTOHSCROLL style.
When the user edits the content of the selection field, the action procedure receives notification messages. The CBN_EDITUPDATE notification code is sent first, indicating that the text in the selection field has been edited. After the altered text is displayed, the system sends CBN_EDITCHANGE. When the selection field content changes as the result of a list item being selected, these messages are not sent.
9.15.7 Combo Box Notifications and Messages
Notifications are sent via the dialog ‘action’ procedure. The control ID is passed along with the action code. The following table defines the action codes.
| Notification code | Value | Description | ||||
|---|---|---|---|---|---|---|
| CBN_CLOSEUP | 8 | Indicates the list in a drop-down combo box or drop-down list box is about to close. | ||||
| CBN_DBLCLK | 2 | Indicates the user has double-clicked a list item in a simple combo box. | ||||
| CBN_DROPDOWN | 7 | Indicates the list in a drop-down combo box or drop-down list box is about to open. | ||||
| CBN_EDITCHANGE | 5 | Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification code is sent after the altered text is displayed. | ||||
| CBN_EDITUPDATE | 6 | Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification code is sent before the altered text is displayed. | ||||
| CBN_ERRSPACE | -1 | Indicates the combo box cannot allocate enough memory to carry out a request, such as adding a list item. | ||||
| CBN_KILLFOCUS | 4 | Indicates the combo box is about to lose the input focus. | ||||
| CBN_SELCHANGE | 1 | Indicates the current selection has changed. | ||||
| CBN_SELENDCANCEL | 10 | Indicates that the selection made in the drop down list, while it was dropped down, should be ignored. | ||||
| CBN_SELENDOK | 9 | Indicates that the selection made in the drop down list, while it was dropped down, should be accepted. | ||||
| CBN_SETFOCUS | 3 | Indicates the combo box has received the input focus. |
Adding Items:
ComboBoxAddArray — Adds an array of items to the list box portion to the end or in sorted position.
ComboBoxAddItem — Adds item to combo box list box section. Item may be a string or an integer value.
ComboBoxInsertItem — Inserts an item in the list box section at a specified position as a string or integer.
ComboBoxLoadList — Loads the list box portion with items from a string as line, csv or space delimited.
ComboBoxLoadFolder — Loads the list box portion of a combo box with filenames. folders, drives...
ComboBoxSetEditText — Sets the text of the edit control. Does not work with CBS_DROPDOWNLIST style controls.
Content Control:
ComboBoxDeleteItem — Deletes an item from list box section of a combo box at a specified position.
ComboBoxFindItem — Finds string by the first word.
ComboBoxFindItemExact — Finds string as an exact match.
ComboBoxLimitEditSize — Limits the content width of the edit control portion of a combo box.
ComboBoxReset — Resets combo box’s content.
Display:
ComboBoxGetDropWidth — Gets the width of the drop box section of the combo box.
ComboBoxSetDropWidth — Sets the width of combo box’s drop-down list.
ComboBoxShowDropDown — Forces drop-down to appear or disappear.
ControlDisable — Disables specified control.
ControlEnable — Enables specified control.
ControlHide — Hides a specified control.
ControlShow — Shows a specified control (if hidden).
Retrieve Data:
ComboBoxGetArray — Returns an array of the list box items of a combo box.
ComboBoxGetEditText — Gets the content of the edit control component of a combo box.
ComboBoxGetItemCount — Gets the list box item count for a combo box.
ComboBoxGetItemText — Gets the list box item text from combo box at a specified index.
Selections:
ComboBoxGetSelectIndex — Gets the index of the currently selected item within the list box portion of a combo box.
ComboBoxGetSelectString — Gets the string value for the currently selected item within the list box portion of a combo box.
ComboBoxSelectItem — Selects a list box item for a combo box at a zero-based position or by finding a specified string.
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.