Constructor

Field

new Field(value, opt_validator, opt_config)

Abstract class for an editable field.

Parameter

value

any type

The initial value of the field.

opt_validator

Optional

function()

A function that is called to validate changes to the field's value. Takes in a value & returns a validated value, or null to abort the change.

Value may be null.

opt_config

Optional

Object

A map of options used to configure the field. See the individual field's documentation for a list of properties this parameter supports.

Properties

BORDER_RECT_DEFAULT_HEIGHT

package   static

number

The default height of the border rect on any field.

DEFAULT_TEXT_OFFSET

static

number

The default offset between the left of the text element and the left of the border rect, if the border rect exists.

NBSP

constant   static

Non-breaking space.

TEXT_DEFAULT_HEIGHT

package   static

number

The default height of the text element on any field.

X_PADDING

package   static

number

The padding added to the width by the border rect, if it exists.

Y_PADDING

package   static

number

The padding added to the height by the border rect, if it exists.

disposed

package

boolean

Has this field been disposed of?

EDITABLE

boolean

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

fieldGroup_

non-null SVGElement

getText_

protected

A developer hook to override the returned text of this field. Override if the text representation of the value of this field is not just a string cast of its value.

Returns

nullable string Current text. Return null to resort to a string cast.

isDirty_

protected

boolean

Does this block need to be re-rendered?

maxDisplayLength

number

Maximum characters of text to display before adding an ellipsis.

name

(string or undefined)

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

SERIALIZABLE

boolean

Serializable fields are saved by the XML renderer, non-serializable fields are not. Editable fields should also be serializable. This is not the case by default so that SERIALIZABLE is backwards compatible.

size_

protected

non-null Blockly.utils.Size

The size of the area rendered by the field.

sourceBlock_

protected

Blockly.Block

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

validator_

protected

function()

Validation function called when user edits an editable field.

value_

protected

any type

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

visible_

protected

boolean

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

Methods

bindEvents_

protected

bindEvents_()

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

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

string

Proposed text.

Deprecated
May 2019. setValue now contains all relevant logic.
Returns

nullable string Revised text, or null if invalid.

classValidator

classValidator(text) returns string

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

Parameter

text

string

The user's text.

Deprecated
May 2019. Override doClassValidation and other relevant 'do' functions instead.
Returns

string No change needed.

configure_

protected

configure_(config)

Process the configuration map passed to the field.

Parameter

config

Object

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.

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.

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.

dispose

package

dispose()

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

doClassValidation_

protected

doClassValidation_(opt_newValue) returns any type

Used to validate a value. Returns input by default. Can be overridden by subclasses, see FieldDropdown.

Parameter

opt_newValue

Optional

any type

The value to be validated.

Returns

any type The validated value, same as input by default.

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

any type

The input value that was determined to be invalid.

doValueUpdate_

protected

doValueUpdate_(newValue)

Used to update the value of a field. Can be overridden by subclasses to do custom storage of values/updating of external things.

Parameter

newValue

any type

The value to be saved.

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.

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.

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.

Returns

string Text to display.

getFlipRtl

getFlipRtl() returns boolean

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

Returns

boolean True if we should flip in RTL.

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.

Returns

Blockly.Input The input that the field belongs to.

getScaledBBox_

protected

getScaledBBox_() returns Object

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

Returns

non-null Object 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.

Returns

non-null Blockly.utils.Size Height and width.

getSourceBlock

getSourceBlock() returns Blockly.Block

Get the block this field is attached to.

Returns

Blockly.Block The block containing this field.

getSvgRoot

getSvgRoot() returns SVGElement

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

Returns

non-null SVGElement The group element.

getText

getText() returns string

Get the text from this field.

Returns

string Current text.

getValidator

getValidator() returns function()

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

Returns

function() Validation function, or null.

getValue

getValue() returns any type

Get the current value of the field.

Returns

any type Current value.

init

package

init()

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

initModel

package

initModel()

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

initView

package

initView()

Create the block UI for this field.

isClickable

isClickable() returns boolean

Check whether this field defines the showEditor_ function.

Returns

boolean 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.

Returns

boolean Whether this field is editable and on an editable block

isSerializable

isSerializable() returns boolean

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

Returns

boolean Whether this field should be serialized or not.

isTabNavigable

isTabNavigable() returns boolean

Returns whether or not the field is tab navigable.

Returns

boolean True if the field is tab navigable.

isVisible

isVisible() returns boolean

Gets whether this editable field is visible or not.

Returns

boolean True if visible.

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.

onBlocklyAction

package

onBlocklyAction(_action) returns boolean

Handles the given action. This is only triggered when keyboard accessibility mode is enabled.

Parameter

_action

Blockly.Action

The action to be handled.

Value must not be null.

Returns

boolean True if the field handled the action, false otherwise.

onMouseDown_

protected

onMouseDown_(e)

Handle a mouse down event on a field.

Parameter

e

Event

Mouse down event.

Value must not be null.

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.

Returns

boolean True if this field has any variable references.

render_

protected

render_()

Used by getSize() to move/resize any DOM elements, and get the new size.

All rendering that has an effect on the size/shape of the block should be done here, and should be triggered by getSize().

setCursorSvg

package

setCursorSvg(cursorSvg)

Add the cursor svg to this fields svg group.

Parameter

cursorSvg

SVGElement

The svg root of the cursor to be added to the field group.

setMarkerSvg

package

setMarkerSvg(markerSvg)

Add the marker svg to this fields svg group.

Parameter

markerSvg

SVGElement

The svg root of the marker to be added to the field group.

setSourceBlock

setSourceBlock(block)

Attach this field to a block.

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

any type

New text.

Deprecated
2019 setText should not be used directly. Use setValue instead.

setTooltip

setTooltip(newTip)

Change the tooltip text for this field.

Parameter

newTip

(string, function(), or non-null SVGElement)

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

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

function()

The validator function or null to clear a previous validator.

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

any type

New value.

setVisible

package

setVisible(visible)

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

Parameter

visible

boolean

True if visible.

toXml

package

toXml(fieldElement) returns Element

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

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 field to match the colour/style of the block. Should only be called by BlockSvg.updateColour().

updateEditable

updateEditable()

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

updateSize_

protected

updateSize_()

Updates the size of the field based on the text.

updateWidth

updateWidth()

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

Deprecated
May 2019 Use Blockly.Field.updateSize_() to force an update to the size of the field, or Blockly.utils.dom.getTextWidth() to check the size of the field.