Blockly. FieldVariable
Constructor
FieldVariable
new FieldVariable(varName, opt_validator, opt_variableTypes, opt_defaultType, opt_config)
Class for a variable's dropdown field.
Parameter |
|
---|---|
varName |
string The default name for the variable. If null, a unique variable name will be generated. Value may be null. |
opt_validator |
Optional function() 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. |
opt_variableTypes |
Optional Array of string A list of the types of variables to include in the dropdown. |
opt_defaultType |
Optional string The type of variable to create if this field's value is not explicitly set. Defaults to ''. |
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.FieldDropdown
Properties
CURSOR
Mouse cursor style when over the hotspot that initiates the editor.
- Inherited from
- Blockly.FieldDropdown#CURSOR
defaultVariableName
string
The initial variable name passed to this field's constructor, or an empty string if a name wasn't provided. Used to create the initial variable.
disposed
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_
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
menuGenerator_
non-null function(this = Blockly.FieldVariable) returns non-null Array of non-null Array
An array of options for a dropdown list, or a function which generates these options.
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_
unknown
The size of the area rendered by the field.
- Inherited from
- Blockly.Field#size_
sourceBlock_
unknown
Block this field is attached to. Starts as null, then set in init.
- Inherited from
- Blockly.Field#sourceBlock_
validator_
unknown
Validation function called when user edits an editable field.
- Inherited from
- Blockly.Field#validator_
value_
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_
unknown
Is the field visible, or hidden due to the block being collapsed?
- Inherited from
- Blockly.Field#visible_
Methods
dropdownCreate
dropdownCreate() returns Array of non-null Array
Return a sorted list of variable names for variable dropdown menus. Include a special option at the end for creating a new variable name.
- Returns
-
non-null Array of non-null Array
Array of variable names/id tuples.
fromJson
fromJson(options) returns Blockly.FieldVariable
Construct a FieldVariable from a JSON arg object, dereferencing any string table references.
Parameter |
|
---|---|
options |
Object A JSON object with options (variable, variableTypes, and defaultType). Value must not be null. |
- Returns
-
non-null Blockly.FieldVariable
The new field instance.
bindEvents_
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.
configure_
configure_(config)
Configure the field based on the given map of options.
Parameter |
|
---|---|
config |
Object A map of options to configure the field based on. Value must not be null. |
createBorderRect_
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_
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
dispose()
Dispose of all DOM objects and events belonging to this editable field.
- Inherited from
- Blockly.Field#dispose
doClassValidation_
doClassValidation_(opt_newValue) returns string
Ensure that the id belongs to a valid variable of an allowed type.
Parameter |
|
---|---|
opt_newValue |
Optional any type The id of the new variable to set. |
- Returns
-
nullable string
The validated id, or null if invalid.
doValueInvalid_
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 |
The input value that was determined to be invalid. |
- Inherited from
- Blockly.Field#doValueInvalid_
doValueUpdate_
doValueUpdate_(newId)
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.
Parameter |
|
---|---|
newId |
any type The value to be saved. |
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.
- Inherited from
- Blockly.Field#forceRerender
fromXml
fromXml(fieldElement)
Initialize this field based on the given XML.
Parameter |
|
---|---|
fieldElement |
Element The element containing information about the variable field's state. Value must not be null. |
getDisplayText_
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.
getOptions
getOptions(opt_useCache) returns Array of non-null Array
Return a list of the options for this dropdown.
Parameter |
|
---|---|
opt_useCache |
Optional For dynamic options, whether or not to use the cached options or to re-generate them. |
- Inherited from
- Blockly.FieldDropdown#getOptions
- Throws
-
If generated options are incorrectly structured.
- Returns
-
A non-empty array of option tuples: (human-readable text or image, language-neutral name).
getParentInput
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_
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, which is the selected variable's name.
- Returns
-
string
The selected variable's name, or the empty string if no variable is selected.
getValidator
getValidator() returns function()
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
-
function()
Validation function, or null.
getValue
getValue() returns string
Get the variable's ID.
- Returns
-
string
Current variable's ID.
getVariable
getVariable() returns Blockly.VariableModel
Get the variable model for the selected variable. Not guaranteed to be in the variable map on the workspace (e.g. if accessed after the variable has been deleted).
- Returns
-
Blockly.VariableModel
The selected variable, or null if none was selected.
init
init()
Initialize everything to render this field. Override methods initModel and initView rather than this method.
- Inherited from
- Blockly.Field#init
initModel
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
initView()
Create the block UI for this dropdown.
- Inherited from
- Blockly.FieldDropdown#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
isOptionListDynamic
isOptionListDynamic() returns boolean
- Inherited from
- Blockly.FieldDropdown#isOptionListDynamic
- Returns
-
True if the option list is generated by a function. Otherwise false.
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
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
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.FieldDropdown#onBlocklyAction
- Returns
-
True if the field handled the action, false otherwise.
onItemSelected
onItemSelected(menu, menuItem)
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.
Parameter |
|
---|---|
menu |
The Menu component clicked. Value must not be null. |
menuItem |
The MenuItem selected within menu. Value must not be null. |
onMouseDown_
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
referencesVariables() returns boolean
Overrides referencesVariables(), indicating this field refers to a variable.
- Inherited from
- Blockly.Field#referencesVariables
- Returns
-
True.
refreshVariableName
refreshVariableName()
Refreshes the name of the variable by grabbing the name of the model. Used when a variable gets renamed, but the ID stays the same. Should only be called by the block.
setCursorSvg
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
setMarkerSvg
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. |
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
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
toXml
toXml(fieldElement) returns Element
Serialize this field to 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
updateColour()
Updates the dropdown arrow to match the colour/style of the block.
- Inherited from
- Blockly.FieldDropdown#updateColour
updateEditable
updateEditable()
Add or remove the UI indicating if this field is editable or not.
- Inherited from
- Blockly.Field#updateEditable
updateSize_
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.