Olympe SDK

Class: DropDown

olympe.ui.std. DropDown

A 'drop down' menu is a UI element that let the user choose one of several choices. The default form features a button and a drop-down list of values.

Example:

const list = new olympe.df.List(String);
list.set("1", "First Choice");
list.set("2", "Second Choice");
list.set("3", "Last Choice");
const dropDown = new olympe.ui.std.DropDown(new Vector2(150, 30), list, new olympe.ui.std.renderer.StringRenderer())
   .setPosition(new Vector2(250, 130))
   .setBorder(3, olympe.df.Color.white())
   .setPlaceholder("Make a choice")
   .onSelectionChanged(
        (key, value) => { console.log(`dropDown selected: ${value}`); }
   );
mainLayout.appendChild(dropDown, 'dropDown');

Before selection: DropDown1 and during selection: DropDown2

Creates an instance of a DropDown.

Parameters:
Name Type Argument Description
dimension olympe.df.PVector2

The dimension (w, h) for this DropDown.
possibleValues olympe.df.Proxy.<olympe.df.Enumerable.<ValueType>> | olympe.df.Enumerable.<ValueType>

List of values.
itemRenderer olympe.ui.std.renderer.ItemRenderer

Renderer to use when displaying the items.
themeClass olympe.df.POString | string <optional>

Theme class name.

Extends

Methods

<protected> _appendChild(child, childId, options)

Append a child to a layer.

Parameters:
Name Type Argument Description
child olympe.df.Proxy.<olympe.ui.std.DockableElement> | olympe.ui.std.DockableElement
childId string

ID of the child (must be unique in this layer)
options * <repeatable>

Can be used if this method is overridden
Inherited From:
Overrides:

<protected> _removeAllChildren()

Inherited From:
Overrides:

<protected> _removeChild(childId)

Remove a child from this layer.

Parameters:
Name Type Description
childId string

ID of the child to remove
Inherited From:
Overrides:

<abstract> appendChild(child, id, options)

Parameters:
Name Type Argument Description
child olympe.df.Proxy.<olympe.ui.std.DockableElement> | olympe.ui.std.DockableElement
id string
options * <repeatable>
Inherited From:
Overrides:
Returns:
Type
olympe.ui.std.Layer

authorizeOverflow()

Authorize the children of this layer to overflow the layer's borders

Inherited From:
Overrides:
Returns:

this

Type
olympe.ui.std.Layer

getFocus()

Checks whether this Element has the focus.

Warning: Focus may not be applicable on some elements, depending on the platform.

Inherited From:
Overrides:
Returns:

true if Element has focus.

Type
olympe.df.POBoolean

<protected> getGestureEvent()

Gets the gesture event manager attached to this element

Inherited From:
Overrides:
Returns:
Type
olympe.ui.events.GestureEventManager

getHeight()

Gets the height of this element.

Inherited From:
Overrides:
See:
Returns:

the height of this element.

Type
olympe.df.PONumber

getHTMLElement()

Return the DOM HTMLElement if exists (may be null)

Inherited From:
Overrides:
Returns:
Type
Element

<protected> getMouseEvent()

Gets the mouse event manager attached to this element.

Inherited From:
Overrides:
Returns:

the mouse event manager.

Type
olympe.ui.events.MouseEventManager

getParent()

Gets the parent, or container, of this element.

Inherited From:
Overrides:
Returns:

the parent of this element.

Type
olympe.ui.std.Element | olympe.df.Proxy

getPlaceholderLabel()

Gets the Label used to display placeholder.

Returns:
Type
olympe.ui.std.Label

getPosition()

Gets the position (x,y) for this element.

Inherited From:
Overrides:
Returns:

Position of this element.

Type
olympe.df.PVector2

getPossibleValues()

Gets all the possible values for that DropDown.

Returns:

The values.

Type
olympe.df.Enumerable.<ValueType>

getSelectedKeyInternal()

Gets the current selected key.

Returns:

The key.

Type
olympe.df.POString

getSelectedValueInternal()

Gets the current selected value.

Returns:

The value of the current selection.

Type
olympe.df.Proxy.<ValueType>

getUIProxyDockableElement()

Note: needs to be public because it is called by RootElement !

Inherited From:
Overrides:
Returns:

The proxy element from the UI thread

Type
olympe.uiapi.std.DockableElement

<protected> getUIProxyElement()

Returns the native UI element associated with this Element.

Inherited From:
Overrides:
Returns:

The proxy element from the UI thread.

Type
olympe.uiapi.std.Element

<protected> getUIProxyLayer()

Inherited From:
Overrides:
Returns:

Proxified UI object Layer

Type
olympe.uiapi.std.Layer

getWidth()

Gets the width of this element.

Inherited From:
Overrides:
See:
Returns:

the width of this element.

Type
olympe.df.PONumber

getX()

Gets the x coordinate of the position of this element.

Inherited From:
Overrides:
See:
Returns:

the x coordinate for this element.

Type
olympe.df.PONumber

getY()

Gets the y coordinate of the position of this element.

Inherited From:
Overrides:
See:
Returns:

the y coordinate for this element.

Type
olympe.df.PONumber

hasSelection()

Checks whether this DropDown has an entry selected.

Returns:

true if a selection has been made, false otherwise.

Type
olympe.df.POBoolean

isHidden()

Checks whether this Element is hidden.

Inherited From:
Overrides:
Returns:

true is this element is hidden.

Type
olympe.df.POBoolean

isListExpanded()

Returns true if the dropdown is expanded, i.e. if the selection list is visible

Returns:
Type
olympe.df.POBoolean

offSelectionChanged(id)

Unregisters a callback previously registered by olympe.ui.std.DropDown#onSelectionChanged.

Parameters:
Name Type Description
id string

The ID of the callback.

onSelectionChanged(callbackFunc [, id])

Registers a callback to be called when the selection changes. The callback will be called with the selected key and value as parameter, IN A CONTEXT corresponding to this pair.

Parameters:
Name Type Argument Description
callbackFunc olympe.ui.std.DropDown.OnSelectionChanged

The function to call.
id string <optional>

The ID for this callback. A unique one will be generated if omitted.
Returns:

The ID of the callback.

Type
string

refreshSize()

Refresh component internal size

Inherited From:
Overrides:

<abstract> removeChild(id)

Parameters:
Name Type Description
id string
Inherited From:
Overrides:
Returns:
Type
olympe.ui.std.Layer

removeTooltip()

Removes the tooltip from this element.

Inherited From:
Overrides:
Returns:

This element.

Type
olympe.ui.std.Element

setAccelerated(accelerated)

Sets whether this DockableElement movements should be calculated by the GPU.

Note: This function doesn't guarantee that the implementation will support GPU acceleration.

Parameters:
Name Type Description
accelerated olympe.df.POBoolean | olympe.df.Node | boolean

true if this DockableElement movements should be calculated by the GPU.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setArrowIconPaddingRight(padding)

Sets the right padding of the arrow icon, wrt the dropdown dimension

Parameters:
Name Type Description
padding olympe.df.PONumber
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setArrowIconPosition(arrowIconPosition)

Sets the position of the arrow icon within the boundaries of the DropDown box.

Parameters:
Name Type Description
arrowIconPosition olympe.df.PVector2

The position (x,y).
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setArrowIconSize(arrowIconSize)

Sets the size for the arrow icon, or its replacement.

Parameters:
Name Type Description
arrowIconSize olympe.df.PVector2

the size (width, height).
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setArrowIconUrl(arrowIconUrl)

Sets the icon to use in place of the arrow.

Parameters:
Name Type Description
arrowIconUrl olympe.df.POString

The URL for the replacement icon.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setBackgroundColor(color)

Sets the background color for this Element.

Parameters:
Name Type Description
color olympe.df.Proxy | olympe.df.Node | olympe.df.Color

The background color.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImage(url [, sizingMode] [, positioningMode] [, size] [, position])

Sets the background image for this Element.

Notes:

  • The size is ignored if the sizing mode is not set to MANUAL.
  • The position is ignored if the positioning mode is not set to MANUAL.
Parameters:
Name Type Argument Default Description
url olympe.df.POString | olympe.df.Node | string

URL for the image.
sizingMode olympe.ui.common.BackgroundImageSize | olympe.df.Proxy | olympe.df.Node <optional>
 AUTO

The sizing mode for the image.
positioningMode olympe.ui.common.BackgroundImagePosition | olympe.df.Proxy | olympe.df.Node <optional>
 TOPLEFT

The positioning mode for this image.
size olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node <optional>

Size, in pixel.
position olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node <optional>

Position of the image, in pixel. (0,0) if omitted.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImagePosition(position)

Sets the background image position for this Element.

Parameters:
Name Type Description
position olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node

The position.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImagePositionMode(positionMode)

Sets the position mode for the background image of this Element.

Parameters:
Name Type Description
positionMode olympe.ui.common.BackgroundImagePosition | olympe.df.Proxy | olympe.df.Node

The positioning mode for this image.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImageSize(size)

Sets the background image size for the this Element.

Parameters:
Name Type Description
size olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node

The image size, in pixels.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImageSizeMode(sizeMode)

Sets the sizing mode for the background image of this Element.

Parameters:
Name Type Description
sizeMode olympe.ui.common.BackgroundImageSize | olympe.df.Proxy | olympe.df.Node

The sizing mode.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBackgroundImageSrc(src)

Sets the URL (or source) for the background image.

Parameters:
Name Type Description
src olympe.df.POString | olympe.df.Node | string

URL for the image.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBlur()

Removes focus from this Element.

Warnings:

  • Focus may not be applicable on some elements, depending on the platform.
  • Elements not inside a container (screen, etc.) can't get the focus.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setBorder(width, color)

Sets the border width & color for this element. a width of 0 means no visible border.

Parameters:
Name Type Description
width olympe.df.ONumber | number | olympe.df.Node | olympe.df.Proxy

the width, in pixels, for the border
color olympe.df.Color | olympe.df.Node | olympe.df.Proxy

the color for the border
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setBorderColor(color)

Set the border color on this element.

Parameters:
Name Type Description
color olympe.df.Color | olympe.df.Proxy.<olympe.df.Color>
Inherited From:
Overrides:
Returns:
Type
olympe.ui.std.DockableElement

setBorderWidth(width)

Set the border width on this element. a width of 0 means no visible border.

Parameters:
Name Type Description
width number | olympe.df.PONumber
Inherited From:
Overrides:
Returns:
Type
olympe.ui.std.DockableElement

setContextMenuEnabled(enabled)

Enable/disable context menu on this element.

Parameters:
Name Type Description
enabled boolean

true to enable the context menu, false to disable it.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setCornerRadius(radius)

Sets the rounded corner radius (in pixels) for this element.

Parameters:
Name Type Description
radius olympe.df.PONumber | olympe.df.Node | number

Radius in pixels.
Inherited From:
Overrides:
Returns:

this DockableElement.

Type
olympe.ui.std.DockableElement

setDimension(dimension)

Sets the dimension (width, height) for this element.

Parameters:
Name Type Description
dimension olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node

Dimension of this element.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setDisplayOnTop(value)

Sets the value of the display top boolean, to know wether or not the list should be displayed on top of the dropdown

Parameters:
Name Type Description
value olympe.df.POBoolean
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setExpanded(expanded)

Sets the right padding of the arrow icon, wrt the dropdown dimension

Parameters:
Name Type Description
expanded olympe.df.POBoolean | olympe.df.OBoolean
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setFocus()

Gives the focus to this Element.

Warnings:

  • Focus may not be applicable on some elements, depending on the platform.
  • Elements not inside a container (screen, etc.) can't get the focus.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setHidden(hidden)

Sets whether this Element is hidden or not. A hidden element will not appear on the screen.

Parameters:
Name Type Description
hidden olympe.df.POBoolean | boolean | olympe.df.Node

true if content must be hidden, false otherwise.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setIgnoreUserInteraction( [ignore])

Disables mouse events for this element. However, mouse events will target its descendants unless they are manually set to also ignore user interactions.

Parameters:
Name Type Argument Default Description
ignore boolean | olympe.df.POBoolean <optional>
 false

ignore true to make this element ignore mouse events and pass them to its children.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setItemThemeClass(itemThemeClass)

Sets the theme class for items in the list.

Parameters:
Name Type Description
itemThemeClass olympe.df.POString | string

Theme class name.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setListCornerRadius(radius)

Sets the corner radius of the elements list

Parameters:
Name Type Description
radius olympe.df.PONumber
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setListOffset(offset)

Sets the offset, in pixels, to be applied when displaying the dropdown list. Default is (0, 0).

Parameters:
Name Type Description
offset olympe.df.PVector2

The offset (x,y) to apply.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setMouseOverItemThemeClass(mouseOverItemThemeClass)

Sets the theme class for the items in the list when mouse are over it.

Parameters:
Name Type Description
mouseOverItemThemeClass olympe.df.POString | string

Theme class name.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setOpacity(opacity)

Sets the opacity, or alpha channel, for this Element. This is a float value between 0 and 1. 0 being transparent and 1 being opaque.

Parameters:
Name Type Description
opacity olympe.df.ONumber | number | olympe.df.Proxy | olympe.df.Node

the opacity (between 0 and 1).
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setPaddingBottom(paddingBottom)

Sets the padding to apply to the bottom of the selected value container (not the list).

Parameters:
Name Type Description
paddingBottom olympe.df.PONumber | number

The padding, in pixels, to apply.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setPaddingLeft(paddingLeft)

Sets the padding to apply to the left of the selected value container (not the list).

Parameters:
Name Type Description
paddingLeft olympe.df.PONumber | number

The padding, in pixels, to apply.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setPaddingRight(paddingRight)

Sets the padding to apply to the right of the selected value container (not the list).

Parameters:
Name Type Description
paddingRight olympe.df.PONumber | number

The padding, in pixels, to apply.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setPaddingTop(paddingTop)

Sets the padding to apply to the top of the selected value container (not the list).

Parameters:
Name Type Description
paddingTop olympe.df.PONumber | number

The padding, in pixels, to apply.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setParent(parent)

Sets the parent of this element.

Important: This method must be called when this element is added to a container or layout.

Parameters:
Name Type Description
parent olympe.df.Proxy.<olympe.ui.std.Element> | olympe.ui.std.Element

The parent for this element.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setPlaceholder(placeholder)

Sets the placeholder text to display in the selection box.

Parameters:
Name Type Description
placeholder olympe.df.POString | string

The text to use as a placeholder.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setPlaceholderThemeClass(placeholderThemeClass)

Sets the theme class for the place holder item.

Parameters:
Name Type Description
placeholderThemeClass olympe.df.POString | string

theme class name.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setPosition(position)

Sets the position (x,y) for this Element.

Parameters:
Name Type Description
position olympe.df.Vector2 | olympe.df.Proxy | olympe.df.Node

The position of this element.
Inherited From:
Overrides:
Returns:

this DockableElement.

Type
olympe.ui.std.DockableElement

setRotationAngle(angle)

Sets the rotation angle (in degree) for this element.

Parameters:
Name Type Description
angle olympe.df.ONumber | number | olympe.df.Node | olympe.df.Proxy

the angle, in degree.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setScale(scale)

Sets the scaling factor for the width and height of this element.

Parameters:
Name Type Description
scale olympe.df.PVector2 | olympe.df.Node

scaling vector (w, h).
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setSelectedKey(key)

Sets the selected item by providing its key.

Parameters:
Name Type Description
key olympe.df.POString | string

The key.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setSelectedValueThemeClass(selectedValueThemeClass)

Sets the theme class for the selected value.

Parameters:
Name Type Description
selectedValueThemeClass olympe.df.POString | string

Theme class name.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setShadow( [offset] [, radius] [, spread] [, color] [, inset])

Set shadow on this DockableElement. A shadow is defined by its offset, the blur radius, the spread radius (all in pixels) and a base color. A shadow is by default 'external, but can be made internal by setting the 'inset' parameter to true`.

Parameters:
Name Type Argument Default Description
offset olympe.df.Vector2 | olympe.df.Node | olympe.df.Proxy.<olympe.df.Vector2> <optional>
 0

Offset in pixels.
radius olympe.df.PONumber | olympe.df.Node | number <optional>
 0

Blur radius in pixels.
spread olympe.df.PONumber | olympe.df.Node | number <optional>
 0

Spread in pixels.
color olympe.df.Color | olympe.df.Node | olympe.df.Proxy.<olympe.df.Color> <optional>
 '#000000'

Shadow color.
inset olympe.df.POBoolean | olympe.df.Node | boolean <optional>
 false

true if the shadow is inset.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setShadowPSStyle(color, angle, distance, spread, size, inset)

Set shadow on this DockableElement as done in Photoshop.

Parameters:
Name Type Description
color olympe.df.Color | olympe.df.Node | olympe.df.Proxy.<olympe.df.Color>

Shadow Color.
angle olympe.df.PONumber | olympe.df.Node | number

Angle, in radians.
distance olympe.df.PONumber | olympe.df.Node | number

Distance, in pixels.
spread olympe.df.PONumber | olympe.df.Node | number

Spread in pixels.
size olympe.df.PONumber | olympe.df.Node | number

Size, in pixels.
inset olympe.df.POBoolean | olympe.df.Node | boolean

true if the shadow is inset.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setSpaceArrowSelectedValue(spaceArrowSelectedValue)

Sets the space, in pixels, between the arrow icon and the selected value.

Parameters:
Name Type Description
spaceArrowSelectedValue olympe.df.PONumber

Space in pixels.
Returns:

this DropDown.

Type
olympe.ui.std.DropDown

setStyle(style, value)

Parameters:
Name Type Description
style string

CSS style name
value string | number

CSS style value
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setTabIndex(tabIndex)

Sets the tab index to this Element. Tab Index defines the tabulation or 'next' order while going through a form.

Parameters:
Name Type Description
tabIndex olympe.df.PONumber | olympe.df.ONumber | number | olympe.df.Node

The tab index.
Inherited From:
Overrides:
Returns:

this Element.

Type
olympe.ui.std.Element

setThemeClass(themeClass)

Method to override if this dockable element supports themes.

Parameters:
Name Type Description
themeClass olympe.df.POString | olympe.df.Node | string

The theme class.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setTooltip(text [, options])

Assigns a tooltip to that element that will show up when the mouse hovers over it.

Parameters:
Name Type Argument Description
text olympe.df.POString

The text of the tooltip.
options Object <optional>

Various options for displaying the tooltip.

Properties
Name Type Argument Description
position olympe.df.PVector2 <optional>

The absolute position of the tooltip.
background olympe.df.PColor <optional>

The background color.
foreground olympe.df.PColor <optional>

The text color.
fontSize olympe.df.PONumber <optional>

The font size.
borderSize olympe.df.PONumber <optional>

The size of the border. Default is 1.
borderColor olympe.df.PColor <optional>

The color of the border. Default is black.
delay olympe.df.ONumber | number <optional>

The delay, in milliseconds, before showing the tooltip. Default is 500.
startingPos olympe.df.Vector2 <optional>

The starting position of the mouse. Default is (0,0).
theme olympe.df.POString <optional>

The theme class to apply to this tooltip.
Inherited From:
Overrides:
Returns:

This Element.

Type
olympe.ui.std.Element

setUniformScale(scale)

Sets the scaling factor for this element.

Parameters:
Name Type Description
scale olympe.df.PONumber | olympe.df.Node | number

The scaling factor.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

setZIndex(zIndex)

Sets the z-index for this element. This determines how elements are layered when they overlap on the screen. Higher Z-index elements are placed on top of lower Z-index elements.

Parameters:
Name Type Description
zIndex olympe.df.PONumber | olympe.df.Node | number

Index of element on z axis.
Inherited From:
Overrides:
Returns:

This DockableElement.

Type
olympe.ui.std.DockableElement

Type Definitions

OnSelectionChanged()

olympe.ui.std.DropDown.OnSelectionChanged(key, value)