Online Help
When you want to present a list of options, but need to do it in a compact and efficient manner, the dropdown list box is your best choice. That's when you need to add the ComboBox object plugin to your AutoPlay Media Studio 5.0 Professional Edition projects!
The ComboBox object gives you the freedom to offer either a standard dropdown list or a "combo" of dropdown list plus a textual user input field, for those times when you don't want to restrict the user to only the list items.
You can control the look and feel of the object with properties such as font face, text color, size and background color. Features such as auto-sort and events for handling item selection and key presses round it all out. As you'd expect, there are ample actions included for adding, removing, inserting and updating the list items at runtime.
Make the combobox selection read-only. (The selected text cannot be edited.)
Make the combobox selection editable. (The selected text can be edited.)
A return character delimited list of the entries you want to appear in the combobox dropdown. For example:
My First Option
My Second Option
My Third Option
Sort the combobox items alphabetically at runtime. If this option is unchecked, combobox items will be displayed in the order they appear at design time or added at runtime.
The font that you want to use for the text. Click the Select Font button to open the Font dialog where you can edit all of the font settings.
The maximum number of lines to display in the combobox dropdown. The dropdown will only expand to the number of current entries up to this maximum. This value must be a number between 0 and 100 (inclusive).
The text color to use for the combobox items. You can click the select button to bring up a color chooser.
The background color to use for the object. You can click the select button to bring up a color chooser.
Fires when the combobox selection changes. The following event variable is automatically set whenever this event is triggered:
(number) The index of the comboxbox item that is being selected. (The first item in the list has an index of 1.)
Fires whenever the combobox has focus and the user presses a key. The following event variables are automatically set whenever this event is triggered:
(number) The ASCII code of the key that was pressed.
(table) A table containing three boolean values that describe which modifier keys were held down while the key was pressed. A modifier key is a key that can be held down while another key is pressed, to "modify" it. There are three true/false values in the table, one for each type of modifier key on the keyboard: shift, ctrl, and alt. You can access these values as e_Modifiers.shift, e_Modifiers.ctrl, and e_Modifiers.alt.
Fires when the combobox receives input focus.
ComboBox.AddItem
ComboBox.DeleteItem
ComboBox.FindItem
ComboBox.GetCount
ComboBox.GetItemData
ComboBox.GetItemText
ComboBox.GetSelected
ComboBox.GetText
ComboBox.InsertItem
ComboBox.ResetContent
ComboBox.SetItemData
ComboBox.SetItemText
ComboBox.SetSelected
ComboBox.SetText
ComboBox.SetUpdate
Adds an item to a combobox object. If the combobox is not sorted, it will be added to the end of the list.
(string) The name of the combobox object.
(string) The item text to display.
(string) The optional item data to associate with the item text. (The default is an empty string "".)
(number) The index (line number) where the item was added. If an error occurs, -1 is returned.
-- Adds a new item with item text "Item One" and no associated data to the
-- combobox object called "Plugin1".
ComboBox.AddItem("Plugin1", "Item One", "");
-- Check to see if any errors occurred calling the ComboBox.AddItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Adds a new item with item text "Item Two" and associated data "C:\\Two.txt"
-- to the combobox object called "Plugin1".
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
-- Check to see if any errors occurred calling the ComboBox.AddItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Removes an item from a combobox object.
(string) The name of the combobox object.
(number) The index (line number) of the item to remove from the combobox object. The first item in the list has an index of 1. You can use an index of -1 to remove the last item in the list.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Removes the item at index 1 from the "Plugin1" combobox object.
ComboBox.DeleteItem("Plugin1", 1);
-- Check to see if any errors occurred calling the ComboBox.DeleteItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Searches through the items in a combobox object for a specific string and returns the index (line number) where it was found.
(string) The name of the combobox object.
(number) The index (line number) to start searching after. The search will begin in the next item in the list. You can use an index of -1 (or variable LB_ALLITEMS) to search all combobox items.
(number) The type of search to perform:
LB_BYTEXT (0) - Search only the item text.
LB_BYDATA (1) - Search only the associated item data.
LB_BYTEXTDATA (2) - Search both the item text and item data.
(string) The string of text to search for in the combobox object. You can use the * and ? wildcards to search for substrings.
(number) The index (line number) of the combobox item where the search text was found. If no items are found, or an error occurs, -1 is returned.
-- Add four new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
ComboBox.AddItem("Plugin1", "Item OneThree", "C:\\OneThree.txt");
ComboBox.AddItem("Plugin1", "Item Four", "C:\\Four.txt");
-- Search all items for any item text containing the text "One" and return its index.
search_result = ComboBox.FindItem("Plugin1", -1, LB_BYTEXT, "*One*");
-- Check to see if any items were found.
if (search_result ~= -1) then
-- Display its index in a dialog.
Dialog.Message("First Item Found", "The first item found was at index "..search_result, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
-- Search for the next item that contains the text "One".
search_result = ComboBox.FindItem("Plugin1", search_result, LB_BYTEXT, "*One*");
-- If another item was found, display a dialog message.
if (search_result ~= -1) then
-- Display its index in a dialog.
Dialog.Message("Second Item Found", "The first item found was at index "..search_result, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
-- If no items were found, notify the user.
else
Dialog.Message("None Found", "There were no items found fitting the search criteria.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
-- Search all items for the first item whose item data is "C:\OneThree.txt".
search_result = ComboBox.FindItem("Plugin1", -1, LB_BYDATA, "C:\\OneThree.txt");
-- If an item was found, display its index. If it wasn't, inform the user.
if (search_result ~= -1) then
Dialog.Message("First Item Data Found", "The first item data found was at index "..search_result, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("None Found", "There waw no item data found fitting the search criteria.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Returns the number of items in a specific combobox object.
(string) The name of the combobox object.
(number) The number of items in the specified combobox object. If there are no items, 0 is returned. If an error occurs, -1 is returned.
-- Get the number of items currently in the "Plugin1" combobox object.
num_items = ComboBox.GetCount("Plugin1");
-- Display the number of items in the combobox.
Dialog.Message("Item Count", "There are currently "..num_items.." items in the combobox.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
-- Add four new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
ComboBox.AddItem("Plugin1", "Item OneThree", "C:\\OneThree.txt");
ComboBox.AddItem("Plugin1", "Item Four", "C:\\Four.txt");
-- Get the number of items currently in the "Plugin1" combobox object.
num_items = ComboBox.GetCount("Plugin1");
-- Display the number of items in the combobox.
Dialog.Message("Item Count", "There are currently "..num_items.." items in the combobox.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
Returns the item data associated to a specific item in a combobox object.
(string) The name of the combobox object.
(number) The index (line number) whose item data you want. You can use an index of -1 to access the last item in the list.
(string) The item data associated to the specified combobox item. If the item does not contain any item data, an empty string ("") is returned.
-- Adds a new item with item text "Item One" and associated data "C:\\One.txt"
-- to the combobox object called "Plugin1".
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
-- Check to see if any errors occurred calling the ComboBox.AddItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Gets the item data of the first item in the combobox object.
item_data = ComboBox.GetItemData("Plugin1", 1);
-- If the item has item data, display its contents, otherwise notify that there was none.
if (item_data ~= "") then
Dialog.Message("Item Data", "The item data in index 1 is "..item_data, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Data", "There is no item data at index 1.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Returns the item text of a specific item in a combobox object.
(string) The name of the combobox object.
(number) The index (line number) of the item whose item text you want. You can use an index of -1 to access the last item in the list.
(string) The item text of the specified item in the combobox. If the specified item has no item text or an error occurs, an empty string ("") is returned.
-- Add two new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
-- Get the item text of the second item in the combobox object.
item_text = ComboBox.GetItemText("Plugin1", 2);
-- If the item is valid display a dialog message. Otherwise display a notification.
if (item_text ~= "") then
Dialog.Message("Item Text", "The item text is '"..item_text.."'.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Text", "The item does not contain any item text.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Returns the index of the selected combobox item.
(string) The name of the combobox object.
(number) The index (line number) of the selected combobox item. If no items are currently selected or an error occurs, -1 is returned.
-- Add four new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
ComboBox.AddItem("Plugin1", "Item OneThree", "C:\\OneThree.txt");
ComboBox.AddItem("Plugin1", "Item Four", "C:\\Four.txt");
-- Gets the index of the selected item.
selected_index = ComboBox.GetSelected("Plugin1");
-- If an item is selected, display it's index, otherwise display a notification message.
if (selected_index ~= -1) then
Dialog.Message("Selected Index","The currently selected item has an index of "..selected_index, MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
Dialog.Message("Selected Index","No items are currently selected.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Returns the text currently displayed in the combobox object.
(string) The name of the combobox object.
(string) The text currently displayed in the specified combobox object. If no text is currently displayed in the combobox or an error occurs, an empty string ("") is returned.
-- Get the text of the item currently in the combobox.
combo_text = ComboBox.GetText("Plugin1");
-- If there is text in the combobox, display a message with its text.
-- If no item is displayed in the combobox, notify the user.
if (combo_text ~= "") then
Dialog.Message("ComboBox Text", "The current text in the combobox is '"..combo_text.."'.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("ComboBox Text", "Currently no text is displayed in the combobox.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Inserts a new item into a combobox object at a specific index. (Note: The item's inserted position will persist even if sorting is enabled.)
(string) The name of the combobox object.
(number) The index (line number) to insert the new item. Use an index of -1 to insert at the end of the list.
(string) The item text to display for the new item.
(string) The optional item data to associate with the new item.
(number) The index (line number) where the item was inserted. If an error occurs, -1 is returned.
-- Add two new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
-- Insert a new item into the combobox at index 2.
ComboBox.InsertItem("Plugin1", 2, "New Item", "New Data");
-- Check to see if any errors occurred calling the ComboBox.InsertItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Removes all items from the specified combobox object.
(string) The name of the combobox object.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Clears all items from the "Plugin1" combobox object.
ComboBox.ResetContent("Plugin1");
Sets the text of a combobox item's associated data.
(string) The name of the combobox object.
(number) The index (line number) whose item data you want to set. Use an index of -1 to access the last item in the list.
(string) The associated item data string to set.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Adds a new item with item text "Item One" and associated data "C:\\One.txt"
-- to the combobox object called "Plugin1".
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
-- Check to see if any errors occurred calling the ComboBox.AddItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Gets the item data of the first item in the combobox object.
item_data = ComboBox.GetItemData("Plugin1", 1);
-- If the item has item data, display its contents, otherwise notify that there was none.
if (item_data ~= "") then
Dialog.Message("Item Data", "The item data in index 1 is "..item_data, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Data", "There is no item data at index 1.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
-- Set the item data of the item at index 1 to "New Data".
ComboBox.SetItemData("Plugin1", 1, "New Data");
-- Check to see if any errors occurred calling the ComboBox.SetItemData action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Gets the item data of the first item in the combobox object.
item_data = ComboBox.GetItemData("Plugin1", 1);
-- If the item has item data, display its contents, otherwise notify that there was none.
if (item_data ~= "") then
Dialog.Message("New Item Data", "The new item data in index 1 is "..item_data, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Data", "There is no item data at index 1.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Sets the item text for a specific item in a combobox object.
(string) The name of the combobox object.
(number) The index (line number) whose item text you want to set. Use an index of -1 to access the last item in the list.
(string) The text to display for the combobox item.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Adds a new item with item text "Item One" and associated data "C:\\One.txt"
-- to the combobox object called "Plugin1".
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
-- Check to see if any errors occurred calling the ComboBox.AddItem action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Gets the item text of the first item in the combobox object.
item_text = ComboBox.GetItemText("Plugin1", 1);
-- If the item has item text, display its contents, otherwise notify that there was none.
if (item_text ~= "") then
Dialog.Message("Item Text", "The item text in index 1 is "..item_text, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Text", "There is no item text at index 1.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
-- Set the item data of the item at index 1 to "New Data".
ComboBox.SetItemText("Plugin1", 1, "New Item Text");
-- Check to see if any errors occurred calling the ComboBox.SetItemText action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Gets the item text of the first item in the combobox object.
item_text = ComboBox.GetItemText("Plugin1", 1);
-- If the item has item text, display its contents, otherwise notify that there was none.
if (item_text ~= "") then
Dialog.Message("New Item Text", "The new item text in index 1 is "..item_text, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("Item Text", "There is no item text at index 1.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
Selects the specified item in the combobox object. This action can also be used to unselect items. To clear the selection, you can use -1 as the index.
(string) The name of the combobox object.
(number) The index (line number) that will be selected. You can use -1 to clear the selection.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Add two new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
-- Set the combobox selection to the item at index 2.
ComboBox.SetSelected("Plugin1", 2);
-- Check to see if any errors occurred calling the ComboBox.SetSelected action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Sets the displayed text in the combobox object. This action only works if your combobox is set as the Dropdown Edit style (instead of Dropdown List).
(string) The name of the combobox object.
(string) The text to display in the combobox.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Add two new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
-- Sets the displayed text in the combobox object.
ComboBox.SetText("Plugin1", "New Text");
-- Check to see if any errors occurred calling the ComboBox.SetText action.
-- If any error occurred, display the error message.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
Sets the enabled/disabled update state of a combobox object. The update state controls whether or not the combobox object will be redrawn to reflect any changes that have been made. When a combobox object's update state is disabled, any actions to modify it will not be visible to the user until this action is called to enable the update state.
(string) The name of the combobox object.
(boolean) Make the combobox object's update state enabled or disabled:
true - Enable the update state of the combobox object. (Default)
false - Disable the update state of the combobox object.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Sets the update state to false.
ComboBox.SetUpdate("Plugin1", false);
-- Add four new items to the "Plugin1" combobox object.
ComboBox.AddItem("Plugin1", "Item One", "C:\\One.txt");
ComboBox.AddItem("Plugin1", "Item Two", "C:\\Two.txt");
ComboBox.AddItem("Plugin1", "Item OneThree", "C:\\OneThree.txt");
ComboBox.AddItem("Plugin1", "Item Four", "C:\\Four.txt");
-- Now that the items have been added, set the update state to true.
ComboBox.SetUpdate("Plugin1", true);
| 0 | (ComboBox.OK) | - | (no error) |
|---|---|---|---|
| 1100 | - | The specified object could not be found. | |
| 77001 | (ComboBox.ERR_ADD_ITEM_FAILED) | - | Could not add item to the ComboBox. |
| 77002 | (ComboBox.ERR_SET_ITEM_DATA_FAILED) | - | An error occured when trying to set the items data. |
| 77003 | (ComboBox.ERR_DELETE_ITEM_FAILED) | - | An error occured when trying to delete the item from the ComboBox. |
| 77004 | (ComboBox.ERR_INDEX_OUT_OF_RANGE) | - | Error index is out of range. |
| 77005 | (ComboBox.ERR_GET_ITEM_TEXT_FAILED) | - | An error occured trying to get the item's text. |
| 77006 | (ComboBox.ERR_INSERT_ITEM_FAILED) | - | Could not insert item into the ComboBox. |
| 77007 | (ComboBox.ERR_SET_ITEM_TEXT_FAILED) | - | An error occured setting the items text. |
| 77008 | (ComboBox.ERR_SET_SELECTION_FAILED) | - | An error occured setting the current selection. |
Indigo Rose Corporation
support.indigorose.com
The ComboBox Object Plugin is copyright © 2003-2004 Indigo Rose Software Design Corporation.
Copyright © 2003-2004 Indigo Rose Software Design Corporation.
All Rights Reserved.