Class: FieldVariable | Blockly

Constructor

FieldVariable

new FieldVariable(varname, opt_validator, opt_variableTypes, opt_defaultType)

Class for a variable's dropdown field.

Parameter
varname	string The default name for the variable. If null, a unique variable name will be generated. Value may be null.
opt_validator	Optional function() A function that is called to validate changes to the field's value. Takes in a variable ID & returns a validated variable ID, or null to abort the change.
opt_variableTypes	Optional Array of string A list of the types of variables to include in the dropdown.
opt_defaultType	Optional string The type of variable to create if this field's value is not explicitly set. Defaults to ''.

Extends: Blockly.FieldDropdown

Properties

CURSOR

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

Inherited from: Blockly.FieldDropdown#CURSOR

EDITABLE

constant

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
Default value: true

fieldGroup_

unknown

Inherited from: Blockly.Field#fieldGroup_

maxDisplayLength

unknown

Maximum characters of text to display before adding an ellipsis.

Inherited from: Blockly.Field#maxDisplayLength

menuGenerator_

unknown

Inherited from: Blockly.FieldDropdown#menuGenerator_

name

unknown

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

Inherited from: Blockly.Field#name

SERIALIZABLE

constant

boolean

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

sourceBlock_

protected

unknown

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

Inherited from: Blockly.Field#sourceBlock_

text_

protected

unknown

Text representation of the field's value. Maintained for backwards compatibility reasons.

Inherited from: Blockly.Field#text_
Deprecated: Use or override getText instead.

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

dropdownCreate

static

dropdownCreate() returns Array of string

Return a sorted list of variable names for variable dropdown menus. Include a special option at the end for creating a new variable name.

Returns: non-null Array of string Array of variable names.

fromJson

package static

fromJson(options) returns Blockly.FieldVariable

Construct a FieldVariable from a JSON arg object, dereferencing any string table references.

Parameter
options	Object A JSON object with options (variable, variableTypes, and defaultType). Value must not be null.

Parameter

options

Object

A JSON object with options (variable, variableTypes, and defaultType).

Value must not be null.

Returns: non-null Blockly.FieldVariable The new field instance.

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_

callValidator

callValidator(text) returns string

Calls the validation function for this field, as well as all the validation function for the field's class and its parents.

Parameter
text	Proposed text.

Inherited from: Blockly.Field#callValidator
Deprecated: May 2019. setValue now contains all relevant logic.
Returns: Revised text, or null if invalid.

classValidator

classValidator(text) returns string

Validates a change. Does nothing. Subclasses may override this.

Parameter
text	The user's text.

Inherited from: Blockly.Field#classValidator
Deprecated: May 2019. Override doClassValidation and other relevant 'do' functions instead.
Returns: No change needed.

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_

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_(newId) returns string

Ensure that the id belongs to a valid variable of an allowed type.

Parameter
newId	string The id of the new variable to set.

Parameter

newId

string

The id of the new variable to set.

Returns: nullable string The validated id, or null if invalid.

doValueInvalid_

protected

doValueInvalid_(_invalidValue)

Used to notify the field an invalid value was input. Can be overidden 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_(newId)

Update the value of this variable field, as well as its variable and text.

The variable ID should be valid at this point, but if a variable field validator returns a bad ID, this could break.

Parameter
newId	string The id of the new variable.

Parameter

newId

string

The id of the new variable.

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

fromXml(fieldElement)

Initialize this field based on the given XML.

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

Parameter

fieldElement

Element

The element containing information about the variable field's state.

Value must not be null.

getDisplayText_

protected

getDisplayText_() returns string

Get the text from this field as displayed on screen. May differ from getText due to ellipsis, and other formatting.

Inherited from: Blockly.Field#getDisplayText_
Returns: Currently displayed text.

getOptions

getOptions() returns Array of non-null Array

Return a list of the options for this dropdown.

Inherited from: Blockly.FieldDropdown#getOptions
Throws: If generated options are incorrectly structured.
Returns: Array of option tuples: (human-readable text or image, language-neutral name).

getScaledBBox_

protected

getScaledBBox_() returns Object

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 goog.math.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
Returns: The block containing this field.

getSvgRoot

getSvgRoot() returns Element

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, which is the selected variable's name.

Returns: string The selected variable's name, or the empty string if no variable is selected.

getValidator

getValidator() returns function()

Gets the validation function for this field, or null if not set. Returns null if the variable is not set, because validators should not run on the initial setValue call, because the field won't be attached to a block and workspace at that point.

Returns: function() Validation function, or null.

getValue

getValue() returns string

Get the variable's ID.

Returns: string Current variable's ID.

getVariable

package

getVariable() returns Blockly.VariableModel

Get the variable model for the selected variable. Not guaranteed to be in the variable map on the workspace (e.g. if accessed after the variable has been deleted).

Returns: Blockly.VariableModel The selected variable, or null if none was selected.

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()

Initialize the model for this field if it has not already been initialized. If the value has not been set to a variable by the first render, we make up a variable rather than let the value be invalid.

initView

package

initView()

Create the block UI for this dropdown.

Inherited from: Blockly.FieldDropdown#initView

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

Inherited from: Blockly.FieldDropdown#isOptionListDynamic
Returns: 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.

isVisible

isVisible() returns boolean

Gets whether this editable field is visible or not.

Inherited from: Blockly.Field#isVisible
Returns: True if visible.

onItemSelected

onItemSelected(menu, menuItem)

Handle the selection of an item in the variable dropdown menu. Special case the 'Rename variable...' and 'Delete variable...' options. In the rename case, prompt the user for a new name.

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

Parameter

goog.ui.Menu

The Menu component clicked.

Value must not be null.

menuItem

goog.ui.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_

referencesVariables

package

referencesVariables() returns boolean

Overrides referencesVariables(), indicating this field refers to a variable.

Inherited from: Blockly.Field#referencesVariables
Returns: True.

setSourceBlock

setSourceBlock(block)

Attach this field to a block.

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

Parameter

block

Blockly.Block

The block containing this field.

Value must not be null.

setText

setText(newText)

Set the text in this field. Trigger a rerender of the source block.

Parameter
newText	New text.

Inherited from: Blockly.Field#setText

setTooltip

setTooltip(newTip)

Change the tooltip text for this field.

Parameter
newTip	Text for tooltip or a parent element to link to for its tooltip.

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 founction as a field-level change event notification.

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

Parameter

handler

Optional

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

toXml

toXml(fieldElement) returns Element

Serialize this field to XML.

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

Parameter

fieldElement

Element

The element to populate with info about the field's state.

Value must not be null.

Returns: non-null Element The element containing info about the field's state.

updateColour

package

updateColour()

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

Inherited from: Blockly.FieldDropdown#updateColour

updateEditable

updateEditable()

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

Inherited from: Blockly.Field#updateEditable

updateSize_

protected

updateSize_()

Updates the size of the field based on the text.

Inherited from: Blockly.Field#updateSize_

updateWidth

updateWidth()

Updates the width of the field. Redirects to updateSize_().

Inherited from: Blockly.Field#updateWidth
Deprecated: May 2019 Use Blockly.Field.updateSize_() to force an update to the size of the field, or Blockly.Field.getCachedWidth() to check the size of the field..