Class: FieldColour

Constructor

FieldColour

new FieldColour(opt_value, opt_validator, opt_config)

Class for a colour input field.

Parameter
opt_value	Optional string The initial value of the field. Should be in '#rrggbb' format. Defaults to the first value in the default colour array.
opt_validator	Optional function() A function that is called to validate changes to the field's value. Takes in a colour string & returns a validated colour string ('#rrggbb' format), 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.

Parameter

opt_value

Optional

string

The initial value of the field. Should be in '#rrggbb' format. Defaults to the first value in the default colour array.

opt_validator

Optional

function()

A function that is called to validate changes to the field's value. Takes in a colour string & returns a validated colour string ('#rrggbb' format), 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

Properties

COLOURS

static

non-null Array of string

An array of colour strings for the palette. Copied from goog.ui.ColorPicker.SIMPLE_GRID_COLORS All colour pickers use this unless overridden with setColours.

COLUMNS

static

Number of columns in the palette. All colour pickers use this unless overridden with setColumns.

TITLES

static

non-null Array of string

An array of tooltip strings for the palette. If not the same length as COLOURS, the colour's hex code will be used for any missing titles. All colour pickers use this unless overridden with setColours.

borderRect_

protected

unknown

The rendered field's SVG border element.

Inherited from: Blockly.Field#borderRect_

clickTarget_

protected

unknown

The element the click handler is bound to.

Inherited from: Blockly.Field#clickTarget_

constants_

protected

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

protected

any type

The default value for this field.

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_

protected

unknown

The rendered field's SVG group element.

Inherited from: Blockly.Field#fieldGroup_

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. Return null to resort to a string cast.

Inherited from: Blockly.Field#getText_
Returns: Current text. Return null to resort to a string cast.

isDirty_

protected

boolean

Used to tell if the field needs to be rendered the next time the block is rendered. Colour fields are statically sized, and only need to be rendered at initialization.

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

picker_

non-null Element

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_

textContent_

protected

unknown

The rendered field's text content element.

Inherited from: Blockly.Field#textContent_

textElement_

protected

unknown

The rendered field's SVG text element.

Inherited from: Blockly.Field#textElement_

validator_

protected

unknown

Validation function called when user edits an editable field.

Inherited from: Blockly.Field#validator_

value_

string

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

Construct a FieldColour from a JSON arg object.

Parameter
options	Object A JSON object with options (colour). Value must not be null.

Parameter

options

Object

A JSON object with options (colour).

Value must not be null.

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

applyColour

package

applyColour()

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

Inherited from: Blockly.FieldColour#applyColour

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

Ensure that the input value is a valid colour.

Parameter
opt_newValue	Optional any type The input value.

Parameter

opt_newValue

Optional

any type

The input value.

Returns: nullable string A valid colour, or null if invalid.

doValueInvalid_

protected

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_

protected

doValueUpdate_(newValue)

Update the value of this colour field, and update the displayed colour.

Parameter
newValue	any type The value to be saved. The default validator guarantees that this is a colour in '#rrggbb' format.

Parameter

newValue

any type

The value to be saved. The default validator guarantees that this is a colour in '#rrggbb' format.

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.

Parameter

fieldElement

The element containing info about the field's state.

Value must not be null.

Inherited from: Blockly.Field#fromXml

getAbsoluteXY_

protected

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_

protected

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_

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.

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

package

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 for this field. Used when the block is collapsed.

Returns: string Text representing the value of 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

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

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

package

markDirty()

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	Blockly.Action The action to be handled. Value must not be null.

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	Mouse down event. Value must not be null.

Inherited from: Blockly.Field#onMouseDown_

positionBorderRect_

protected

positionBorderRect_()

Position a field's border rect after a size change.

Inherited from: Blockly.Field#positionBorderRect_

positionTextElement_

protected

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

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

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

Inherited from: Blockly.Field#render_

setColours

setColours(colours, opt_titles) returns Blockly.FieldColour

Set a custom colour grid for this field.

Parameter
colours	Array of string Array of colours for this block, or null to use default (Blockly.FieldColour.COLOURS).
opt_titles	Optional Array of string Optional array of colour tooltips, or null to use default (Blockly.FieldColour.TITLES).

Parameter

colours

Array of string

Array of colours for this block, or null to use default (Blockly.FieldColour.COLOURS).

opt_titles

Optional

Array of string

Optional array of colour tooltips, or null to use default (Blockly.FieldColour.TITLES).

Returns: non-null Blockly.FieldColour Returns itself (for method chaining).

setColumns

setColumns(columns) returns Blockly.FieldColour

Set a custom grid size for this field.

Parameter
columns	number Number of columns for this block, or 0 to use default (Blockly.FieldColour.COLUMNS).

Parameter

columns

number

Number of columns for this block, or 0 to use default (Blockly.FieldColour.COLUMNS).

Returns: non-null Blockly.FieldColour Returns itself (for method chaining).

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
Implements: Blockly.IASTNodeLocationSvg#setCursorSvg

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

Parameter

block

The block containing this field.

Value must not be null.

Inherited from: Blockly.Field#setSourceBlock

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

package

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.

Parameter

opt_e

Optional

Optional mouse event that triggered the field to open, or undefined if triggered programmatically.

Inherited from: Blockly.Field#showEditor

showEditor_

protected

showEditor_()

Create and show the colour field's editor.

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.

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_

protected

updateMarkers_()

Redraw any attached marker or cursor svgs if needed.

Inherited from: Blockly.Field#updateMarkers_

updateSize_

protected

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.

Parameter

opt_margin

Optional

margin to use when positioning the text element.

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.