Field class
Abstract class for an editable field.
Signature:
export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable, ISerializable
Implements: IASTNodeLocationSvg, IASTNodeLocationWithBlock, IKeyboardAccessible, IRegistrable, ISerializable
Constructors
Constructor | Modifiers | Description |
---|---|---|
(constructor)(value, validator, config) | Constructs a new instance of the Field class |
Properties
Property | Modifiers | Type | Description |
---|---|---|---|
borderRect_ | protected |
SVGRectElement | null | The rendered field's SVG border element. |
clickTarget_ | protected |
Element | null | The element the click handler is bound to. |
constants_ | protected |
ConstantProvider | null | Constants associated with the source block's renderer. |
CURSOR | string | Mouse cursor style when over the hotspot that initiates the editor. | |
DEFAULT_VALUE | T | null | To overwrite the default value which is set in **Field**, directly update the prototype. Example: |
|
EDITABLE | boolean | Editable fields usually show some sort of UI indicating they are editable. They will also be saved by the serializer. | |
enabled_ | protected |
boolean | Can the field value be changed using the editor on an editable block? |
fieldGroup_ | protected |
SVGGElement | null | The rendered field's SVG group element. |
isDirty_ | protected |
boolean | Does this block need to be re-rendered? |
maxDisplayLength | number | Maximum characters of text to display before adding an ellipsis. | |
name? | string | (Optional) Name of field. Unique within each block. Static labels are usually unnamed. | |
NBSP |
|
(not declared) | Non-breaking space. |
SERIALIZABLE | boolean | Serializable fields are saved by the serializer, non-serializable fields are not. Editable fields should also be serializable. This is not the case by default so that SERIALIZABLE is backwards compatible. | |
size_ | protected |
Size | |
SKIP_SETUP |
|
unique symbol | 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. |
sourceBlock_ | protected |
Block | null | Block this field is attached to. Starts as null, then set in init. |
textContent_ | protected |
Text | null | The rendered field's text content element. |
textElement_ | protected |
SVGTextElement | null | The rendered field's SVG text element. |
validator_ | protected |
FieldValidator<T> | null | Validation function called when user edits an editable field. |
value_ | protected |
T | null | |
visible_ | protected |
boolean | Is the field visible, or hidden due to the block being collapsed? |
Methods
Method | Modifiers | Description |
---|---|---|
applyColour() | Updates the field to match the colour/style of the block. Non-abstract sub-classes may wish to implement this if the colour of the field depends on the colour of the block. It will automatically be called at relevant times, such as when the parent block or renderer changes. See the field documentation for more information, or FieldDropdown for an example. |
|
bindEvents_() | protected |
Bind events to the field. Can be overridden by subclasses if they need to do custom input handling. |
configure_(config) | protected |
Process the configuration map passed to the field. |
createBorderRect_() | protected |
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_() | protected |
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. |
doClassValidation_(newValue) | protected |
Validate the changes to a field's value before they are set. See **FieldDropdown** for an example of subclass implementation. **NOTE:** Validation returns one option between |
doClassValidation_(newValue) | protected |
|
doValueInvalid_(_invalidValue, _fireChangeEvent) | protected |
Used to notify the field an invalid value was input. Can be overridden by subclasses, see FieldTextInput. No-op by default. |
doValueUpdate_(newValue) | protected |
Used to update the value of a field. Can be overridden by subclasses to do custom storage of values/updating of external things. |
fromJson(_options) | static |
Subclasses should reimplement this method to construct their Field subclass from a JSON arg object. It is an error to attempt to register a field subclass in the FieldRegistry if that subclass has not overridden this method. |
getAbsoluteXY_() | protected |
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. |
getBorderRect() | protected |
Gets the border rectangle element. |
getClickTarget_() | protected |
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. |
getConstants() | Get the renderer constant provider. | |
getDisplayText_() | protected |
Get the text from this field to display on the block. May differ from getText due to ellipsis, and other formatting. |
getFlipRtl() | Returns whether or not we should flip the field in RTL. | |
getSize() | Returns the height and width of the field. This should *in general* be the only place render_ gets called from. |
|
getSourceBlock() | Get the block this field is attached to. | |
getSvgRoot() | Gets the group element for this editable field. Used for measuring the size and for positioning. | |
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. |
getText() | Get the text from this field. Override getText_ to provide a different behavior than simply casting the value to a string. | |
getTextContent() | protected |
Gets the text content. |
getTextElement() | protected |
Gets the text element. |
getTooltip() | Returns the tooltip text for this field. | |
getValidator() | Gets the validation function for editable fields, or null if not set. | |
getValue() | Get the current value of the field. | |
initModel() | Initializes the model of the field after it has been installed on a block. No-op by default. | |
initView() | protected |
Create the block UI for this field. |
isClickable() | Check whether this field defines the showEditor_ function. | |
isClickableInFlyout(autoClosingFlyout) | 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. | |
isEnabled() | Check whether this field's value can be changed using the editor when the source block is editable. | |
isFullBlockField() | protected |
Defines whether this field should take up the full block or not. Be cautious when overriding this function. It may not work as you expect / intend because the behavior was kind of hacked in. If you are thinking about overriding this function, post on the forum with your intended behavior to see if there's another approach. |
isSerializable() | Check whether this field should be serialized by the XML renderer. Handles the logic for backwards compatibility and incongruous states. | |
isTabNavigable() | Returns whether or not the field is tab navigable. | |
isVisible() | Gets whether this editable field is visible or not. | |
loadLegacyState(callingClass, state) | 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. | |
onLocationChange(_) | Notifies the field that it has changed locations. | |
onMouseDown_(e) | protected |
Handle a pointerdown event on a field. |
onShortcut(_shortcut) | Handles the given keyboard shortcut. | |
positionBorderRect_() | protected |
Position a field's border rect after a size change. |
positionTextElement_(xOffset, contentWidth) | protected |
Position a field's text element after a size change. This handles both LTR and RTL positioning. |
render_() | protected |
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(). |
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. 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. |
|
saveLegacyState(callingClass) | protected |
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. |
setEnabled(enabled) | Set whether this field's value can be changed using the editor when the source block is editable. | |
setSourceBlock(block) | Attach this field to a block. | |
setTooltip(newTip) | Sets the tooltip for this field. | |
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. |
|
setValue(newValue, fireChangeEvent) | Used to change the value of the field. Handles validation and events. Subclasses should override doClassValidation_ and doValueUpdate_ rather than this method. | |
showEditor_(_e) | protected |
A developer hook to create an editor for the field. This is no-op by default, and must be overriden to create an editor. |
updateEditable() | Add or remove the UI indicating if this field is editable or not. | |
updateSize_(margin) | protected |
Updates the size of the field based on the text. |