Constructor

Field

new Field(text, opt_validator)

Abstract class for an editable field.

Parameter

text

string

The initial content of the field.

opt_validator

Optional

function()

An optional function that is called to validate any constraints on what the user entered. Takes the new text as an argument and returns either the accepted text, a replacement text, or null to abort the change.

Properties

NBSP

constant   static

Non-breaking space.

EDITABLE

Editable fields are saved by the XML renderer, non-editable fields are not.

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.

textElement_

non-null Element

Methods

fromJson

static

fromJson(options) returns Blockly.Field

Construct a Field from a JSON arg object. Finds the appropriate registered field by the type name as registered using Blockly.Field.register.

Parameter

options

Object

A JSON object with a type and options specific to the field type.

Value must not be null.

Returns

nullable Blockly.Field The new field instance or null if a field wasn't found with the given type name

getCachedWidth

static

getCachedWidth(textElement) returns number

Gets the width of a text element, caching it in the process.

Parameter

textElement

Element

An SVG 'text' element.

Value must not be null.

Returns

number Width of element.

register

static

register(type, fieldClass)

Registers a field type. May also override an existing field type. Blockly.Field.fromJson uses this registry to find the appropriate field.

Parameter

type

string

The field type name as used in the JSON definition.

Value must not be null.

fieldClass

{fromJson: function()}

The field class containing a fromJson function that can construct an instance of the field.

Value must not be null.

Throws

Error if the type name is empty, or the fieldClass is not an object containing a fromJson function.

startCache

static

startCache()

Start caching field widths. Every call to this function MUST also call stopCache. Caches must not survive between execution threads.

stopCache

static

stopCache()

Stop caching field widths. Unless caching was already on when the corresponding call to startCache was made.

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.

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.

Returns

string No change needed.

dispose

dispose()

Dispose of all DOM objects belonging to this editable field.

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.

getSize

getSize() returns goog.math.Size

Returns the height and width of the field.

Returns

non-null goog.math.Size Height and width.

getSvgRoot

getSvgRoot() returns Element

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

Returns

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

Returns

function() Validation function, or null.

getValue

getValue() returns string

By default there is no difference between the human-readable text and the language-neutral values. Subclasses (such as dropdown) may define this.

Returns

string Current value.

init

init()

Install this field on a block.

initModel

initModel()

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

isCurrentlyEditable

isCurrentlyEditable() returns boolean

Check whether this field is currently editable. Some fields are never editable (e.g. text labels). Those fields are not serialized to XML. Other fields may be editable, and therefore serialized, but may exist on non-editable blocks.

Returns

boolean whether this field is editable and on an editable block

isVisible

isVisible() returns boolean

Gets whether this editable field is visible or not.

Returns

boolean True if visible.

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.

Returns

boolean True if this field has any variable references.

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.

setTooltip

setTooltip(_newTip)

Change the tooltip text for this field.

Parameter

_newTip

(string or non-null Element)

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

setValidator

setValidator(handler)

Sets a new validation function for editable fields.

Parameter

handler

function()

New validation function, or null.

setValue

setValue(newValue)

By default there is no difference between the human-readable text and the language-neutral values. Subclasses (such as dropdown) may define this.

Parameter

newValue

string

New value.

setVisible

setVisible(visible)

Sets whether this editable field is visible or not.

Parameter

visible

boolean

True if visible.

updateEditable

updateEditable()

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

updateWidth

updateWidth()

Updates thw width of the field. This calls getCachedWidth which won't cache the approximated width on IE/Edge when getComputedTextLength fails. Once it eventually does succeed, the result will be cached.