News Examples Documentation Download Buy Forum Contact
NOTE: This page is from an older version, see the latest version here.

Combobox Plugin combobox.xml Version 1.20.11

  • A combobox / dropdown-list / selectbox plugin.
  • This plugin converts <combobox> elements in the current xml into several internal <layer> container, scrollarea and textfield elements.
  • Additionally it's also possible to add and remove combobox elements also dynamically.
  • The xml-only implementation allows many ways of customizing (design and functionality).
  • Due the xml-only plugin code it works automatically the same for HTML5 and Flash.
  • It's possible to use this plugin as replacement for the old combobox.swf / combobox.js plugins, the action interfaces are the same.

Syntax

First include the combobox.xml file once anywhere in the xml (adjust the path as necessary):
<include url="plugins/combobox.xml" />

Either define the combobox element via static xml code:
<combobox name="cb1" design="default" ...any layer settings...>
    <item name="item1" caption="Item 1" onclick="..." oninit="..." />
    <item name="item2" caption="Item 2" onclick="..." />
    <item name="item3" caption="Item 3" onclick="..." />
</combobox>
That <combobox> element will get converted to a <layer> element on startup. The layer name will be the same. So for the dynamic access to the combobox use layer[name] as addressing.

Or create the combobox element by dynamic action code:
<action name="test">       
    addComboboxLayer(cb1, default);
    set(layer[cb1].align, 'lefttop');
    set(layer[cb1].x, 20);
    set(layer[cb1].y, 20);
    layer[cb1].addItem('Item 1', trace(Item 1 clicked) );
    layer[cb1].addItem('Item 2', trace(Item 2 clicked) );
    layer[cb1].addItem('Item 3', trace(Item 3 clicked) );
</action>

Size / Alignment / Position

  • The combobox can be placed on the screen or within other layers like a normal layer element - e.g. by using the align, edge, x, y and parent settings.
  • If no width is set, the width will be determined automatically by the design settings and the largest item caption.
  • Setting the height is not possible, the height will be always set automatically.

Plugin Attributes / Events

Attribute nameTypeDefault value
designString"default"
  • Select the design for the combobox.
  • Here a predefined design or own custom one can be selected.
  • Available designs are:
    • default - white boxes with a shadow and black text.
    • vtour - vtourskin.xml look, dark-blue background with white text.
  • If no setting or an invalid setting is used, the 'default' design will be used.
  • A custom design can be created by a <combobox_design> element.
    For more please see here: Combobox Custom Designs
Attribute nameTypeDefault value
callonclickaftercloseBooleanfalse
  • Define when the onclick event of the items should be called:
    • true (default) - call onclick delayed after closing the combobox.
    • false - call instantly, this can be necessary when changing browser settings that require a direct user-interaction, e.g. like switching to the fullscreen mode.
Attribute name (read only)TypeDefault value
selecteditemindexint
  • The index (0-n) of the current selected item.
Attribute nameTypeDefault value
onchangeString
  • This event will be called when the current selected item will be changed.
Attribute name (read only)TypeDefault value
itemArray
  • Array of the items, only for read-access.
  • Access by: layer[cbname].item[itemname].*
  • To get the number of items: layer[cbname].item.count
Attribute nameTypeDefault value
item[itemname].captionString
  • The caption text for the item.
  • The item itself is a textfield and so it's possible to use also html/css code here.
Attribute name (read only)TypeDefault value
item[itemname].itemlayernameString
Attribute name (read only)TypeDefault value
item[itemname].itemlayerObject
Attribute nameTypeDefault value
item[itemname].oninitString
  • This event will be called when creating the item.
  • The calling-scope will be item textfield layer element.
  • Could be used to dynamically style the item element on creation.
Attribute nameTypeDefault value
item[itemname].onclickString

Plugin Actions

Action name
addComboboxLayer(name, design*)
  • Add a new combobox layer with the given name and design (*optionally).
Action name
removeComboboxLayer(name)
  • Remove the combobox element.
Action name
layer[name].addItem(caption, onclick)
  • Add a new item to the combobox.
  • An automatic name will be used for the item.
Action name
layer[name].addNamedItem(name, caption, onclick)
  • Add a new item with a given name to the combobox.
Action name
layer[name].selectItem(caption)
  • Select an item by its caption.
Action name
layer[name].selectItemByName(name)
  • Select an item by its item-name.
Action name
layer[name].removeAll()
  • Remove all items from the combobox.
Action name
layer[name].openList()
  • Manually open the combobox list.
Action name
layer[name].closeList()
  • Manually close the combobox list.

Combobox Custom Designs

  • Custom designs can be defined by <combobox_design> elements.
  • They can be defined anywhere in the xml and need an unique name.
  • For using that design, its name need to be used as design parameter.
  • The <combobox_design> element itself has these attributes:
    • margin - layout / item margins (2 by default)
    • open_close_speed - the opening / closing speed in seconds (0.25 by default)
    and needs these three <style> elements within it:
    1. combobox_container_style
      • The style for the basic layer of the combobox (a container layer).
      • It can contain any container layer settings.
    2. combobox_marker_style
      • The style for drop-down / current-item marker (a textfield).
      • It can contain any textfield settings.
    3. combobox_item_style

Here as example the <combobox_design> element of the default design:
<combobox_design name="default" margin="2" open_close_speed="0.25">
    <style name="combobox_container_style"
           bgalpha="1.0"
           bgcolor="0xFFFFFF"
           bgborder="1 0xFFFFFF 0.5"
           bgroundedge="1"
           bgshadow="0 1 3 0x000000 1.0"
           />
    <style name="combobox_marker_style"
           css="color:#FFFFFF;"
           bg="false"
           txtshadow="0 0 2 0x000000 1"
           />
    <style name="combobox_item_style"
           css="color:#222222;"
           padding="4 4"
           bg="false"
           bgcolor="0xC7E4FC"
           bgalpha="1.0"
           bgroundedge="1"
           txtshadow="0 0 1 0xFFFFFF 1.0"
           />
</combobox_design>