Blockly. FieldDropdown
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
IfmenuGenerator
options are incorrectly structured.
Properties
ARROW_CHAR
Android can't (in 2014) display "▾", so use "▼" instead.
CHECKMARK_OVERHANG
Horizontal distance that a checkmark overhangs the dropdown.
MAX_MENU_HEIGHT_VH
Maximum height of the dropdown menu, as a percentage of the viewport height.
arrow_
non-null SVGTSpanElement
borderRect_
unknown
The rendered field's SVG border element.
- Inherited from
- Blockly.Field#borderRect_
clickTarget_
unknown
The element the click handler is bound to.
- Inherited from
- Blockly.Field#clickTarget_
constants_
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
unknown
The default value for this field.
- Inherited from
- Blockly.Field#DEFAULT_VALUE
disposed
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
fieldGroup_
unknown
The rendered field's SVG group element.
- Inherited from
- Blockly.Field#fieldGroup_
isDirty_
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_
The dropdown menu.
menu_
non-null Blockly.Menu
menuGenerator_
(non-null Array of non-null Array or non-null function(this = Blockly.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
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_
unknown
The size of the area rendered by the field.
- Inherited from
- Blockly.Field#size_
sourceBlock_
unknown
Block this field is attached to. Starts as null, then set in init.
- Inherited from
- Blockly.Field#sourceBlock_
suffixField
nullable string
The suffix field label, of common words set after options are trimmed.
textContent_
unknown
The rendered field's text content element.
- Inherited from
- Blockly.Field#textContent_
textElement_
non-null Element
validator_
unknown
Validation function called when user edits an editable field.
- Inherited from
- Blockly.Field#validator_
value_
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_
unknown
Is the field visible, or hidden due to the block being collapsed?
- Inherited from
- Blockly.Field#visible_
Methods
applyTrim_
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
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
applyColour()
Updates the dropdown arrow to match the colour/style of the block.
bindEvents_
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_
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_
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_
createSVGArrow_()
Create an SVG based arrow.
createTextArrow_
createTextArrow_()
Create a tspan based arrow.
createTextElement_
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
dispose()
Dispose of all DOM objects and events belonging to this editable field.
- Inherited from
- Blockly.Field#dispose
doClassValidation_
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_
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_
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
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
fromXml(fieldElement)
Sets the field's value based on the given XML element. Should only be called by Blockly.Xml.
Parameter |
|
---|---|
fieldElement |
The element containing info about the field's state. Value must not be null. |
- Inherited from
- Blockly.Field#fromXml
getAbsoluteXY_
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_
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_
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
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
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_
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
init()
Initialize everything to render this field. Override methods initModel and initView rather than this method.
- Inherited from
- Blockly.Field#init
initModel
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
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.
- Inherited from
- Blockly.Field#isCurrentlyEditable
- Returns
-
Whether this field is editable and on an editable block
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.
markDirty
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
onBlocklyAction
onBlocklyAction(action) returns boolean
Handles the given action. This is only triggered when keyboard accessibility mode is enabled.
Parameter |
|
---|---|
action |
Blockly.ShortcutRegistry.KeyboardShortcut The action to be handled. Value must not be null. |
- Returns
-
boolean
True if the field handled the action, false otherwise.
onItemSelected_
onItemSelected_(menu, menuItem)
Handle the selection of an item in the dropdown menu.
Parameter |
|
---|---|
menu |
The Menu component clicked. Value must not be null. |
menuItem |
The MenuItem selected within menu. Value must not be null. |
onMouseDown_
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_
positionBorderRect_
positionBorderRect_()
Position a field's border rect after a size change.
- Inherited from
- Blockly.Field#positionBorderRect_
positionTextElement_
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
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_
render_()
Draws the border with the correct width.
setCursorSvg
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
setMarkerSvg
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
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_
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
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_
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
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_
updateMarkers_()
Redraw any attached marker or cursor svgs if needed.
- Inherited from
- Blockly.Field#updateMarkers_
updateSize_
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
{src:string, alt:string, width:number, height:number}
Dropdown image properties.