Class: FieldVariable

Defined in: packages/blockly/core/field_variable.ts:37

Class for a variable's dropdown field.

Extends

• FieldDropdown

Properties index

Property	Description
DEFAULT_VALUE	To overwrite the default value which is set in Field, directly update the prototype.
NBSP	Non-breaking space.
SKIP_SETUP	A value used to signal when a field's constructor should not set the field's value or run configure_, and should allow a subclass to do that instead.
name	Name of field. Unique within each block. Static labels are usually unnamed.
value_	-
validator_	Validation function called when user edits an editable field.
ariaTypeName	The ARIA-friendly label representation of this field's type.
fieldGroup_	The rendered field's SVG group element.
borderRect_	The rendered field's SVG border element.
textElement_	The rendered field's SVG text element.
textContent_	The rendered field's text content element.
constants_	Constants associated with the source block's renderer.
maxDisplayLength	Maximum characters of text to display before adding an ellipsis.
sourceBlock_	Block this field is attached to. Starts as null, then set in init.
isDirty_	Does this block need to be re-rendered?
visible_	Is the field visible, or hidden due to the block being collapsed?
enabled_	Can the field value be changed using the editor on an editable block?
EDITABLE	Editable fields usually show some sort of UI indicating they are editable. They will also be saved by the serializer.
SEPARATOR	Magic constant used to represent a separator in a list of dropdown items.
ARROW_CHAR	-
menu_	The dropdown menu.
clickTarget_	The element the click handler is bound to.
IMAGE_Y_OFFSET	The y offset from the top of the field to the top of the image, if an image is selected.
IMAGE_Y_PADDING	The total vertical padding above and below an image.
isInitialized	True once the field’s DOM has been created and it is safe to run ARIA updates in response to value changes.
menuGenerator_	-
defaultVariableName	-
variableTypes	All of the types of variables that will be available in this field's dropdown.
SERIALIZABLE	Serializable fields are saved by the serializer, non-serializable fields are not. Editable fields should also be serializable.

Methods index

Method	Description
getConstants	Get the renderer constant provider.
getSourceBlock	Get the block this field is attached to.
setAriaTypeName	Sets the ARIA-friendly label representation of this field's type.
computeAriaLabel	Computes a descriptive ARIA label to represent this field with configurable verbosity.
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_	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. Aria state is hidden; use the aria label for the field and/or containing block to expose content to screen readers. Text content for custom blocks can be set after creation.
bindEvents_	Bind events to the field. Can be overridden by subclasses if they need to do custom input handling.
saveLegacyState	Returns a stringified version of the XML state, if it should be used. Otherwise this returns null, to signal the field should use its own serialization.
loadLegacyState	Loads the given state using either the old XML hooks, if they should be used. Returns true to indicate loading has been handled, false otherwise.
dispose	Dispose of all DOM objects and events belonging to this editable field.
updateEditable	Add or remove the UI indicating if this field is editable or not.
setEnabled	Set whether this field's value can be changed using the editor when the source block is editable.
isEnabled	Check whether this field's value can be changed using the editor when the source block is editable.
isClickable	Check whether this field defines the showEditor_ function.
isClickableInFlyout	Check whether the field should be clickable while the block is in a flyout. The default is that fields are clickable in always-open flyouts such as the simple toolbox, but not in autoclosing flyouts such as the category toolbox. Subclasses may override this function to change this behavior. Note that isClickable must also return true for this to have any effect.
isCurrentlyEditable	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 or be currently disabled.
isSerializable	Check whether this field should be serialized by the XML renderer. Handles the logic for backwards compatibility and incongruous states.
isVisible	Gets whether this editable field is visible or not.
setValidator	Sets a new validation function for editable fields, or clears a previously set validator.
getSvgRoot	Gets the group element for this editable field. Used for measuring the size and for positioning.
getBorderRect	Gets the border rectangle element.
getTextElement	Gets the text element.
getTextContent	Gets the text content.
repositionForWindowResize	A developer hook to reposition the WidgetDiv during a window resize. You need to define this hook if your field has a WidgetDiv that needs to reposition itself when the window is resized. For example, text input fields define this hook so that the input WidgetDiv can reposition itself on a window resize event. This is especially important when modal inputs have been disabled, as Android devices will fire a window resize event when the soft keyboard opens.
updateSize_	Updates the size of the field based on the text.
positionTextElement_	Position a field's text element after a size change. This handles both LTR and RTL positioning.
positionBorderRect_	Position a field's border rect after a size change.
getSize	Returns the height and width of the field.
onLocationChange	Notifies the field that it has changed locations.
getDisplayText_	Get the text from this field to display on the block. May differ from getText due to ellipsis, and other formatting.
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.
setValue	Used to change the value of the field. Handles validation and events. Subclasses should override doClassValidation_ and doValueUpdate_ rather than this method.
doValueInvalid_	Used to notify the field an invalid value was input. Can be overridden by subclasses, see FieldTextInput. No-op by default.
onMouseDown_	Handle a pointerdown event on a field.
setTooltip	Sets the tooltip for this field.
getTooltip	Returns the tooltip text for this field.
getClickTarget_	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.
getAbsoluteXY_	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.
getFlipRtl	Returns whether or not we should flip the field in RTL.
onShortcut	Handles the given keyboard shortcut.
getFocusableElement	See IFocusableNode.getFocusableElement.
getFocusableTree	See IFocusableNode.getFocusableTree.
onNodeFocus	See IFocusableNode.onNodeFocus.
onNodeBlur	See IFocusableNode.onNodeBlur.
canBeFocused	See IFocusableNode.canBeFocused.
performAction	Handles the user acting on this field via keyboard navigation. Shows and focuses the field editor.
isFullBlockField	This is hacky way of determining if a dropdown field is a full-block field or not. The constants that control the border rect are the same ones that determine how we render full-block dropdown fields. It's a full-block field if it doesn't have the border rect (and it's a simple reporter block).
createTextArrow_	Create a tspan based arrow.
createSVGArrow_	Create an SVG based arrow.
showEditor_	Create a dropdown menu under the text.
dropdownDispose_	Disposes of events and DOM-references belonging to the dropdown editor.
isOptionListDynamic	Returns true if the option list is generated by a function. Otherwise false.
getOptions	Return a list of the options for this dropdown.
setOptions	Update the options on this dropdown. This will reset the selected item to the first item in the list.
applyColour	Updates the dropdown arrow to match the colour/style of the block.
render_	Draws the border with the correct width.
getText_	Use the getText_ developer hook to override the field's text representation. Get the selected option text. If the selected option is an image we return the image alt text. If the selected option is an HTMLElement, return the title, ariaLabel, or innerText of the element.
trimOptions	Factor out common words in statically defined options. Create prefix and/or suffix labels.
validateOptions	Validates the data structure to be processed as an options list.
getAriaTypeName	Gets an ARIA-friendly label representation of this field's type.
recomputeAriaContext	Sets additional aria state.
configure_	Configure the field based on the given map of options.
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	Create the block UI for this dropdown.
shouldAddBorderRect_	Whether or not the dropdown should add a border rect.
fromXml	Initialize this field based on the given XML.
toXml	Serialize this field to XML.
setSourceBlock	Attach this field to a block.
getValue	Get the variable's ID.
getText	Get the text from this field, which is the selected variable's name.
getDefaultType	Gets the type of this field's default variable.
getValidator	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.
doClassValidation_	Ensure that the ID belongs to a valid variable of an allowed type.
doValueUpdate_	Update the value of this variable field, as well as its variable and text.
onItemSelected_	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.
dropdownCreate	Return a sorted list of variable names for variable dropdown menus. Include a special option at the end for creating a new variable name.
getAriaValue	Gets an ARIA-friendly label representation of this field's value.

Constructors

Constructor

new FieldVariable(
   varName, 
   validator?, 
   variableTypes?, 
   defaultType?, 
   config?
): FieldVariable;

Defined in: packages/blockly/core/field_variable.ts:79

Parameters

Parameter	Type	Description
varName	string | typeof SKIP_SETUP | null	The default name for the variable. If null, a unique variable name will be generated. Also accepts Field.SKIP_SETUP if you wish to skip setup (only used by subclasses that want to handle configuration and setting the field value after their own constructors have run).
validator?	FieldDropdownValidator	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.
variableTypes?	string[] | null	A list of the types of variables to include in the dropdown. Pass null to include all types that exist on the workspace. Will only be used if config is not provided.
defaultType?	string	The type of variable to create if this field's value is not explicitly set. Defaults to ''. Will only be used if config is not provided.
config?	FieldVariableConfig	A map of options used to configure the field. See the [field creation documentation]https://docs.blockly.com/guides/create-custom-blocks/fields/built-in-fields/variable/#creation for a list of properties this parameter supports.

Returns

FieldVariable

Overrides

FieldDropdown.constructor

Properties

DEFAULT_VALUE

DEFAULT_VALUE: string | null = null;

Defined in: packages/blockly/core/field.ts:79

To overwrite the default value which is set in Field, directly update the prototype.

Example: FieldImage.prototype.DEFAULT_VALUE = null;

Inherited from

FieldDropdown.DEFAULT_VALUE

---

NBSP

readonly static NBSP: " " = '\u00A0';

Defined in: packages/blockly/core/field.ts:82

Non-breaking space.

Inherited from

FieldDropdown.NBSP

---

SKIP_SETUP

readonly static SKIP_SETUP: typeof SKIP_SETUP;

Defined in: packages/blockly/core/field.ts:89

A value used to signal when a field's constructor should not set the field's value or run configure_, and should allow a subclass to do that instead.

Inherited from

FieldDropdown.SKIP_SETUP

---

name?

optional name?: string = undefined;

Defined in: packages/blockly/core/field.ts:95

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

Inherited from

FieldDropdown.name

---

value_

protected value_: string | null;

Defined in: packages/blockly/core/field.ts:96

Inherited from

FieldDropdown.value_

---

validator_

protected validator_: 
  | FieldValidator<string>
  | null = null;

Defined in: packages/blockly/core/field.ts:99

Validation function called when user edits an editable field.

Inherited from

FieldDropdown.validator_

---

ariaTypeName

protected ariaTypeName: string | null = null;

Defined in: packages/blockly/core/field.ts:102

The ARIA-friendly label representation of this field's type.

Inherited from

FieldDropdown.ariaTypeName

---

fieldGroup_

protected fieldGroup_: SVGGElement | null = null;

Defined in: packages/blockly/core/field.ts:130

The rendered field's SVG group element.

Inherited from

FieldDropdown.fieldGroup_

---

borderRect_

protected borderRect_: SVGRectElement | null = null;

Defined in: packages/blockly/core/field.ts:133

The rendered field's SVG border element.

Inherited from

FieldDropdown.borderRect_

---

textElement_

protected textElement_: SVGTextElement | null = null;

Defined in: packages/blockly/core/field.ts:136

The rendered field's SVG text element.

Inherited from

FieldDropdown.textElement_

---

textContent_

protected textContent_: Text | null = null;

Defined in: packages/blockly/core/field.ts:139

The rendered field's text content element.

Inherited from

FieldDropdown.textContent_

---

constants_

protected constants_: 
  | ConstantProvider
  | null = null;

Defined in: packages/blockly/core/field.ts:145

Constants associated with the source block's renderer.

Inherited from

FieldDropdown.constants_

---

maxDisplayLength

maxDisplayLength: number = 50;

Defined in: packages/blockly/core/field.ts:155

Maximum characters of text to display before adding an ellipsis.

Inherited from

FieldDropdown.maxDisplayLength

---

sourceBlock_

protected sourceBlock_: Block | null = null;

Defined in: packages/blockly/core/field.ts:158

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

Inherited from

FieldDropdown.sourceBlock_

---

isDirty_

protected isDirty_: boolean = true;

Defined in: packages/blockly/core/field.ts:161

Does this block need to be re-rendered?

Inherited from

FieldDropdown.isDirty_

---

visible_

protected visible_: boolean = true;

Defined in: packages/blockly/core/field.ts:164

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

Inherited from

FieldDropdown.visible_

---

enabled_

protected enabled_: boolean = true;

Defined in: packages/blockly/core/field.ts:169

Can the field value be changed using the editor on an editable block?

Inherited from

FieldDropdown.enabled_

---

EDITABLE

EDITABLE: boolean = true;

Defined in: packages/blockly/core/field.ts:192

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

Inherited from

FieldDropdown.EDITABLE

---

SEPARATOR

readonly static SEPARATOR: "separator" = 'separator';

Defined in: packages/blockly/core/field_dropdown.ts:44

Magic constant used to represent a separator in a list of dropdown items.

Inherited from

FieldDropdown.SEPARATOR

---

ARROW_CHAR

static ARROW_CHAR: string = '▾';

Defined in: packages/blockly/core/field_dropdown.ts:46

Inherited from

FieldDropdown.ARROW_CHAR

---

menu_

protected menu_: Menu | null = null;

Defined in: packages/blockly/core/field_dropdown.ts:52

The dropdown menu.

Inherited from

FieldDropdown.menu_

---

clickTarget_

clickTarget_: SVGElement | null = null;

Defined in: packages/blockly/core/field_dropdown.ts:91

The element the click handler is bound to.

Inherited from

FieldDropdown.clickTarget_

---

IMAGE_Y_OFFSET

protected static IMAGE_Y_OFFSET: number = 5;

Defined in: packages/blockly/core/field_dropdown.ts:97

The y offset from the top of the field to the top of the image, if an image is selected.

Inherited from

FieldDropdown.IMAGE_Y_OFFSET

---

IMAGE_Y_PADDING

protected static IMAGE_Y_PADDING: number;

Defined in: packages/blockly/core/field_dropdown.ts:100

The total vertical padding above and below an image.

Inherited from

FieldDropdown.IMAGE_Y_PADDING

---

isInitialized

isInitialized: boolean = false;

Defined in: packages/blockly/core/field_dropdown.ts:106

True once the field’s DOM has been created and it is safe to run ARIA updates in response to value changes.

Inherited from

FieldDropdown.isInitialized

---

menuGenerator_

protected menuGenerator_: MenuGenerator | undefined;

Defined in: packages/blockly/core/field_variable.ts:38

Overrides

FieldDropdown.menuGenerator_

---

defaultVariableName

defaultVariableName: string;

Defined in: packages/blockly/core/field_variable.ts:39

---

variableTypes

variableTypes: string[] | null = [];

Defined in: packages/blockly/core/field_variable.ts:48

All of the types of variables that will be available in this field's dropdown.

---

SERIALIZABLE

SERIALIZABLE: boolean = true;

Defined in: packages/blockly/core/field_variable.ts:57

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

Overrides

FieldDropdown.SERIALIZABLE

Accessors

size_

Get Signature

get protected size_(): Size;

Defined in: packages/blockly/core/field.ts:121

Gets the size of this field. Because getSize() and updateSize() have side effects, this acts as a shim for subclasses which wish to adjust field bounds when setting/getting the size without triggering unwanted rendering or other side effects. Note that subclasses must override both get and set if either is overridden; the implementation may just call directly through to super, but it must exist per the JS spec.

Returns

Size

Set Signature

set protected size_(newValue): void;

Defined in: packages/blockly/core/field.ts:125

Parameters

Parameter	Type
newValue	Size

Returns

void

Inherited from

FieldDropdown.size_

Methods

getConstants()

getConstants(): 
  | ConstantProvider
  | null;

Defined in: packages/blockly/core/field.ts:284

Get the renderer constant provider.

Returns

| ConstantProvider | null

The renderer constant provider.

Inherited from

FieldDropdown.getConstants

---

getSourceBlock()

getSourceBlock(): Block | null;

Defined in: packages/blockly/core/field.ts:304

Get the block this field is attached to.

Returns

Block | null

The block containing this field.

Throws

An error if the source block is not defined.

Inherited from

FieldDropdown.getSourceBlock

---

setAriaTypeName()

setAriaTypeName(ariaTypeName): void;

Defined in: packages/blockly/core/field.ts:332

Sets the ARIA-friendly label representation of this field's type.

Implementations are responsible for, and encouraged to, set a localized version of the ARIA representation of the field's type. To that end, the provided value may contain message references of the form %{BKY_...} (e.g. %{BKY_MY_FIELD_ARIA_TYPE}), which are replaced with the corresponding Blockly.Msg value.

Parameters

Parameter	Type	Description
ariaTypeName	string	An ARIA representation of the field's type.

Returns

void

Inherited from

FieldDropdown.setAriaTypeName

---

computeAriaLabel()

computeAriaLabel(includeTypeInfo?): string;

Defined in: packages/blockly/core/field.ts:391

Computes a descriptive ARIA label to represent this field with configurable verbosity.

A 'verbose' label includes type information, if available, whereas a non-verbose label only contains the field's value.

Note that this will always return the latest representation of the field's label which may differ from any previously set ARIA label for the field itself. Implementations are largely responsible for ensuring that the field's ARIA label is set correctly at relevant moments in the field's lifecycle (such as when its value changes).

Finally, it is never guaranteed that implementations use the label returned by this method for their actual ARIA label. Some implementations may rely on other contexts to convey information like the field's value. Example: checkboxes represent their checked/non-checked status (i.e. value) through a separate ARIA property.

If the field's value is empty then it will return a localized placeholder indicating that its value is empty. If this method returns an empty string, the output will be ignored when composing the block-level ARIA label. Make sure you want your label hidden from screenreaders before returning an empty string.

Parameters

Parameter	Type	Default value	Description
includeTypeInfo	boolean	true	Whether to include the field's type information in the returned label, if available.

Returns

string

Inherited from

FieldDropdown.computeAriaLabel

---

createBorderRect_()

protected createBorderRect_(): void;

Defined in: packages/blockly/core/field.ts:489

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.

Returns

void

Inherited from

FieldDropdown.createBorderRect_

---

createTextElement_()

protected createTextElement_(): void;

Defined in: packages/blockly/core/field.ts:512

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. Aria state is hidden; use the aria label for the field and/or containing block to expose content to screen readers. Text content for custom blocks can be set after creation.

Returns

void

Inherited from

FieldDropdown.createTextElement_

---

bindEvents_()

protected bindEvents_(): void;

Defined in: packages/blockly/core/field.ts:532

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

Returns

void

Inherited from

FieldDropdown.bindEvents_

---

saveLegacyState()

protected saveLegacyState(callingClass): string | null;

Defined in: packages/blockly/core/field.ts:610

Returns a stringified version of the XML state, if it should be used. Otherwise this returns null, to signal the field should use its own serialization.

Parameters

Parameter	Type	Description
callingClass	FieldProto	The class calling this method. Used to see if this has overridden any relevant hooks.

Returns

string | null

The stringified version of the XML state, or null.

Inherited from

FieldDropdown.saveLegacyState

---

loadLegacyState()

loadLegacyState(callingClass, state): boolean;

Defined in: packages/blockly/core/field.ts:637

Loads the given state using either the old XML hooks, if they should be used. Returns true to indicate loading has been handled, false otherwise.

Parameters

Parameter	Type	Description
callingClass	FieldProto	The class calling this method. Used to see if this has overridden any relevant hooks.
state	any	The state to apply to the field.

Returns

boolean

Whether the state was applied or not.

Inherited from

FieldDropdown.loadLegacyState

---

dispose()

dispose(): void;

Defined in: packages/blockly/core/field.ts:656

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

Returns

void

Inherited from

FieldDropdown.dispose

---

updateEditable()

updateEditable(): void;

Defined in: packages/blockly/core/field.ts:675

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

Returns

void

Inherited from

FieldDropdown.updateEditable

---

setEnabled()

setEnabled(enabled): void;

Defined in: packages/blockly/core/field.ts:696

Set whether this field's value can be changed using the editor when the source block is editable.

Parameters

Parameter	Type	Description
enabled	boolean	True if enabled.

Returns

void

Inherited from

FieldDropdown.setEnabled

---

isEnabled()

isEnabled(): boolean;

Defined in: packages/blockly/core/field.ts:707

Check whether this field's value can be changed using the editor when the source block is editable.

Returns

boolean

Whether this field is enabled.

Inherited from

FieldDropdown.isEnabled

---

isClickable()

isClickable(): boolean;

Defined in: packages/blockly/core/field.ts:716

Check whether this field defines the showEditor_ function.

Returns

boolean

Whether this field is clickable.

Inherited from

FieldDropdown.isClickable

---

isClickableInFlyout()

isClickableInFlyout(autoClosingFlyout): boolean;

Defined in: packages/blockly/core/field.ts:735

Check whether the field should be clickable while the block is in a flyout. The default is that fields are clickable in always-open flyouts such as the simple toolbox, but not in autoclosing flyouts such as the category toolbox. Subclasses may override this function to change this behavior. Note that isClickable must also return true for this to have any effect.

Parameters

Parameter	Type	Description
autoClosingFlyout	boolean	true if the containing flyout is an auto-closing one.

Returns

boolean

Whether the field should be clickable while the block is in a flyout.

Inherited from

FieldDropdown.isClickableInFlyout

---

isCurrentlyEditable()

isCurrentlyEditable(): boolean;

Defined in: packages/blockly/core/field.ts:747

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 or be currently disabled.

Returns

boolean

Whether this field is currently enabled, editable and on an editable block.

Inherited from

FieldDropdown.isCurrentlyEditable

---

isSerializable()

isSerializable(): boolean;

Defined in: packages/blockly/core/field.ts:762

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.

Inherited from

FieldDropdown.isSerializable

---

isVisible()

isVisible(): boolean;

Defined in: packages/blockly/core/field.ts:784

Gets whether this editable field is visible or not.

Returns

boolean

True if visible.

Inherited from

FieldDropdown.isVisible

---

setValidator()

setValidator(handler): void;

Defined in: packages/blockly/core/field.ts:821

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.

Parameters

Parameter	Type	Description
handler	FieldValidator<string>	The validator function or null to clear a previous validator.

Returns

void

Inherited from

FieldDropdown.setValidator

---

getSvgRoot()

getSvgRoot(): SVGGElement | null;

Defined in: packages/blockly/core/field.ts:840

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

Returns

SVGGElement | null

The group element.

Inherited from

FieldDropdown.getSvgRoot

---

getBorderRect()

protected getBorderRect(): SVGRectElement;

Defined in: packages/blockly/core/field.ts:850

Gets the border rectangle element.

Returns

SVGRectElement

The border rectangle element.

Throws

An error if the border rectangle element is not defined.

Inherited from

FieldDropdown.getBorderRect

---

getTextElement()

protected getTextElement(): SVGTextElement;

Defined in: packages/blockly/core/field.ts:863

Gets the text element.

Returns

SVGTextElement

The text element.

Throws

An error if the text element is not defined.

Inherited from

FieldDropdown.getTextElement

---

getTextContent()

protected getTextContent(): Text;

Defined in: packages/blockly/core/field.ts:876

Gets the text content.

Returns

Text

The text content.

Throws

An error if the text content is not defined.

Inherited from

FieldDropdown.getTextContent

---

repositionForWindowResize()

repositionForWindowResize(): boolean;

Defined in: packages/blockly/core/field.ts:953

A developer hook to reposition the WidgetDiv during a window resize. You need to define this hook if your field has a WidgetDiv that needs to reposition itself when the window is resized. For example, text input fields define this hook so that the input WidgetDiv can reposition itself on a window resize event. This is especially important when modal inputs have been disabled, as Android devices will fire a window resize event when the soft keyboard opens.

If you want the WidgetDiv to hide itself instead of repositioning, return false. This is the default behavior.

DropdownDivs already handle their own positioning logic, so you do not need to override this function if your field only has a DropdownDiv.

Returns

boolean

True if the field should be repositioned, false if the WidgetDiv should hide itself instead.

Inherited from

FieldDropdown.repositionForWindowResize

---

updateSize_()

protected updateSize_(margin?): void;

Defined in: packages/blockly/core/field.ts:962

Updates the size of the field based on the text.

Parameters

Parameter	Type	Description
margin?	number	margin to use when positioning the text element.

Returns

void

Inherited from

FieldDropdown.updateSize_

---

positionTextElement_()

protected positionTextElement_(xOffset, contentWidth): void;

Defined in: packages/blockly/core/field.ts:995

Position a field's text element after a size change. This handles both LTR and RTL positioning.

Parameters

Parameter	Type	Description
xOffset	number	x offset to use when positioning the text element.
contentWidth	number	The content width.

Returns

void

Inherited from

FieldDropdown.positionTextElement_

---

positionBorderRect_()

protected positionBorderRect_(): void;

Defined in: packages/blockly/core/field.ts:1023

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

Returns

void

Inherited from

FieldDropdown.positionBorderRect_

---

getSize()

getSize(): Size;

Defined in: packages/blockly/core/field.ts:1046

Returns the height and width of the field.

This should in general be the only place render_ gets called from.

Returns

Size

Height and width.

Inherited from

FieldDropdown.getSize

---

onLocationChange()

onLocationChange(_): void;

Defined in: packages/blockly/core/field.ts:1107

Notifies the field that it has changed locations.

Parameters

Parameter	Type	Description
_	Coordinate	The location of this field's block's top-start corner in workspace coordinates.

Returns

void

Inherited from

FieldDropdown.onLocationChange

---

getDisplayText_()

protected getDisplayText_(): string;

Defined in: packages/blockly/core/field.ts:1115

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.

Inherited from

FieldDropdown.getDisplayText_

---

forceRerender()

forceRerender(): void;

Defined in: packages/blockly/core/field.ts:1179

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.

Returns

void

Inherited from

FieldDropdown.forceRerender

---

setValue()

setValue(newValue, fireChangeEvent?): void;

Defined in: packages/blockly/core/field.ts:1197

Sealed

Used to change the value of the field. Handles validation and events. Subclasses should override doClassValidation_ and doValueUpdate_ rather than this method.

Parameters

Parameter	Type	Default value	Description
newValue	any	undefined	New value.
fireChangeEvent	boolean	true	Whether to fire a change event. Defaults to true. Should usually be true unless the change will be reported some other way, e.g. an intermediate field change event.

Returns

void

Inherited from

FieldDropdown.setValue

---

doValueInvalid_()

protected doValueInvalid_(_invalidValue, _fireChangeEvent?): void;

Defined in: packages/blockly/core/field.ts:1352

Used to notify the field an invalid value was input. Can be overridden by subclasses, see FieldTextInput. No-op by default.

Parameters

Parameter	Type	Default value	Description
_invalidValue	any	undefined	The input value that was determined to be invalid.
_fireChangeEvent	boolean	true	Whether to fire a change event if the value changes.

Returns

void

Inherited from

FieldDropdown.doValueInvalid_

---

onMouseDown_()

protected onMouseDown_(e): void;

Defined in: packages/blockly/core/field.ts:1363

Handle a pointerdown event on a field.

Parameters

Parameter	Type	Description
e	PointerEvent	Pointer down event.

Returns

void

Inherited from

FieldDropdown.onMouseDown_

---

setTooltip()

setTooltip(newTip): void;

Defined in: packages/blockly/core/field.ts:1381

Sets the tooltip for this field.

Parameters

Parameter	Type	Description
newTip	TipInfo | null	The text for the tooltip, a function that returns the text for the tooltip, a parent object whose tooltip will be used, or null to display the tooltip of the parent block. To not display a tooltip pass the empty string.

Returns

void

Inherited from

FieldDropdown.setTooltip

---

getTooltip()

getTooltip(): string;

Defined in: packages/blockly/core/field.ts:1400

Returns the tooltip text for this field.

Returns

string

The tooltip text for this field.

Inherited from

FieldDropdown.getTooltip

---

getClickTarget_()

protected getClickTarget_(): Element | null;

Defined in: packages/blockly/core/field.ts:1416

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.

Returns

Element | null

Element to bind click handler to.

Inherited from

FieldDropdown.getClickTarget_

---

getAbsoluteXY_()

protected getAbsoluteXY_(): Coordinate;

Defined in: packages/blockly/core/field.ts:1426

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.

Returns

Coordinate

Object with .x and .y properties.

Inherited from

FieldDropdown.getAbsoluteXY_

---

getFlipRtl()

getFlipRtl(): boolean;

Defined in: packages/blockly/core/field.ts:1481

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

Returns

boolean

True if we should flip in RTL.

Inherited from

FieldDropdown.getFlipRtl

---

onShortcut()

onShortcut(_shortcut): boolean;

Defined in: packages/blockly/core/field.ts:1491

Handles the given keyboard shortcut.

Parameters

Parameter	Type	Description
_shortcut	KeyboardShortcut	The shortcut to be handled.

Returns

boolean

True if the shortcut has been handled, false otherwise.

Inherited from

FieldDropdown.onShortcut

---

getFocusableElement()

getFocusableElement(): HTMLElement | SVGElement;

Defined in: packages/blockly/core/field.ts:1496

See IFocusableNode.getFocusableElement.

Returns

HTMLElement | SVGElement

Inherited from

FieldDropdown.getFocusableElement

---

getFocusableTree()

getFocusableTree(): IFocusableTree;

Defined in: packages/blockly/core/field.ts:1504

See IFocusableNode.getFocusableTree.

Returns

IFocusableTree

Inherited from

FieldDropdown.getFocusableTree

---

onNodeFocus()

onNodeFocus(): void;

Defined in: packages/blockly/core/field.ts:1513

See IFocusableNode.onNodeFocus.

Returns

void

Inherited from

FieldDropdown.onNodeFocus

---

onNodeBlur()

onNodeBlur(): void;

Defined in: packages/blockly/core/field.ts:1521

See IFocusableNode.onNodeBlur.

Returns

void

Inherited from

FieldDropdown.onNodeBlur

---

canBeFocused()

canBeFocused(): boolean;

Defined in: packages/blockly/core/field.ts:1524

See IFocusableNode.canBeFocused.

Returns

boolean

Inherited from

FieldDropdown.canBeFocused

---

performAction()

performAction(): void;

Defined in: packages/blockly/core/field.ts:1532

Handles the user acting on this field via keyboard navigation. Shows and focuses the field editor.

Returns

void

Inherited from

FieldDropdown.performAction

---

isFullBlockField()

isFullBlockField(): boolean;

Defined in: packages/blockly/core/field_dropdown.ts:219

This is hacky way of determining if a dropdown field is a full-block field or not. The constants that control the border rect are the same ones that determine how we render full-block dropdown fields. It's a full-block field if it doesn't have the border rect (and it's a simple reporter block).

Returns

boolean

true if this field should be treated as a full-block field

Inherited from

FieldDropdown.isFullBlockField

---

createTextArrow_()

protected createTextArrow_(): void;

Defined in: packages/blockly/core/field_dropdown.ts:240

Create a tspan based arrow.

Returns

void

Inherited from

FieldDropdown.createTextArrow_

---

createSVGArrow_()

protected createSVGArrow_(): void;

Defined in: packages/blockly/core/field_dropdown.ts:260

Create an SVG based arrow.

Returns

void

Inherited from

FieldDropdown.createSVGArrow_

---

showEditor_()

protected showEditor_(e?): void;

Defined in: packages/blockly/core/field_dropdown.ts:282

Create a dropdown menu under the text.

Parameters

Parameter	Type	Description
e?	MouseEvent	Optional mouse event that triggered the field to open, or undefined if triggered programmatically.

Returns

void

Inherited from

FieldDropdown.showEditor_

---

dropdownDispose_()

protected dropdownDispose_(): void;

Defined in: packages/blockly/core/field_dropdown.ts:377

Disposes of events and DOM-references belonging to the dropdown editor.

Returns

void

Inherited from

FieldDropdown.dropdownDispose_

---

isOptionListDynamic()

isOptionListDynamic(): boolean;

Defined in: packages/blockly/core/field_dropdown.ts:411

Returns

boolean

True if the option list is generated by a function. Otherwise false.

Inherited from

FieldDropdown.isOptionListDynamic

---

getOptions()

getOptions(useCache?): MenuOption[];

Defined in: packages/blockly/core/field_dropdown.ts:424

Return a list of the options for this dropdown.

Parameters

Parameter	Type	Description
useCache?	boolean	For dynamic options, whether or not to use the cached options or to re-generate them.

Returns

MenuOption[]

A non-empty array of option tuples: (human-readable text or image, language-neutral name).

Throws

If generated options are incorrectly structured.

Inherited from

FieldDropdown.getOptions

---

setOptions()

setOptions(menuGenerator): void;

Defined in: packages/blockly/core/field_dropdown.ts:444

Update the options on this dropdown. This will reset the selected item to the first item in the list.

Parameters

Parameter	Type	Description
menuGenerator	MenuGenerator	The array of options or a generator function.

Returns

void

Inherited from

FieldDropdown.setOptions

---

applyColour()

applyColour(): void;

Defined in: packages/blockly/core/field_dropdown.ts:515

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

Returns

void

Inherited from

FieldDropdown.applyColour

---

render_()

protected render_(): void;

Defined in: packages/blockly/core/field_dropdown.ts:536

Draws the border with the correct width.

Returns

void

Inherited from

FieldDropdown.render_

---

getText_()

protected getText_(): string | null;

Defined in: packages/blockly/core/field_dropdown.ts:680

Use the getText_ developer hook to override the field's text representation. Get the selected option text. If the selected option is an image we return the image alt text. If the selected option is an HTMLElement, return the title, ariaLabel, or innerText of the element.

If you use HTMLElement options in Node.js and call this function, ensure that you are supplying an implementation of HTMLElement, such as through jsdom-global.

Returns

string | null

Selected option text.

Inherited from

FieldDropdown.getText_

---

trimOptions()

protected trimOptions(options): object;

Defined in: packages/blockly/core/field_dropdown.ts:731

Factor out common words in statically defined options. Create prefix and/or suffix labels.

Parameters

Parameter	Type
options	MenuOption[]

Returns

object

options

options: MenuOption[];

prefix?

optional prefix?: string;

suffix?

optional suffix?: string;

Inherited from

FieldDropdown.trimOptions

---

validateOptions()

protected validateOptions(options): void;

Defined in: packages/blockly/core/field_dropdown.ts:833

Validates the data structure to be processed as an options list.

Parameters

Parameter	Type	Description
options	MenuOption[]	The proposed dropdown options.

Returns

void

Throws

If proposed options are incorrectly structured.

Inherited from

FieldDropdown.validateOptions

---

getAriaTypeName()

getAriaTypeName(): string | null;

Defined in: packages/blockly/core/field_dropdown.ts:890

Gets an ARIA-friendly label representation of this field's type.

Implementations are responsible for, and encouraged to, return a localized version of the ARIA representation of the field's type.

Returns

string | null

An ARIA representation of the field's type or a default if it is unspecified.

Inherited from

FieldDropdown.getAriaTypeName

---

recomputeAriaContext()

recomputeAriaContext(): boolean;

Defined in: packages/blockly/core/field_dropdown.ts:938

Sets additional aria state.

Returns

boolean

Inherited from

FieldDropdown.recomputeAriaContext

---

configure_()

protected configure_(config): void;

Defined in: packages/blockly/core/field_variable.ts:121

Configure the field based on the given map of options.

Parameters

Parameter	Type	Description
config	FieldVariableConfig	A map of options to configure the field based on.

Returns

void

Overrides

FieldDropdown.configure_

---

initModel()

initModel(): void;

Defined in: packages/blockly/core/field_variable.ts:131

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.

Returns

void

Overrides

FieldDropdown.initModel

---

initView()

initView(): void;

Defined in: packages/blockly/core/field_variable.ts:149

Create the block UI for this dropdown.

Returns

void

Overrides

FieldDropdown.initView

---

shouldAddBorderRect_()

shouldAddBorderRect_(): boolean;

Defined in: packages/blockly/core/field_variable.ts:154

Whether or not the dropdown should add a border rect.

Returns

boolean

True if the dropdown field should add a border rect.

Overrides

FieldDropdown.shouldAddBorderRect_

---

fromXml()

fromXml(fieldElement): void;

Defined in: packages/blockly/core/field_variable.ts:172

Initialize this field based on the given XML.

Parameters

Parameter	Type	Description
fieldElement	Element	The element containing information about the variable field's state.

Returns

void

Overrides

FieldDropdown.fromXml

---

toXml()

toXml(fieldElement): Element;

Defined in: packages/blockly/core/field_variable.ts:219

Serialize this field to XML.

Parameters

Parameter	Type	Description
fieldElement	Element	The element to populate with info about the field's state.

Returns

Element

The element containing info about the field's state.

Overrides

FieldDropdown.toXml

---

setSourceBlock()

setSourceBlock(block): void;

Defined in: packages/blockly/core/field_variable.ts:284

Attach this field to a block.

Parameters

Parameter	Type	Description
block	Block	The block containing this field.

Returns

void

Overrides

FieldDropdown.setSourceBlock

---

getValue()

getValue(): string | null;

Defined in: packages/blockly/core/field_variable.ts:296

Get the variable's ID.

Returns

string | null

Current variable's ID.

Overrides

FieldDropdown.getValue

---

getText()

getText(): string;

Defined in: packages/blockly/core/field_variable.ts:306

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.

Overrides

FieldDropdown.getText

---

getDefaultType()

protected getDefaultType(): string;

Defined in: packages/blockly/core/field_variable.ts:327

Gets the type of this field's default variable.

Returns

string

The default type for this variable field.

---

getValidator()

getValidator(): 
  | FieldDropdownValidator
  | null;

Defined in: packages/blockly/core/field_variable.ts:339

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

| FieldDropdownValidator | null

Validation function, or null.

Overrides

FieldDropdown.getValidator

---

doClassValidation_()

protected doClassValidation_(newValue?): string | null;

Defined in: packages/blockly/core/field_variable.ts:355

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

Parameters

Parameter	Type	Description
newValue?	any	The ID of the new variable to set.

Returns

string | null

The validated ID, or null if invalid.

Overrides

FieldDropdown.doClassValidation_

---

doValueUpdate_()

protected doValueUpdate_(newId): void;

Defined in: packages/blockly/core/field_variable.ts:390

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.

Parameters

Parameter	Type	Description
newId	string	The value to be saved.

Returns

void

Overrides

FieldDropdown.doValueUpdate_

---

onItemSelected_()

protected onItemSelected_(menu, menuItem): void;

Defined in: packages/blockly/core/field_variable.ts:509

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.

Parameters

Parameter	Type	Description
menu	Menu	The Menu component clicked.
menuItem	MenuItem	The MenuItem selected within menu.

Returns

void

Overrides

FieldDropdown.onItemSelected_

---

dropdownCreate()

static dropdownCreate(this): MenuOption[];

Defined in: packages/blockly/core/field_variable.ts:564

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

Parameters

Parameter	Type
this	FieldVariable

Returns

MenuOption[]

Array of variable names/id tuples.

---

getAriaValue()

getAriaValue(): string;

Defined in: packages/blockly/core/field_variable.ts:625

Gets an ARIA-friendly label representation of this field's value.

Implementations are responsible for, and encouraged to, return a localized version of the ARIA representation of the field's value.

Returns

string

An ARIA representation of the field's text.

Overrides

FieldDropdown.getAriaValue