krpano Documentation

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="..." />
    <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

design	String	"default"
Attribute name	Type	Default value
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 name	Type	Default value
callonclickafterclose	Boolean	false
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)	Type	Default value
selecteditemindex	int
The index (0-n) of the current selected item.
Attribute name	Type	Default value
onchange	String
This event will be called when the current selected item will be changed.
Attribute name (read only)	Type	Default value
item	Array
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 name	Type	Default value
item[itemname].caption	String
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	Type	Default value
item[itemname].onclick	String
This event will be called when clicking the item. Note - see also the callonclickafterclose setting!

Plugin Actions

addComboboxLayer(name, design*)
Action name
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
  - The style for the item elements (textfields).
  - It can contain any textfield settings.

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>

Documentation

Plugins