Constructor

FieldTextInput

new FieldTextInput(opt_value, opt_validator, opt_config)

Class for an editable text field.

Parameter

opt_value

Optional

string

The initial value of the field. Should cast to a string. Defaults to an empty string if null or undefined.

opt_validator

Optional

function()

A function that is called to validate changes to the field's value. Takes in a string & returns a validated string, 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 field creation documentation for a list of properties this parameter supports.

Extends
Blockly.Field

Properties

BORDERRADIUS

static

Pixel size of input border radius. Should match blocklyText's border-radius in CSS.

FONTSIZE

static

Point size of text. Should match blocklyText's font-size in CSS.

CURSOR

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

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

fieldGroup_

unknown

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

name

unknown

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

Inherited from
Blockly.Field#name

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_

spellcheck_

protected

boolean

Allow browser to spellcheck this field.

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

fromJson

package   static

fromJson(options) returns Blockly.FieldTextInput

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

Parameter

options

Object

A JSON object with options (text, and spellcheck).

Value must not be null.

Returns

non-null Blockly.FieldTextInput The new field instance.

nonnegativeIntegerValidator

static

nonnegativeIntegerValidator(text) returns string

Ensure that only a non-negative integer may be entered.

Parameter

text

string

The user's text.

Deprecated
Returns

nullable string A string representing a valid int, or null if invalid.

numberValidator

static

numberValidator(text) returns string

Ensure that only a number may be entered.

Parameter

text

string

The user's text.

Deprecated
Returns

nullable string A string representing a valid number, or null if invalid.

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_

bindInputEvents_

protected

bindInputEvents_(htmlInput)

Bind handlers for user input on the text input field's editor.

Parameter

htmlInput

HTMLElement

The htmlInput to which event handlers will be bound.

Value must not be null.

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.

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.FieldTextInput#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_

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 any type

Ensure that the input value casts to a valid string.

Parameter

opt_newValue

Optional

any type

The input value.

Returns

any type A valid string, or null if invalid.

doValueInvalid_

protected

doValueInvalid_(_invalidValue)

Called by setValue if the text input is not valid. If the field is currently being edited it reverts value of the field to the previous value while allowing the display text to be handled by the htmlInput_.

Parameter

_invalidValue

any type

The input value that was determined to be invalid. This is not used by the text input because its display value is stored on the htmlInput_.

doValueUpdate_

protected

doValueUpdate_(newValue)

Called by setValue if the text input is valid. Updates the value of the field, and updates the text of the field if it is not currently being edited (i.e. handled by the htmlInput_).

Parameter

newValue

any type

The value to be saved. The default validator guarantees that this is a string.

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

The element containing info about the field's state.

Value must not be null.

Inherited from
Blockly.Field#fromXml

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.

getEditorText_

protected

getEditorText_(value) returns string

Transform the provided value into a text to show in the html input. Override this method if the field's html input representation is different than the field's value. This should be coupled with an override of getValueFromEditorText_.

Parameter

value

any type

The value stored in this field.

Returns

string The text to show on the html input.

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.

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_

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 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
Returns

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.

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. When we're currently editing, return the current html value instead. Otherwise, return null which tells the field to use the default behaviour (which is a string cast of the field's value).

Inherited from
Blockly.FieldTextInput#getText_
Returns

The html value if we're editing, otherwise null.

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.

getValueFromEditorText_

protected

getValueFromEditorText_(text) returns any type

Transform the text received from the html input into a value to store in this field. Override this method if the field's html input representation is different than the field's value. This should be coupled with an override of getEditorText_.

Parameter

text

string

Text received from the html input.

Returns

any type The value to store.

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

Inherited from
Blockly.Field#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

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.FieldTextInput#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

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

onBlocklyAction

package

onBlocklyAction(_action) returns boolean

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

Parameter

_action

The action to be handled.

Value must not be null.

Inherited from
Blockly.Field#onBlocklyAction
Returns

True if the field handled the action, false otherwise.

onHtmlInputKeyDown_

protected

onHtmlInputKeyDown_(e)

Handle key down to the editor.

Parameter

e

Event

Keyboard event.

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

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

Updates the colour of the htmlInput given the current validity of the field's value.

resizeEditor_

protected

resizeEditor_()

Resize the editor to fit the text.

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

setEditorValue_

protected

setEditorValue_(newValue)

Set the html input value and the field's internal value. The difference between this and setValue is that this also updates the html input value whilst editing.

Parameter

newValue

any type

New value.

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

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

setSpellcheck

setSpellcheck(check)

Set whether this field is spellchecked by the browser.

Parameter

check

boolean

True if checked.

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
Deprecated
2019 setText should not be used directly. Use setValue instead.

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

showEditor_

protected

showEditor_(opt_quietInput)

Show the inline free-text editor on top of the text.

Parameter

opt_quietInput

Optional

boolean

True if editor should be created without focus. Defaults to false.

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.

updateColour

package

updateColour()

Updates the field to match the colour/style of the block. Should only be called by BlockSvg.updateColour().

Inherited from
Blockly.Field#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.utils.dom.getTextWidth() to check the size of the field.

widgetCreate_

protected

widgetCreate_() returns HTMLElement

Create the text input editor widget.

Returns

non-null HTMLElement The newly created text input editor.