Class: FieldDropdown

Blockly.FieldDropdown

class   static

Constructor

FieldDropdown

new FieldDropdown(menuGenerator, opt_validator, opt_config)

Class for an editable dropdown field.

Parameter
menuGenerator	(non-null Array of non-null Array or non-null function()) A non-empty array of options for a dropdown list, or a function which generates these options.
opt_validator	Optional function() A function that is called to validate changes to the field's value. Takes in a language-neutral dropdown option & returns a validated language-neutral dropdown option, or null to abort the change.
opt_config	Optional Object A map of options used to configure the field. See the field creation documentation for a list of properties this parameter supports.

Extends

Blockly.Field

Throws

TypeError If menuGenerator options are incorrectly structured.

Properties

ARROW_CHAR

static

Android can't (in 2014) display "▾", so use "▼" instead.

CHECKMARK_OVERHANG

static

Horizontal distance that a checkmark overhangs the dropdown.

MAX_MENU_HEIGHT_VH

static

Maximum height of the dropdown menu, as a percentage of the viewport height.

arrow_

non-null SVGTSpanElement

borderRect_

protected

unknown

The rendered field's SVG border element.

Inherited from

Blockly.Field#borderRect_

clickTarget_

protected

unknown

The element the click handler is bound to.

Inherited from

Blockly.Field#clickTarget_

constants_

protected

unknown

Constants associated with the source block's renderer.

Inherited from

Blockly.Field#constants_

CURSOR

Mouse cursor style when over the hotspot that initiates the editor.

DEFAULT_VALUE

protected

unknown

The default value for this field.

Inherited from

Blockly.Field#DEFAULT_VALUE

disposed

package

unknown

Has this field been disposed of?

Inherited from

Blockly.Field#disposed

EDITABLE

unknown

Editable fields usually show some sort of UI indicating they are editable. They will also be saved by the XML renderer.

Inherited from

Blockly.Field#EDITABLE

enabled_

protected

unknown

Can the field value be changed using the editor on an editable block?

Inherited from

Blockly.Field#enabled_

fieldGroup_

protected

unknown

The rendered field's SVG group element.

Inherited from

Blockly.Field#fieldGroup_

isDirty_

protected

unknown

Does this block need to be re-rendered?

Inherited from

Blockly.Field#isDirty_

maxDisplayLength

unknown

Maximum characters of text to display before adding an ellipsis.

Inherited from

Blockly.Field#maxDisplayLength

menu_

protected

nullable Blockly.Menu

The dropdown menu.

menu_

non-null Blockly.Menu

menuGenerator_

protected

(non-null Array of non-null Array or non-null function(this = FieldDropdown) returns non-null Array of non-null Array)

An array of options for a dropdown list, or a function which generates these options.

menuGenerator_

non-null Array of non-null Array of string

name

unknown

Name of field. Unique within each block. Static labels are usually unnamed.

Inherited from

Blockly.Field#name

prefixField

package

nullable string

The prefix field label, of common words set after options are trimmed.

SERIALIZABLE

boolean

Serializable fields are saved by the XML renderer, non-serializable fields are not. Editable fields should also be serializable.

size_

protected

unknown

The size of the area rendered by the field.

Inherited from

Blockly.Field#size_

sourceBlock_

protected

unknown

Block this field is attached to. Starts as null, then set in init.

Inherited from

Blockly.Field#sourceBlock_

suffixField

package

nullable string

The suffix field label, of common words set after options are trimmed.

textContent_

protected

unknown

The rendered field's text content element.

Inherited from

Blockly.Field#textContent_

textElement_

non-null Element

validator_

protected

unknown

Validation function called when user edits an editable field.

Inherited from

Blockly.Field#validator_

value_

protected

unknown

A generic value possessed by the field. Should generally be non-null, only null when the field is created.

Inherited from

Blockly.Field#value_

visible_

protected

unknown

Is the field visible, or hidden due to the block being collapsed?

Inherited from

Blockly.Field#visible_

Methods

applyTrim_

static

applyTrim_(options, prefixLength, suffixLength) returns Array of non-null Array

Use the calculated prefix and suffix lengths to trim all of the options in the given array.

Parameter
options	Array of non-null Array Array of option tuples: (human-readable text or image, language-neutral name). Value must not be null.
prefixLength	number The length of the common prefix.
suffixLength	number The length of the common suffix

Returns

non-null Array of non-null Array A new array with all of the option text trimmed.

fromJson

package   static

fromJson(options) returns Blockly.FieldDropdown

Construct a FieldDropdown from a JSON arg object.

Parameter
options	Object A JSON object with options (options). Value must not be null.

Returns

non-null Blockly.FieldDropdown The new field instance.

applyColour

package

applyColour()

Updates the dropdown arrow to match the colour/style of the block.

bindEvents_

protected

bindEvents_()

Bind events to the field. Can be overridden by subclasses if they need to do custom input handling.

Inherited from

Blockly.Field#bindEvents_

configure_

protected

configure_(config)

Process the configuration map passed to the field.

Parameter
config	A map of options used to configure the field. See the individual field's documentation for a list of properties this parameter supports. Value must not be null.

Inherited from

Blockly.Field#configure_

createBorderRect_

protected

createBorderRect_()

Create a field border rect element. Not to be overridden by subclasses. Instead modify the result of the function inside initView, or create a separate function to call.

Inherited from

Blockly.Field#createBorderRect_

createSVGArrow_

protected

createSVGArrow_()

Create an SVG based arrow.

createTextArrow_

protected

createTextArrow_()

Create a tspan based arrow.

createTextElement_

protected

createTextElement_()

Create a field text element. Not to be overridden by subclasses. Instead modify the result of the function inside initView, or create a separate function to call.

Inherited from

Blockly.Field#createTextElement_

dispose

package

dispose()

Dispose of all DOM objects and events belonging to this editable field.

Inherited from

Blockly.Field#dispose

doClassValidation_

protected

doClassValidation_(opt_newValue) returns string

Ensure that the input value is a valid language-neutral option.

Parameter
opt_newValue	Optional any type The input value.

Returns

nullable string A valid language-neutral option, or null if invalid.

doValueInvalid_

protected

doValueInvalid_(_invalidValue)

Used to notify the field an invalid value was input. Can be overridden by subclasses, see FieldTextInput. No-op by default.

Parameter
_invalidValue	The input value that was determined to be invalid.

Inherited from

Blockly.Field#doValueInvalid_

doValueUpdate_

protected

doValueUpdate_(newValue)

Update the value of this dropdown field.

Parameter
newValue	any type The value to be saved. The default validator guarantees that this is one of the valid dropdown options.

forceRerender

package

forceRerender()

Force a rerender of the block that this field is installed on, which will rerender this field and adjust for any sizing changes. Other fields on the same block will not rerender, because their sizes have already been recorded.

Inherited from

Blockly.Field#forceRerender

fromXml

package

fromXml(fieldElement)

Sets the field's value based on the given XML element. Should only be called by Blockly.Xml.

Parameter
fieldElement	Element The element containing info about the field's state. Value must not be null.

getAbsoluteXY_

protected

getAbsoluteXY_() returns Blockly.utils.Coordinate

Return the absolute coordinates of the top-left corner of this field. The origin (0,0) is the top-left corner of the page body.

Inherited from

Blockly.Field#getAbsoluteXY_

Returns

Object with .x and .y properties.

getClickTarget_

protected

getClickTarget_() returns Element

The element to bind the click handler to. If not set explicitly, defaults to the SVG root of the field. When this element is clicked on an editable field, the editor will open.

Inherited from

Blockly.Field#getClickTarget_

Returns

Element to bind click handler to.

getConstants

getConstants() returns Blockly.blockRendering.ConstantProvider

Get the renderer constant provider.

Inherited from

Blockly.Field#getConstants

Returns

The renderer constant provider.

getDisplayText_

protected

getDisplayText_() returns string

Get the text from this field to display on the block. May differ from getText due to ellipsis, and other formatting.

Inherited from

Blockly.Field#getDisplayText_

Returns

Text to display.

getFlipRtl

getFlipRtl() returns boolean

Returns whether or not we should flip the field in RTL.

Inherited from

Blockly.Field#getFlipRtl

Returns

True if we should flip in RTL.

getOptions

getOptions(opt_useCache) returns Array of non-null Array

Return a list of the options for this dropdown.

Parameter
opt_useCache	Optional boolean For dynamic options, whether or not to use the cached options or to re-generate them.

Throws

TypeError If generated options are incorrectly structured.

Returns

non-null Array of non-null Array A non-empty array of option tuples: (human-readable text or image, language-neutral name).

getParentInput

package

getParentInput() returns Blockly.Input

Search through the list of inputs and their fields in order to find the parent input of a field.

Inherited from

Blockly.Field#getParentInput

Returns

The input that the field belongs to.

getScaledBBox

package

getScaledBBox() returns Blockly.utils.Rect

Returns the bounding box of the rendered field, accounting for workspace scaling.

Inherited from

Blockly.Field#getScaledBBox

Returns

An object with top, bottom, left, and right in pixels relative to the top left corner of the page (window coordinates).

getSize

getSize() returns Blockly.utils.Size

Returns the height and width of the field.

This should in general be the only place render_ gets called from.

Inherited from

Blockly.Field#getSize

Returns

Height and width.

getSourceBlock

getSourceBlock() returns Blockly.Block

Get the block this field is attached to.

Inherited from

Blockly.Field#getSourceBlock

Implements

Blockly.IASTNodeLocationWithBlock#getSourceBlock

Returns

The block containing this field.

getSvgRoot

getSvgRoot() returns SVGGElement

Gets the group element for this editable field. Used for measuring the size and for positioning.

Inherited from

Blockly.Field#getSvgRoot

Returns

The group element.

getText

getText() returns string

Get the text from this field.

Inherited from

Blockly.Field#getText

Returns

Current text.

getText_

protected

getText_() returns string

Use the getText_ developer hook to override the field's text representation. Get the selected option text. If the selected option is an image we return the image alt text.

Inherited from

Blockly.FieldDropdown#getText_

Returns

Selected option text.

getTooltip

getTooltip() returns string

Returns the tooltip text for this field.

Inherited from

Blockly.Field#getTooltip

Returns

The tooltip text for this field.

getValidator

getValidator() returns function()

Gets the validation function for editable fields, or null if not set.

Inherited from

Blockly.Field#getValidator

Returns

Validation function, or null.

getValue

getValue() returns any type

Get the current value of the field.

Inherited from

Blockly.Field#getValue

Returns

Current value.

init

package

init()

Initialize everything to render this field. Override methods initModel and initView rather than this method.

Inherited from

Blockly.Field#init

initModel

package

initModel()

Initializes the model of the field after it has been installed on a block. No-op by default.

Inherited from

Blockly.Field#initModel

initView

package

initView()

Create the block UI for this dropdown.

isClickable

isClickable() returns boolean

Check whether this field defines the showEditor_ function.

Inherited from

Blockly.Field#isClickable

Returns

Whether this field is clickable.

isCurrentlyEditable

isCurrentlyEditable() returns boolean

Check whether this field is currently editable. Some fields are never EDITABLE (e.g. text labels). Other fields may be EDITABLE but may exist on non-editable blocks or be currently disabled.

Inherited from

Blockly.Field#isCurrentlyEditable

Returns

Whether this field is currently enabled, editable and on an editable block.

isEnabled

isEnabled() returns boolean

Check whether this field's value can be changed using the editor when the source block is editable.

Inherited from

Blockly.Field#isEnabled

Returns

Whether this field is enabled.

isOptionListDynamic

isOptionListDynamic() returns boolean

Returns

boolean True if the option list is generated by a function. Otherwise false.

isSerializable

isSerializable() returns boolean

Check whether this field should be serialized by the XML renderer. Handles the logic for backwards compatibility and incongruous states.

Inherited from

Blockly.Field#isSerializable

Returns

Whether this field should be serialized or not.

isTabNavigable

isTabNavigable() returns boolean

Returns whether or not the field is tab navigable.

Inherited from

Blockly.Field#isTabNavigable

Returns

True if the field is tab navigable.

isVisible

isVisible() returns boolean

Gets whether this editable field is visible or not.

Inherited from

Blockly.Field#isVisible

Returns

True if visible.

loadLegacyState

loadLegacyState(callingClass, state) returns boolean

Loads the given state using either the old XML hoooks, if they should be used. Returns true to indicate loading has been handled, false otherwise.

Parameter
callingClass	The class calling this method. Used to see if this has overridden any relevant hooks.
state	The state to apply to the field.

Inherited from

Blockly.Field#loadLegacyState

Returns

Whether the state was applied or not.

loadState

package

loadState(state)

Sets the field's value based on the given state.

Parameter
state	The state to apply to the dropdown field.

Inherited from

Blockly.FieldDropdown#loadState

markDirty

package

markDirty()

Force a rerender of the block that this field is installed on, which will rerender this field and adjust for any sizing changes. Other fields on the same block will not rerender, because their sizes have already been recorded.

Inherited from

Blockly.Field#markDirty

onItemSelected_

protected

onItemSelected_(menu, menuItem)

Handle the selection of an item in the dropdown menu.

Parameter
menu	Blockly.Menu The Menu component clicked. Value must not be null.
menuItem	Blockly.MenuItem The MenuItem selected within menu. Value must not be null.

onMouseDown_

protected

onMouseDown_(e)

Handle a mouse down event on a field.

Parameter
e	Mouse down event. Value must not be null.

Inherited from

Blockly.Field#onMouseDown_

onShortcut

public

onShortcut(_shortcut) returns boolean

Handles the given keyboard shortcut.

Parameter
_shortcut	The shortcut to be handled. Value must not be null.

Inherited from

Blockly.Field#onShortcut

Implements

Blockly.IKeyboardAccessible#onShortcut

Returns

True if the shortcut has been handled, false otherwise.

positionBorderRect_

protected

positionBorderRect_()

Position a field's border rect after a size change.

Inherited from

Blockly.Field#positionBorderRect_

positionTextElement_

protected

positionTextElement_(xOffset, contentWidth)

Position a field's text element after a size change. This handles both LTR and RTL positioning.

Parameter
xOffset	x offset to use when positioning the text element.
contentWidth	The content width.

Inherited from

Blockly.Field#positionTextElement_

referencesVariables

package

referencesVariables() returns boolean

Whether this field references any Blockly variables. If true it may need to be handled differently during serialization and deserialization. Subclasses may override this.

Inherited from

Blockly.Field#referencesVariables

Returns

True if this field has any variable references.

render_

protected

render_()

Draws the border with the correct width.

saveLegacyState

protected

saveLegacyState(callingClass) returns string

Returns a stringified version of the XML state, if it should be used. Otherwise this returns null, to signal the field should use its own serialization.

Parameter
callingClass	The class calling this method. Used to see if this has overridden any relevant hooks.

Inherited from

Blockly.Field#saveLegacyState

Returns

The stringified version of the XML state, or null.

saveState

package

saveState(_doFullSerialization) returns any type

Saves this fields value as something which can be serialized to JSON. Should only be called by the serialization system.

Parameter
_doFullSerialization	Optional If true, this signals to the field that if it normally just saves a reference to some state (eg variable fields) it should instead serialize the full state of the thing being referenced.

Inherited from

Blockly.Field#saveState

Returns

JSON serializable state.

setCursorSvg

package

setCursorSvg(cursorSvg)

Add the cursor SVG to this fields SVG group.

Parameter
cursorSvg	The SVG root of the cursor to be added to the field group.

Inherited from

Blockly.Field#setCursorSvg

Implements

Blockly.IASTNodeLocationSvg#setCursorSvg

setEnabled

setEnabled(enabled)

Set whether this field's value can be changed using the editor when the source block is editable.

Parameter
enabled	True if enabled.

Inherited from

Blockly.Field#setEnabled

setMarkerSvg

package

setMarkerSvg(markerSvg)

Add the marker SVG to this fields SVG group.

Parameter
markerSvg	The SVG root of the marker to be added to the field group.

Inherited from

Blockly.Field#setMarkerSvg

Implements

Blockly.IASTNodeLocationSvg#setMarkerSvg

setSourceBlock

setSourceBlock(block)

Attach this field to a block.

Parameter
block	The block containing this field. Value must not be null.

Inherited from

Blockly.Field#setSourceBlock

setTooltip

setTooltip(newTip)

Sets the tooltip for this field.

Parameter
newTip	The text for the tooltip, a function that returns the text for the tooltip, a parent object whose tooltip will be used, or null to display the tooltip of the parent block. To not display a tooltip pass the empty string. Value may be null.

Inherited from

Blockly.Field#setTooltip

setValidator

setValidator(handler)

Sets a new validation function for editable fields, or clears a previously set validator.

The validator function takes in the new field value, and returns validated value. The validated value could be the input value, a modified version of the input value, or null to abort the change.

If the function does not return anything (or returns undefined) the new value is accepted as valid. This is to allow for fields using the validated function as a field-level change event notification.

Parameter
handler	The validator function or null to clear a previous validator.

Inherited from

Blockly.Field#setValidator

setValue

setValue(newValue)

Used to change the value of the field. Handles validation and events. Subclasses should override doClassValidation_ and doValueUpdate_ rather than this method.

Parameter
newValue	New value.

Inherited from

Blockly.Field#setValue

setVisible

package

setVisible(visible)

Sets whether this editable field is visible or not. Should only be called by input.setVisible.

Parameter
visible	True if visible.

Inherited from

Blockly.Field#setVisible

shouldAddBorderRect_

protected

shouldAddBorderRect_() returns boolean

Whether or not the dropdown should add a border rect.

Returns

boolean True if the dropdown field should add a border rect.

showEditor

package

showEditor(opt_e)

Show an editor when the field is clicked only if the field is clickable.

Parameter
opt_e	Optional Optional mouse event that triggered the field to open, or undefined if triggered programmatically.

Inherited from

Blockly.Field#showEditor

showEditor_

protected

showEditor_(opt_e)

Create a dropdown menu under the text.

Parameter
opt_e	Optional Event Optional mouse event that triggered the field to open, or undefined if triggered programmatically.

toXml

package

toXml(fieldElement) returns Element

Serializes this field's value to XML. Should only be called by Blockly.Xml.

Parameter
fieldElement	The element to populate with info about the field's state. Value must not be null.

Inherited from

Blockly.Field#toXml

Returns

The element containing info about the field's state.

updateEditable

updateEditable()

Add or remove the UI indicating if this field is editable or not.

Inherited from

Blockly.Field#updateEditable

updateMarkers_

protected

updateMarkers_()

Redraw any attached marker or cursor svgs if needed.

Inherited from

Blockly.Field#updateMarkers_

updateSize_

protected

updateSize_(opt_margin)

Updates the size of the field based on the text.

Parameter
opt_margin	Optional margin to use when positioning the text element.

Inherited from

Blockly.Field#updateSize_

Abstract type

ImageProperties

static

{src:string, alt:string, width:number, height:number}

Dropdown image properties.