FileField
Widget

A file input field that wraps the native <input type="file" /> element. It allows users to browse and select files from their device. Configure multiple to allow selecting more than one file, and use accept to restrict which file types are offered. The selected files are available via the files property. For a more polished file selection experience with drag-and-drop support, consider using FilePicker instead.

new FileField({ appendTo : targetElement, width : 300, multiple : true, accept : 'image/*', label : 'Pick multiple images', style : 'display: block' }); new FileField({ appendTo : targetElement, width : 300, label : 'Pick single file on any type', style : 'display: block; margin-top: 2em;' });

const fileField = new FileField({
    label    : 'Attachment',
    accept   : '.pdf,.docx',
    multiple : true,
    appendTo : document.body,
    onChange({ value }) {
        console.log('Selected files:', fileField.files);
    }
});

Useful configs and properties

Config / Property	Description
multiple	Allow selecting multiple files
accept	Comma-separated list of accepted file extensions or MIME types
files	The `FileList` of selected files (read-only)
label	Label text displayed beside the field

Configs

Configs are options you supply in a configuration object when creating an instance of this class

listeners : Object

Events

The listener set for this object.

An object whose property names are the names of events to handle, or options which modifiy how the handlers are called.

See addListener for details about the options.

Listeners can be specified in target class config and they will be merged with any listeners specified in the instantiation config. Class listeners will be fired first:

class MyStore extends Store({
    static configurable = {
        listeners : {
            myCustomEvent() {
            },
            load : {
                prio : 10000,
                fn() { // this load listener handles things first }
            }
        }
    };
});

let store = new MyStore({
  listeners: {
    load: () => { // This load listener runs after the class's },
    ...
  }
});

Handlers as function name

Object event handlers may be specified as a function name. If a string is specified, it is the name of the function in the thisObj object.

If the string begins with up., this object's ownership hierarchy (if present) is scanned for an object which implements that function name:

new Popup({
    tbar : {
        items : {
            myCombo : {
                type      : 'combo',
                editable  : false,
                label     : 'Type',
                listeners : {
                    // Look in owner chain for this function name
                    change : 'up.onFilterChange'
                },
                items     : [
                    'Event',
                    'Task',
                    'Appointment'
                ]
            }
        }
    },
    items : {
        ...
    },
    onFilterChange({ value }) {
        // Handle event type selection here
    }
});

accept : String

Comma-separated list of file extensions or MIME type to accept. E.g. ".jpg,.png,.doc" or "image/*". Null by default, allowing all files.
multiple : Boolean

Set to true to allow picking multiple files. Note that when set to a truthy value, the field is set to accept multiple files, but the value returned will be an empty string since this is what is rendered into the HTML.
ariaDescription : String

ADVANCED
Field

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject into an element which will be linked using the aria-describedby attribute.

The purpose of the aria-describedby attribute is to provide additional descriptive information for assistive technologies to provide more detailed information about the widget's purpose and state.

This extra description is announced by screen readers after the ariaLabel, providing users with a more comprehensive understanding of the widget's functionality and context. It can be used to convey additional instructions, state information, or any other relevant details that may assist users in effectively interacting with the widget.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.
ariaLabel : String

ADVANCED
Field

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject as the aria-label attribute.

The purpose of the aria-label attribute is to provide an accessible name for assistive technologies. This is analogous to a <label> element for form fields and is especially important for interactive widgets such as buttons, form fields, etc. that may not have visible text content that can be used as a label - for example an icon-only button.

By providing an aria-label, this ensures that assistive technologies can identify the widget and operate it by this identifier. Voice activation uses this label to allow users to interact with the widget using voice commands. Screen readers also use this label to announce the widget to users with visual impairments, providing them with the necessary information to understand the purpose of the widget and how to interact with it.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.
keyMap : Object<String, KeyMapConfig>
KeyMap
An object whose keys are the key name and optional modifier prefixes: 'Ctrl+', 'Alt+', 'Meta+', and 'Shift+' (case-insensitive). The values are the name of the instance method to call when the keystroke is received.

For example:
```
 keyMap : {
     'Ctrl+A': 'onSelectAll',
     'Ctrl+Z': 'onUndo',
     't'     : 'gotoNow',
     [/\d/]  : 'onDigit'
 }
```
If a key is a visible character (as above), and not modified by any modifier keys, and emanates from an editable element (such as an <input> or <textarea>), the keystroke is ignored. This is to allow the browser to handle typing in editable elements.

Target element filtering

By default, the keyMap will process keystrokes from any element within the widget.

This can be filtered by providing a targetSelector property in the keyMap. If provided, only keystrokes originating from elements matching the targetSelector (or their descendants) will be processed by the keyMap.

For example:
```
// Only accept keys from elements with class 'my-class' or their descendants.
keyMap : {
   targetSelector : '.my-class',
  'Enter'         : 'actionToPerformOnEnter'
}
```
This can be done on a more granular level for each keyMap entry by providing a targetSelector property in the action config object:
```
keyMap : {
    'Enter' : {
        handler        : 'actionToPerformOnEnter',
        targetSelector : '.my-class'
    }
}
```
Delegation

In addition to key names, the special key 'delegate' can be included to specify additional objects that have their own keyMap. If a keystroke is not handled by this keyMap, the delegates are processed until one has a matching entry in its keyMap. The value of the delegate key can be a single string, an array of strings or an object whose truthy keys are dot paths identifying the delegate(s) related to this instance.

For example:
```
 keyMap : {
     delegate : ['widgetMap.foo', 'widgetMap.bar', 'tbar']
 }
```
An widget with the above keyMap will delegate to the child widgets named foo and bar via the widget's widgetMap. In addition, the tbar property of the widget will also be considered as a delegate.

The following is equivalent to the above delegate but using an object. This form can be used to allow removal of entries by derived classes or an overriding instance config.
```
 keyMap : {
     delegate : {
         'widgetMap.foo' : true,
         'widgetMap.bar' : true,
         tbar            : true
     }
 }
```
Has a corresponding runtime keyMap property.
role : String

ADVANCED
Field

The ARIA role to apply to this widget's element. By default, this is set to 'presentation' to avoid accidentally applying a role which may interfere with screen readers.

Bryntum widgets usually set their own appropriate default role, so it is not usually necessary to set this config directly.

However, when creating custom widgets, or when a widget does not set an appropriate default role, this config should be set to the appropriate ARIA role for the widget.
cls : String/Object
Field
Custom CSS classes to add to element. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:
```
 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }
```
Has a corresponding runtime cls property.
color : Color
Field
Applies the specified color to the widget, by setting the --b-primary CSS variable in the widgets style block.

If the supplied color starts with b-, a named color from the current theme will be used (red -> b-color-red etc.). Applied as <tag>, for example:
```
<tag>
```
When the supplied color does not start with b-, it is assumed to be a valid CSS color specification and is used as is. Applied as <tag>, for example:
```
<tag>
```
contentElementCls : String/Object

ADVANCED
Field
Custom CSS classes to add to the contentElement. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:
```
 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }
```
style : String
Field

Custom style spec to add to element

Has a corresponding runtime style property.
ui : String/Object
Field
Custom CSS class name suffixes to apply to the elements rendered by this widget. This may be specified as a space separated string, an array of strings, or as an object in which property names with truthy values are used as the class names.

For example, consider a Panel with a ui config like so:
```
 new Panel({
     text : 'OK',
     ui   : 'light'
 });
```
This will apply the CSS class 'b-panel-ui-light' to the main element of the panel as well as its many child elements. This allows simpler CSS selectors to match the child elements of this particular panel UI:
```
 .b-panel-content.b-panel-ui-light {
     background-color : #eee;
 }
```
Using the cls config would make matching the content element more complex, and in the presence of docked items and nested panels, impossible to target accurately.
containValues : Boolean/String/Function
Field
The config controls how the value of nested items are handled when a parent container gets or sets its values.

The valid values for this config are:
- null (the default) will include the values of this field's items if this field stores its own value.
- true to always include the values of this field's items.
- false to never include the values of this field's items.
- 'nested' to include the values of this field's items as a nested object under the field's name. This field's value is stored as the 'value' property of that object.
- Any other string is treated as the name of a property on this field. When truthy, the values of this field's items will be included.
- A function can be supplied that must return a value given this field as its sole argument. If that value is truthy, this field's items will be included.
Parameters
- field : Field
  
  Field instance
Returns

Boolean
container : Object<String, WidgetConfig>/WidgetConfig/FieldContainerConfig
Field
The configuration for additional items associated to this field. This is typically used to add contextual fields related to a checkbox or radio button. See these classes for examples of nested fields.

This config can be provided as an array of widget config objects, an object with named widgets (see namedItems, or a config object for the whole field container.

To determine if the object is a namedItems object or a field container config, the object is checked for either a type or an items property. If it has either of these properties, it is a field container config object. Configuring the container is useful for applying classes or styles to the container as a whole.

For example, to add named items:
```
 new Checkbox({
     text : 'Separate shipping address',
     container : {
         address1 : {
             type : 'textfield'
         },
         address2 : {
             type : 'textfield'
         }
     }
 });
```
To style the container as well, move the items to the items property and add cls:
```
 new Checkbox({
     text : 'Separate shipping address',
     container : {
         cls   : 'address-form',
         items : {
             address1 : {
                 type : 'textfield'
             },
             address2 : {
                 type : 'textfield'
             }
         }
     }
 });
```
containerDefaults : FieldContainer/FieldContainerConfig

internal
Field

The default configuration for the container.
inline : Boolean
Field

Set this config to true to always display items horizontally along with this field. This assigns an hbox as the layout to the container.

Alternatively, set this config to false to wrap this field's items below. This assigns a VBox as the layout to the container.

This config defaults to true if there is exactly one item, and false otherwise.
adopt : HTMLElement/String
Field

Element (or element id) to adopt as this Widget's encapsulating element. The widget's content will be placed inside this element.

If this widget has not been configured with an id, it will adopt the id of the element in order to preserve CSS rules which may apply to the id.
appendTo : HTMLElement/String
Field

Element (or the id of an element) to append this widget's element to. Can be configured, or set once at runtime. To access the element of a rendered widget, see element.

Has a corresponding runtime appendTo property.
dataset : Object<String, String>
Field

Object to apply to elements dataset (each key will be used as a data-attribute on the element)

Has a corresponding runtime dataset property.
element : DomConfig/String

private
Field

A createElement config object or HTML string from which to create the Widget's element.

Has a corresponding runtime element property.
id : String
Field

Widget id, if not specified one will be generated. Also used for lookups through Widget.getById

Has a corresponding runtime id property.
insertBefore : HTMLElement/String
Field

Element (or element id) to insert this widget before. If provided, appendTo config is ignored.

Has a corresponding runtime insertBefore property.
insertFirst : HTMLElement/String
Field

Element (or element id) to append this widget element to, as a first child. If provided, appendTo config is ignored.

Has a corresponding runtime insertFirst property.
title : String
Field

A title to display for the widget. Only in effect when inside a container that uses it (such as TabPanel)
catchEventHandlerExceptions : Booleanfalse

ADVANCED
Events

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed.

Set this to true to catch exceptions thrown by this object's event handlers and continue processing the event. The exception will be rethrown on a zero millisecond timeout, so it will not destroy the stack.

Has a corresponding runtime catchEventHandlerExceptions property.
internalListeners : Object

internal
Events

Internal listeners, that cannot be removed by the user.
autoSelect : Booleanfalse
Field

Specify true to auto select field contents on focus
clearable : Boolean/FieldTriggerConfigfalse
Field

Show a trigger to clear field, if this field is not readOnly. The trigger is available in the triggers object under the name clear. May also be an object which configures the cleartrigger.
editable : Booleantrue
Field

Set to false to prevent user from editing the field. For TextFields it is basically the same as setting readOnly, but for PickerFields there is a distinction where it allows you to pick a value but not to type one in the field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

On mobile devices, PickerFields are set to editable : false by default so that the user must select a value from the dropdown picker rather than having to type a value which will cause a display of the virtual keyboard.

If typing is essential to the functioning of the field, configuring the field with editable : true will override this behaviour.

Has a corresponding runtime editable property.
highlightExternalChange : Boolean
Field

Specify true to highlight field after external value changes
keyStrokeChangeDelay : Number0
Field

The delay in milliseconds to wait after the last keystroke before triggering a change event. Set to 0 to not trigger change events from keystrokes (listen for input event instead to have immediate feedback, change will still be triggered on blur).

If the field is clearable, the change event fires immediately on receiving the clear gesture.
name : String
Field

Name of the field which is used as a key to get/set values from/to the field. Used prior to ref and id in Container.values.

The config is useful when the field is used in EventEditor or TaskEditor to load/save values automatically.
placeholder : String
Field

Text to display in empty field.

Has a corresponding runtime placeholder property.
readOnly : Boolean
Field

Makes the field unmodifiable by user action. The input area is not editable, and triggers are unresponsive.

This is a wider-acting setting than editable which only sets the readOnly attribute of the <input> field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

Has a corresponding runtime readOnly property.
required : Booleanfalse
Field

Configure as true to indicate that a null field value is to be marked as invalid. This will optionally append a * to the field label if showRequiredIndicator is set.

Has a corresponding runtime required property.
revertOnEscape : Booleanfalse
Field

If this field is not readOnly, then setting this option means that pressing the Escape key after editing the field will revert the field to the value it had when the user focused the field. If the field is not changed from when focused, the clearable behaviour will be activated.
showRequiredIndicator : String
Field

true to automatically display a * after the label for this field when it is required.

Has a corresponding runtime showRequiredIndicator property.
skipValidation : Booleanfalse
Field

Set to true, completely bypasses validation logic (could be userful if your field is not editable to the user).
triggers : Object<String, FieldTriggerConfig>
Field
The triggers to add either before or after the input field. Each property name is the reference by which an instantiated Trigger Widget may be retrieved from the live triggers property.

Each trigger may have the following properties:
- cls The CSS class to apply.
- handler A method in the field to call upon click
- align (Optional) 'start' or 'end' which end of the field the trigger should go.
- weight (Optional) Higher weighted triggers gravitate towards the input field.
- key (Optional) The key name of the key to use as the activation key of this trigger.
```
const textField = new TextField({
  triggers : {
      check : {
          cls : 'fa fa-check',
          handler() {
              ...
          }
      },
      ...
  }
})
```
Has a corresponding runtime triggers property.
value : String
Field

Default value

Has a corresponding runtime value property.
align : AlignSpec/String
Field

Only valid if this Widget is floating.

How to align this element with its target when showBy is called passing a simple element as an align target.

Either a full alignment config object, or for simple cases, the edge alignment string to use.

When using a simple string, the format is '[trblc]n-[trblc]n' and it specifies our edge and the target edge plus optional offsets from 0 to 100 along the edges to align to. Also supports direction independent edges horizontally, s for start and e for end (maps to l and r for LTR, r and l for RTL).

See the showBy function for more details about using the object form.

Once set, this is stored internally in object form.
anchor : Booleanfalse
Field

Only valid if this Widget is floating and being shown through showBy.true to show a connector arrow pointing to the align target.
centered : Boolean
Field

Only valid if this Widget is floating. Set to true to centre the Widget in browser viewport space.
constrainTo : HTMLElement/Widget/Rectangledocument.body
Field

Only valid if this Widget is floating or positioned. Element, Widget or Rectangle to which this Widget is constrained.
draggable : Boolean/Objectfalse
Field
Only valid if this Widget is floating. Set to true to be able to drag a widget freely on the page. Or set to an object with a ´handleSelector´ property which controls when a drag should start.
```
draggable : {
    handleSelector : ':not(button)'
}
```
- handleSelector : String
  
  CSS selector used to determine if drag can be started from a mouse-downed element inside the widget
floating : Boolean
Field

Set to true to move the widget out of the document flow and position it absolutely in browser viewport space.
hideAnimation : Boolean/Object
Field
Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon hide, and how it should be animated eg:
```
{
   opacity: {
       to : 0,
       duration: '10s',
       delay: '0s'
   }
}
```
Set to 'false' to disable animation.
maximizeOnMobile : Number/String
Field

Only valid if this Widget is floating.

When configured as true, this widget uses isMobile to maximize itself on mobile devices.

Has a corresponding runtime maximizeOnMobile property.
positionable : 'before'/'after'/Boolean

internal
Field

This config is used to absolutely position this widget in its parent Container. When enabled, this widget will be rendered into the parent widget's primary element. In containers where the contentElement is not the same as the element (for example, Panel), the value of this config indicates if this widget should be rendered 'before' or 'after' the contentElement.

Because positionable widgets are position: absolute and may even be rendered outside of the owning container's contentElement, these widgets do not participate in the standard layout of their container.

It is not necessary to set this config explicitly when using the position configs top, right, bottom, or left, unless it needs to be set to 'after'.
positioned : Boolean
Field

Set to true when a widget is rendered into another widget's contentElement, but must not participate in the standard layout of that widget, and must be positioned relatively to that widget's contentElement.

Editors are positioned widgets.
scrollAction : 'hide'/'realign'/null
Field

Defines what to do if document is scrolled while Widget is visible (only relevant when floating is set to true). Valid values: ´null´: do nothing, ´hide´: hide the widget or ´realign´: realign to the target if possible.
showAnimation : Boolean/Object
Field
Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon show, and how it should be animated eg:
```
{
   opacity: {
       to : 1,
       duration: '10s',
       delay: '0s'
   }
}
```
Set to 'false' to disable animation.
x : Number
Field

The x position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding runtime x property.
y : Number
Field

The y position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding runtime y property.
attributes : String[]

private
Field

A list of property names to be set in the underlying input element from properties by the same name in this Field object if the value is not == null.
autoComplete : Stringoff
Field

Sets the native autocomplete property of the underlying input element. For more information, please refer to MDN
inputAlign : String
Field

Text alignment for the input field.
inputAttributes : Object<String, String>
Field

Sets custom attributes of the underlying input element. For more information, please refer to MDN
inputTag : String

ADVANCED
Field

If you need to use something else than a default input element, as the input element, provide the tag name here. Please note that this is used for advanced usage only, for example when using WebComponents (custom elements), and that the configured element must fulfil the same contract as a regular input element.
inputType : String
Field

Sets the type attribute of the underlying input element (password, hidden, date, color, etc.).
inputWidth : String/Number
Field

The width to apply to the .b-field-inner element, which encompasses the input element and any triggers. If a number is specified, px will be used.
spellCheck : Boolean
Field

Sets the native spellcheck property of the underlying input element. For more information, please refer to MDN
tabIndex : Number
Field

The tab index of the input field or fields, or null for natural tab order (recommended). Setting to 0 is equivalent to natural tab order, but is unnecessary for fields since they are naturally tabbable (i.e., accessible via the TAB key). Setting to -1 disables tabbability but allows for focus to be set to the element programmatically.

From MDN documentation:

Warning: You are recommended to only use 0 and -1 as tabindex values. Avoid using tabindex values greater than 0 and CSS properties that can change the order of focusable HTML elements (Ordering flex items). Doing so makes it difficult for people who rely on using keyboard for navigation or assistive technology to navigate and operate page content. Instead, write the document with the elements in a logical sequence.
validateOnInput : Boolean
Field

Set to false to not highlight a field as invalid while typing, to instead show it on ENTER key press or similar.
hint : String/Function
Field
An optional string to display inside the input field as an overlay. This can be useful for displaying a field's units.

This config is ignored if hintHtml is set.

For example:
```
 {
     type  : 'numberfield',
     label : 'Temperature',
     hint  : '°C'
 }
```
This config can be set to a function to dynamically generate the hint text:
```
 {
     type  : 'numberfield',
     label : 'Duration',
     hint  : ({ value }) => (value === 1) ? 'Day' : 'Days'
 }
```
The function is passed an object with the following properties:
- source A reference to the field instance.
- value The current value of the field.
A hint function will be called when the field changes value.
Parameters
- data : Object
  
  A data object
- source : Field
  
  A reference to the field instance
- value : *
  
  The current value of the field
Returns

String
hintHtml : String/Function
Field
This config is similar to hint except that this config is used to display HTML content. Since this can allow malicious content to be executed, be sure not to include user-entered data or to encode such data (see encodeHtml).

If this config is set, hint is ignored.

For example:
```
 {
     type     : 'numberfield',
     label    : 'Temperature',
     hintHtml : '<i>°C</i>'
 }
```
This config can be set to a function to dynamically generate the hintHtml text:
```
 {
     type     : 'numberfield',
     label    : 'Duration',
     hintHtml : ({ value }) => (value === 1) ? '<i>Day</i>' : '<i>Days</i>'
 }
```
The function is passed an object with the following properties:
- source A reference to the field instance.
- value The current value of the field.
A hintHtml function will be called when the field changes value.
Parameters
- data : Object
  
  A data object
- source : Field
  
  A reference to the field instance
- value : *
  
  The current value of the field
Returns

String
label : String
Labelable

Label, prepended to field

Has a corresponding runtime label property.
labelCls : String/Object
Labelable

CSS class name or class names to add to any configured label
labelPosition : 'before'/'above'/null
Labelable

Label position, either 'before' the field or 'above' the field

Leaving it out, or specifying null, lets the theme decide on label placement.
labelWidth : String/Number
Labelable

The width to apply to the <label> element. If a number is specified, px will be used.
labels : Object[]
Field
The labels to add either before or after the input field. Each label may have the following properties:
- html The label text.
- align'start' or 'end' which end of the field the label should go.
- html : String
  
  Label text
- align : 'start'/'end'
  
  Which end of the file the label should go
alignSelf : String
Field

When this widget is a child of a Container, it will by default be participating in a flexbox layout. This config allows you to set this widget's align-self style.

Has a corresponding runtime alignSelf property.
dock : 'top'/'bottom'/'left'/'right'/'start'+ 4 more
Field

Controls the placement of this widget when it is added to a panel's strips collection. Typical values for this config are 'top', 'bottom', 'left', or 'right', which cause the widget to be placed on that side of the panel's body. Such widgets are called "edge strips".

Also accepts direction neutral horizontal values 'start' and 'end'.

If this config is set to 'header', the widget is placed in the panel's header, following the title. If this config is set to 'pre-header', the widget is placed before the title. Such widgets are called "header strips".
flex : Number/String
Field

When this widget is a child of a Container, it will by default be participating in a flexbox layout. This config allows you to set this widget's flex style. This may be configured as a single number or a <flex-grow> <flex-shrink> <flex-basis> format string. numeric-only values are interpreted as the flex-grow value.

Has a corresponding runtime flex property.
height : String/Number
Field

Widget's height, used to set element style.height. Either specify a valid height string or a number, which will get 'px' appended. We recommend using CSS as the primary way to control height, but in some cases this config is convenient.

Has a corresponding runtime height property.
hidden : Booleanfalse
Field

Configure with true to make widget initially hidden.

Has a corresponding runtime hidden property.
margin : Number/String
Field

Widget's margin. This may be configured as a single number or a TRBL format string. numeric-only values are interpreted as pixels.

Has a corresponding runtime margin property.
maxHeight : String/Number
Field

The element's maxHeight. Can be either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Has a corresponding runtime maxHeight property.
maxWidth : String/Number
Field

The elements maxWidth. Can be either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Has a corresponding runtime maxWidth property.
minHeight : String/Number
Field

The element's minHeight. Can be either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Has a corresponding runtime minHeight property.
minWidth : String/Number
Field

The elements minWidth. Can be either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Has a corresponding runtime minWidth property.
overflowable : Boolean/Stringtrue

internal
Field

When set to true, this widget is considered as a whole when processing Toolbar overflow. When false, this widget's child items are considered instead.

When set to the string 'none', this widget is ignored by overflow processing. This option should be used with caution as it prevents the overflow algorithm from moving such widgets into the overflow popup which may result in not clearing enough space to avoid overflowing the toolbar.
textAlign : 'left'/'center'/'right'/'start'/'end'
Field

Text alignment: 'left', 'center' or 'right'. Also accepts direction neutral 'start' and 'end'.

Applied by adding a b-text-align-xx class to the widgets element. Blank by default, which does not add any alignment class.

To be compliant with RTL, 'left' yields same result as 'start' and 'right' as 'end'.
weight : Number
Field

A widgets weight determines its position among siblings when added to a Container. Higher weights go further down.
width : String/Number
Field

Widget's width, used to set element style.width. Either specify a valid width string or a number, which will get 'px' appended. We recommend using CSS as the primary way to control width, but in some cases this config is convenient.

Has a corresponding runtime width property.
badge : String
Badge

Initial text to show in badge.

Has a corresponding runtime badge property.

bubbleEvents : Object

Events

An object where property names with a truthy value indicate which events should bubble up the ownership hierarchy when triggered.

const container = new Container({
    items : [
       { type : 'text', bubbleEvents : { change : true }}
    ],

    listeners : {
        change() {
            // Will catch change event from the text field
        }
    }
});

callOnFunctions : Booleanfalse
Events
Set to true to call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.
```
const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});
```
Has a corresponding runtime callOnFunctions property.
dataField : String

ADVANCED
Field

When this Widget configuration is used in the Grid's RowExpander feature's widget config, provide the field on the expanded record to use for populating this widget's store (if applicable)
defaultAction : String

private
Field

Event that should be considered the default action of the widget. When that event is triggered the widget is also expected to trigger an action event. Purpose is to allow reacting to most widgets in a coherent way.
defaultBindProperty : String'html'
Field

The name of the property to set when a single value is to be applied to this Widget. Such as when used in a grid WidgetColumn, this is the property to which the column's field is applied.
disabled : Boolean/'inert'false
Field

Disable or enable the widget. It is similar to readOnly except a disabled widget cannot be focused, uses a different rendition (usually greyish) and does not allow selecting its value.

Set to 'inert' to also set the inert DOM attribute.

Has a corresponding runtime disabled property.

elementAttributes : Object<String, String | null>

Field

An object specifying attributes to assign to the root element of this widget. Set null value to attribute to remove it.

new Label({
    elementAttributes : {
       'data-role': 'primary', // Add data-role attribute with `"primary"` value
       inert : '',             // Add inert with no value
       title : null            // This will remove the title attribute from the element
    }
});

ignoreParentReadOnly : Booleanfalse
Field

Determines if the widgets read-only state should be controlled by its parent.

When set to true, setting a parent container to read-only will not affect the widget. When set to false, it will affect the widget.

localeClass : Base

ADVANCED

Localizable

A class translations of which are used for translating this entity. This is often used when translations of an item are defined on its container class. For example:

// Toolbar class that has some predefined items
class MyToolbar extends Toolbar {

    static $name = 'MyToolbar';

    static configurable = {
        // this specifies default configs for the items
        defaults : {
            // will tell items to use the toolbar locale
            localeClass : this
        },

        items : {
            // The toolbar has 2 buttons and translation for their texts will be searched in
            // the toolbar locales
            agree :{ text : 'Agree' },
            disagree :{ text : 'Disagree' }
        }
    };

   ...
}

So if one makes a locale for the MyToolbar class that will include Agree and Disagree string translations:

    ...
    MyToolbar : {
        Agree    : 'Yes, I agree',
        Disagree : 'No, I do not agree'
    }

They will be used for the toolbar buttons and the button captions will say Yes, I agree and No, I do not agree.

localizable : Booleantrue

ADVANCED
Localizable

Set to false to disable localization of this object.
localizableProperties : String[]

ADVANCED
Localizable
List of properties which values should be translated automatically upon a locale applying. In case there is a need to localize not typical value (not a String value or a field with re-defined setter/getter), you could use 'localeKey' meta configuration. Example:
```
 static configurable = {
      localizableProperties : ['width'],

      width : {
          value   : '54em', // default value here
          $config : {
              localeKey : 'L{editorWidth}' // name of the property that will be used in localization file
          }
      }
  };
```
maskDefaults : MaskConfig
Field

This config object contains the defaults for the Mask created for the masked config. Any properties specified in the masked config will override these values.
masked : Boolean/String/MaskConfig
Field

Set to true to apply the default mask to the widget. Alternatively, this can be the mask message or a Mask config object.
monitorResize : Boolean/Objectfalse

ADVANCED
Field
When this is configured as true a ResizeObserver is used to monitor this element for size changes caused by either style manipulation, or by CSS layout.

By default, notifications are queued up for delivery in the next microtask.

To receive notifications immediately, set the immediate option to true.

Size changes are announced using the resize event.
- immediate : Boolean
  
  Set to true to receive resize notifications immediately.
owner : Widget
Field

The owning Widget of this Widget. If this Widget is directly contained (that is, it is one of the items of a Container), this config will be ignored. In this case the owner is always the encapsulating Container.

If this Widget is floating, this config should be specified by the developer.

Registering with an owner creates a lifecycle relationship with that owning Widget. When the owner is destroyed this widget will also be destroyed.

This also allows focus to be tracked in the ownership tree. If a widget owns another widget, then even if that other widget is in a different element, focusing that owned widget will not cause a focusOut event, and the containsFocus property remains set.

A widget can unregister from its owner and break this relationship at any time by setting the property to null. It is then the developer's responsibility to ensure that this Widget is destroyed.

Has a corresponding runtime owner property.
preventTooltipOnTouch : Booleanfalse
Field

Prevent tooltip from being displayed on touch devices. Useful for example for buttons that display a menu on click etc, since the tooltip would be displayed at the same time.
ref : String
Field

An identifier by which this widget will be registered in the widgetMap of all ancestor containers.

If omitted, this widget will be registered using its id. In most cases ref is preferable over id since id is required to be globally unique while ref is not.

The ref value is also added to the elements dataset, to allow targeting it using CSS etc.

Has a corresponding runtime ref property.
ripple : Boolean/Object
Field
Configure as true to have the component display a translucent ripple when its focusElement, or element is tapped if the current theme supports ripples. Out of the box, only the Material theme supports ripples.

This may also be a config object containing the properties listed below.

E.g.
```
   columns  : [{}...],
   ripple   : {
       color : 'red',
       clip  : '.b-grid-row'
   },
   ...
```
- delegate : String
  
  A CSS selector to filter which child elements trigger ripples. By default, the ripple is clipped to the triggering element.
- color : String'#000'
  
  A CSS color name or specification.
- radius : Number100
  
  The ending radius of the ripple. Note that it will be clipped by the target element by default.
- clip : String
  
  A string which describes how to clip the ripple if it is not to be clipped to the default element. Either the property of the widget to use as the clipping element, or a selector to allow clipping to the closest matching ancestor to the target element.
rootElement : ShadowRoot/HTMLElement
Field

If you are rendering this widget to a shadow root inside a web component, set this config to the shadowRoot. If not inside a web component, set it to document.body
showTooltipWhenDisabled : Booleantrue
Field

Set to false to not show the tooltip when this widget is disabled

tab : Boolean/TabConfig

Field

A configuration for the tab created for this widget when it is placed in a TabPanel. For example, this config can be used to control the icon of the tab for this widget:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             icon : 'fa fa-wrench'
         }
     },
     ...
 }

Another use for this config is to set the tab's rotate value differently than the default managed by the TabPanel:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             rotate : false   // don't rotate even if tabBar is docked left or right
         }
     },
     ...
 }

Set this to false to prevent the creation of a tab for this widget. In this case, this widget must be shown explicitly. The activeTab for the tab panel will be -1 in this situation.

 items : {
     panel : {
         type : 'panel',
         tab  : false,    // no tab for this item

         // other configs...
     },
     ...
 ]

Has a corresponding runtime tab property.

tooltip : String/TooltipConfig/null
Field

Tooltip for the widget, either as a string or as a Tooltip config object.

By default, the Widget will use a single, shared instance to display its tooltip as configured, reconfiguring it to the specification before showing it. Therefore, it may not be permanently mutated by doing things such as adding fixed event listeners.

To have this Widget own its own Tooltip instance, add the property newInstance : true to the configuration. In this case, the tooltip's owner will be this Widget.

Note that in the absence of a configured ariaDescription, the tooltip's value will be used to populate an aria-describedBy element within this Widget.
rtl : Booleanfalse
RTL

This may be configured as true to make the widget's element use the direction:rtl style.

All descendant widgets, including any floating widgets will inherit this setting.

Has a corresponding runtime rtl property.
scrollerClass : Scroller

internal
Field

The class to instantiate to use as the scrollable. Defaults to Scroller.
bottom : Number/String

internal
Field

The bottom CSS absolute position for this widget. If specified, the widget is implicitly configured as positionable.
collapsify : Boolean/'hide'/'overlay'

internal
Field
Determines how a collapsed panel will treat this widget if it resides within the panel's header (for example, as one of its strips or tools).

Valid options are:
- null : The widget will be moved to the overlay header when the panel is collapsed (the default).
- false : The widget will be unaffected when the panel is collapsed and will remain in the primary panel header at all times.
- 'hide' : The widget will be hidden when the panel is collapsed.
- 'overlay' : The widget will only appear in the collapsed panel's overlay header. See collapsible type='overlay'.
column : Number
Field

Programmatic control over which column to start in when used in a grid layout.

Has a corresponding runtime column property.
defaultCls : String/Object/String[]

internal
Field
Custom CSS classes to add to this widget's element. This property is typically used internally to assign default CSS classes while allowing cls to alter these defaults. It is not recommended that client code set this config but instead should set cls.

For example, to remove a class defined by defaultCls using cls, declare the class name as a key with a falsy value:
```
 cls : {
     'default-class' : false
 }
```
detectCSSCompatibilityIssues : Boolean
Field
Check for CSS compatibility and inclusion related issues and try to auto fix them. Performs the following checks:
- Detects usage of .b-fa class for icons. Since v7, FontAwesome is no longer built-in, the standard .fa class should be used instead.
- Detects missing FontAwesome font. With FontAwesome no longer built-in, this must be included separately by the app. If it is not included, it tries to autoload it from CDN.
- Checks for presence of a Bryntum CSS. Theme and structural CSS was separated in v7, both structural CSS and a theme must be included. If they are not, it tries to autoload them from CDN.
Defaults to true in Grid, Scheduler, Scheduler Pro, Gantt, Calendar and TaskBoard.

We recommend disabling this check when you have CSS imports properly set up in your app
hideMode : 'clip'/'display'/'opacity''display'

internal
Field
Determines how a widget will prevent itself from being seen when hidden is set to true or the hide method is called.

The allowed values are as follows:
- 'display' (the default) to hide the widget using display: none style
- 'clip' to hide the widget using CSS clip style (only valid if position: absolute)
- 'opacity' to hide the widget using opacity : 0 style (and pointer-events : none)
Has a corresponding runtime hideMode property.
left : Number/String

internal
Field

The inset-inline-start CSS absolute position for this widget. If specified, the widget is implicitly configured as positionable.
recomposeAsync : Booleantrue

internal
Field

Set this config to false to disable batching DOM updates on animation frames for this widget. This has the effect of synchronously updating the DOM when configs affecting the rendered DOM are modified. Depending on the situation, this could simplify code while increasing time spent updating the DOM.
right : Number/String

internal
Field

The inset-inline-end CSS absolute position for this widget. If specified, the widget is implicitly configured as positionable.
span : Number
Field

Programmatic control over how many columns to span when used in a grid layout.

Has a corresponding runtime span property.
top : Number/String

internal
Field

The top CSS absolute position for this widget. If specified, the widget is implicitly configured as positionable.
twinForwardEvents : String/String[]/Object

internal
Field
The events to forward from an overflow twin to its origin widget.

May be specified as a space separated string, or as an object in which property names with truthy values are used as the event names:
```
 twinForwardEvents : {
     change : true,
     input  : 1
 }
```
NOTE: This config cannot be dynamically changed after the overflowTwin has been created (see ensureOverflowTwin.
twinSyncConfigs : String/String[]/Object

internal
Field
A mapping object describing config properties to sync with the overflowTwin. This is pass to bindConfigs.

For example:
```
 twinSyncConfigs : {
     disabled : true,
     value    : 'checked'   // sync twin's checked config to this object's value config
 }
```
NOTE: This config cannot be dynamically changed after the overflowTwin has been created (see ensureOverflowTwin.

Properties

Properties are getters/setters or publicly accessible variables on this class

isBadge : Booleantrue

READONLY

static

ADVANCED
Badge

Identifies an object as an instance of Badge class, or subclass thereof.
isDelayable : Booleantrue

READONLY

static

ADVANCED
Delayable

Identifies an object as an instance of Delayable class, or subclass thereof.
isEvents : Booleantrue

READONLY

static

ADVANCED
Events

Identifies an object as an instance of Events class, or subclass thereof.
isFileField : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of FileField class, or subclass thereof.
isKeyMap : Booleantrue

READONLY

static

ADVANCED
KeyMap

Identifies an object as an instance of KeyMap class, or subclass thereof.
isLabelable : Booleantrue

READONLY

static

ADVANCED
Labelable

Identifies an object as an instance of Labelable class, or subclass thereof.
isLocalizable : Booleantrue

READONLY

static

ADVANCED
Localizable

Identifies an object as an instance of Localizable class, or subclass thereof.
isRTL : Booleantrue

READONLY

static

ADVANCED
RTL

Identifies an object as an instance of RTL class, or subclass thereof.
isValidatable : Booleantrue

READONLY

static

ADVANCED
Validatable

Identifies an object as an instance of Validatable class, or subclass thereof.
configurable : Object

internal

static
Field
A class property getter for the configuration properties of the class, which can be overridden by configurations passed at construction time.

Unlike a normal static property, this property is only ever used for the class that defines it (as in, hasOwnProperty). It is retrieved for all classes in a class hierarchy, to gather their configs individually and then combine them with those of derived classes.

For example, a Label might declare a text config like so:
```
 class Label extends Base {
     static configurable = {
         text : null
     };
 }
```
The text config is automatically inherited by classes derived from Label. By implementing get configurable(), derived classes can change the default value of inherited configs, or define new configs, or both.

When a config property is declared in this way, the class author can also implement either of two special methods that will be called when the config property is assigned a new value:
- changeText()
- updateText()
In the example above, the Label class could implement a changeText() method, an updateText() method, or both. The generated property setter ensures these methods will be called when the text property is assigned.

The generated setter (for text in this example) performs the following steps:
- If the class defines a changeText() method, call it passing the new value and the current value: changeText(newText, oldText).
  Then:
  - If changeText() exits without returning a value (i.e., undefined), exit and do nothing further. The assumption is that the changer method has done all that is required.
  - Otherwise, the return value of changeText() replaces the incoming value passed to the setter.
- If the new value (or the value returned by changeText()) is !== to the current value:
  - Update the stored config value in this._text.
  - If the class defines an updateText() method, call it passing the new value and the previous value. updateText(newText, oldText)
Resolving a value from an owner

By specifying a value starting with 'up.' for a config, the config system will resolve that value by examining the ownership hierarchy. It will walk up the hierarchy looking for a property matching the name (or dot separated path) after 'up.'. If one is found, the value will be read and used as the initial value.
```
class Parent extends Base {
    static get configurable() {
        return [
          'importantValue'
        ]
    }
}

class Child extends Base {
    static get configurable() {
        return [
          'value'
        ]
    }
}

const parent = new Parent({
    importantValue : 123
});

const child = new Child({
    owner : parent,
    // Will be resolved from the owner
    value : 'up.importantValue'
});

console.log(child.value); // logs 123
```
Please note that this is for now a one way one time binding, the value will only be read initially and not kept up to date on later changes.

Value Merging

When a config property value is an object, the value declared by the base class is merged with values declared by derived classes and the value passed to the constructor.
```
 class Example extends Base {
     static configurable = {
         config : {
             foo : 1,
             bar : 2
         }
     };
 }

 class Example2 extends Example {
     static configurable = {
         config : {
             bar : 42,
             zip : 'abc'
         }
     };
 }

 let ex = new Example2({
     config : {
         zip : 'xyz'
     }
 });
```
The result of the merge would set config to:
```
 ex.foo = {
     foo : 1,    // from Example
     bar : 42,   // from Example2
     zip : 'xyz' // from constructor
 }
```
Config Options

Some config properties require additional options such as declarative information about the config that may be useful to automate some operation. Consider a Button. It could declare that its text config affects the rendered HTML by applying a render property to the config definition. Its base class could then examine the config definition to find this property.

To support this, config options ca be declared like so:
```
 class Button extends Widget {
     static configurable = {
         text : {
             value   : null,
             $config : {
                 render : true
             }
         }
     };
 }
```
The $config property can alternatively be just the names of the options that should be enabled (set to true).

For example, the following is equivalent to the above:
```
 class Button extends Widget {
     static configurable = {
         text : {
             value   : null,
             $config : 'render'
         }
     };
```
Default Value

It is common to set a config to a null value to take advantage of internal optimizations for null values. In most cases the fact that this produces undefined as the actual initial value of the config is acceptable. When this is not acceptable, a config can be declared like so:
```
 class Widget {
     static configurable = {
         disabled : {
             $config : null,
             value   : null,
             default : false
         }
     };
```
The default property above determines the value of the config while still gaining the benefits of minimal processing due to the null value of the value property.
declarable : String[]

internal

static
Field
A class property getter to add additional, special class properties.

For example, a class adds a declarable class property like so:
```
 class Something extends Base {
     static get declarable() {
         return ['extra'];
     }

     static setupExtra(cls, meta) {
         // use cls.extra
     }
 }
```
A derived class can then specify this property like so:
```
 class Derived extends Something {
     static get extra() {
         // return extra information
     }
 }
```
When the Derived class is initialized, the setupExtra() method is called and Derived is passed as the argument. It is also the this pointer, but the parameter is minifiable. The second argument passed is the $meta object for the class.

Classes are initialized at the first occurrence of the following:
- An instance is created
- The class $meta property is accessed
defaultConfig : Object

internal

static
Field
A legacy class property getter for the default configuration of the class, which can be overridden by configurations passed at construction time. We recommend using configurable instead.

Unlike a normal static property, this property is only ever used for the class that defines it (as in, hasOwnProperty). It is retrieved for all classes in a class hierarchy, to gather their configs individually and then combine them with those of derived classes.

For example, a Store might declare its url config like so:
```
 class Store extends Base {
     static get defaultConfig() {
         return {
             url : null
         };
     }
 }
```
The url config is automatically inherited by classes derived from Store. By implementing get defaultConfig(), derived classes can change the default value of inherited configs, or define new configs, or both. When defining new configs, however, configurable is preferred.

Config properties introduced to a class by this declaration do not participate in value merging and do not get a generated setter. Config properties introduced by a base class using configurable can be set to a different value using defaultConfig and in doing so, the values will be merged as appropriate for configurable.
properties : Object

internal

static
Field

A class property getter for the default values of internal properties for this class.

renderConfigs : Object/String[]

internal

static

Field

This property declares the set of config properties that affect a Widget's rendering, i.e., the configs used by the compose method.

For example:

 class Button extends Widget {
     static renderConfigs = [ 'cls', 'iconCls', 'text' ];
 }

Alternatively this can be an object:

 class Button extends Widget {
     static renderConfigs = {
         cls     : true,
         iconCls : true,
         text    : true
     };
 }

delayable : Object.

internal

static
Delayable
This class property returns an object that specifies methods to wrap with configurable timer behaviors.

It is used like so:
```
 class Foo extends Base.mixin(Delayable) {
     static get delayable() {
         return {
             expensiveMethod : 500
         };
     }

     expensiveMethod() {
         this.things();
         this.moreThings();
         this.evenMoreThings();
     }
 }
```
With the above in place, consider:
```
 let instance = new Foo();

 instance.expensiveMethod();
```
Instead of the above code immediately calling the expensiveMethod(), it will start a timer that will invoke the method 500ms later. Because expensiveMethod() is an instance method, each instance of Foo will have its own timer.

NOTE: Only instance methods are currently supported (i.e., only non-static methods).

Options

The value of each key configures how the method will be scheduled. If the value is a number, it is promoted to a config object of type='buffer' as in the following:
```
 class Foo extends Base.mixin(Delayable) {
     static get delayable() {
         return {
             expensiveMethod : {
                 type  : 'buffer',
                 delay : 500
             }
         };
     }
 }
```
The type property of the config object must be one of three values. Other options can be provided depending on the type:
- buffer
  Other options:
  - delay (Number) : The number of milliseconds to wait before calling the underlying method. A value of 0 is equivalent to setting immediate: true.
  - immediate (Boolean) : Set to true to call immediately (effectively disabling the buffer).
- raf (short for "request animation frame")
- idle (short for "request idle callback") Not available on Safari
  Other options:
  - cancelOutstanding (Boolean) : Set to true to cancel any pending animation frame requests and schedule a new one on each call.
  - immediate (Boolean) : Set to true to call immediately.
- throttle
  Other options:
  - delay (Number) : The number of milliseconds to wait after each execution before another execution takes place. A value of 0 is equivalent to setting immediate: true.
  - immediate (Boolean) : Set to true to call immediately (effectively disabling the throttle).
While immediate: true can be specified at the class level, it is more typical to set it on the instance's method as described below.

Delayable Method API

Delayable methods have a consistent API to manage their scheduling. This API is added to the methods themselves.

For example:
```
 let instance = new Foo();

 instance.expensiveMethod();         // schedule a call in 500ms
 instance.expensiveMethod.isPending; // true
 instance.expensiveMethod.cancel();
 instance.expensiveMethod.flush();
 instance.expensiveMethod.now();

 instance.expensiveMethod.delay = 10;
 instance.expensiveMethod();         // schedule a call in 10ms
```
isPending (Boolean, readonly)

This boolean property will be true if a call has been scheduled, and false otherwise.

cancel()

Cancels a pending call if one has been scheduled. Otherwise this method does nothing.

flush()

Cancels the timer and causes the pending call to execute immediately. If there is no pending call, this method does nothing.

now()

Cancels the timer (if one is pending) and executes the method immediately. If there is no pending call, this method will still call the underlying method.
$meta : Object

internal

READONLY

static
Field
An object owned by this class that does not share properties with its super class. This object may contain other properties which are added as needed and are not documented here.
- class : Function
  
  The class constructor that owns the meta object
- super : Object
  
  The $meta object for the super class. This is null for Base
- config : Object
  
  The object holding the default configuration values for this class
- configs : Object
  
  An object keyed by config name that holds the defined configs for the class The value of each property is a Config instance
- forkConfigs : Boolean
  
  This will be true if the default configuration values for this class (in the config property of the meta object) must be forked to avoid object sharing, or if the object can be passed to Object.create() for efficiency
- hierarchy : Function[]
  
  The array of classes in the ancestry of this class. This will start with Base at index 0 and ends with this class
- properties : Function[]
  
  The array of classes that define a "static get properties()" getter
$name : String

static

ADVANCED
Field
Class name getter. Used when original ES6 class name is minified or mangled during production build. Should be overridden in each class which extends Widget or it descendants.
```
class MyNewClass extends Widget {
    static $name = 'MyNewClass';
}
```
all : Widget[]

internal

READONLY

static
Field

Returns an array containing all existing Widgets. The returned array is generated by this call and is not an internal structure.
convertPinchToMousewheel : Boolean

static
Field
By default, on touch devices, a two finger pinch gesture where both touch points are within a Bryntum widget is converted to a CTRL/wheel event injected at the mid-point between the two initial touches.

This is so that Scheduler and Calendar views which are configured to zoomOnMouseWheel will zoom on pinch on touch devices.

That disables the platform's native pinch-zooming. Set this static flag to false to disable the conversion:
```
    Widget.convertPinchToMousewheel = false;
```
focusVisible : Boolean

internal

READONLY

static
Field

This property yields true if the currently focused element has been reached through other means than mouse click. If the activeElement matches :focus-visible.
recomposeAsync : Boolean

internal

static
Field

Get/set the recomposeAsync config for all widgets. Setting this value will set the config for all existing widgets and will be the default value for newly created widgets. Set this value to null to disable the default setting for new widgets while leaving existing widgets unaffected.

Has a corresponding recomposeAsync config.
tooltip : Tooltip

READONLY

static
Field

The shared Tooltip instance which handles tooltips which are not configured with newInstance : true.

Has a corresponding tooltip config.

type : String

static

Field

Widget name alias which you can use in the items of a Container widget.

class MyWidget extends Widget {
    static get type() {
       return 'mywidget';
    }
}

const panel = new Panel({
   title : 'Cool widgets',
   items : {
      customWidget : { type : 'mywidget', html : 'Lorem ipsum dolor sit amet...' }
   }
});

files : FileList

READONLY

Returns list of selected files
keyMap : Object<String, KeyMapConfig>
KeyMap
An object whose keys are the key name and optional modifier prefixes: 'Ctrl+', 'Alt+', 'Meta+', and 'Shift+' (case-insensitive). The values are the name of the instance method to call when the keystroke is received.

For example:
```
 keyMap : {
     'Ctrl+A': 'onSelectAll',
     'Ctrl+Z': 'onUndo',
     't'     : 'gotoNow',
     [/\d/]  : 'onDigit'
 }
```
If a key is a visible character (as above), and not modified by any modifier keys, and emanates from an editable element (such as an <input> or <textarea>), the keystroke is ignored. This is to allow the browser to handle typing in editable elements.

Target element filtering

By default, the keyMap will process keystrokes from any element within the widget.

This can be filtered by providing a targetSelector property in the keyMap. If provided, only keystrokes originating from elements matching the targetSelector (or their descendants) will be processed by the keyMap.

For example:
```
// Only accept keys from elements with class 'my-class' or their descendants.
keyMap : {
   targetSelector : '.my-class',
  'Enter'         : 'actionToPerformOnEnter'
}
```
This can be done on a more granular level for each keyMap entry by providing a targetSelector property in the action config object:
```
keyMap : {
    'Enter' : {
        handler        : 'actionToPerformOnEnter',
        targetSelector : '.my-class'
    }
}
```
Delegation

In addition to key names, the special key 'delegate' can be included to specify additional objects that have their own keyMap. If a keystroke is not handled by this keyMap, the delegates are processed until one has a matching entry in its keyMap. The value of the delegate key can be a single string, an array of strings or an object whose truthy keys are dot paths identifying the delegate(s) related to this instance.

For example:
```
 keyMap : {
     delegate : ['widgetMap.foo', 'widgetMap.bar', 'tbar']
 }
```
An widget with the above keyMap will delegate to the child widgets named foo and bar via the widget's widgetMap. In addition, the tbar property of the widget will also be considered as a delegate.

The following is equivalent to the above delegate but using an object. This form can be used to allow removal of entries by derived classes or an overriding instance config.
```
 keyMap : {
     delegate : {
         'widgetMap.foo' : true,
         'widgetMap.bar' : true,
         tbar            : true
     }
 }
```
Has a corresponding keyMap config.
emptyArray : Array

internal

READONLY
Field

An empty array that can be used as a default value.
emptyObject : Object

internal

READONLY
Field

An empty object that can be used as a default value.
cls : String/Object
Field
Custom CSS classes to add to element. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:
```
 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }
```
Has a corresponding cls config.
isField : Booleantrue

READONLY

ADVANCED
Field

Identifies an object as an instance of Field class, or subclass thereof.
isFileField : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of FileField class, or subclass thereof.
isWidget : Booleantrue

READONLY

ADVANCED
Field

Identifies an object as an instance of Widget class, or subclass thereof.
The : String[]

internal

READONLY
Field

Used by the Widget class internally to create CSS classes based on this Widget's inheritance chain to allow styling from each level to apply.

For example Combo would yield "["b-widget", "b-field", "b-text-field", "b-picker-field", "b-combo"]"

May be implemented in subclasses to add or remove classes from the super.widgetClassList
appendTo : HTMLElement/String
Field

Element (or the id of an element) to append this widget's element to. Can be configured, or set once at runtime. To access the element of a rendered widget, see element.

Has a corresponding appendTo config.
content : String

ADVANCED
Field

Set HTML content safely, without disturbing sibling elements which may have been added to the contentElement by plugins and features. When specifying html, this widget's element will also have the htmlCls added to its classList, to allow targeted styling.
contentElement : HTMLElement

READONLY

ADVANCED
Field

The child element into which content should be placed. This means where html should be put, or, for Containers, where child items should be rendered.
dataset : Object
Field

Get widgets elements dataset or assign to it

Has a corresponding dataset config.
element : HTMLElement

READONLY
Field

Get this widget's encapsulating HTMLElement, which is created along with the widget but added to DOM at render time.

Has a corresponding element config.
focusElement : HTMLElement

READONLY

ADVANCED
Field

Get this widget's primary focus holding element if this widget is itself focusable, or contains focusable widgets.
focusability : Focusability

internal

READONLY
Field

Returns an object describing the focus and keyboard navigation aspects of this widget's focusElement.
focusableElement : HTMLElement

READONLY

ADVANCED
Field

Returns this widget's focusElement if that element can currently be given focus (e.g., this widget is not disabled, or hidden).
hasPainted : Boolean

internal

READONLY
Field

This property is set to true after processing the initial paint for the widget. It remains false during the initial paint. The intended use for this flag is to avoid processing that will be handled by the first paint (similar to not firing events during the widget's initial configuration). If this field is true, the initial paint has already taken place, otherwise, it has yet to run. This field differs from isPainted which checks that the widget's element is attached to the DOM.
html : String/Function/DomConfig/DomConfig[]/VueConfig+ 1 more
Field

The HTML to display initially or a function returning the markup (called at widget construction time).

This may be specified as the name of a function which can be resolved in the component ownership hierarchy, such as 'up.getHTML' which will be found on an ancestor Widget.
id : String
Field

Get/set widgets id

Has a corresponding id config.
insertBefore : HTMLElement/String
Field

Element (or element id) to insert this widget before. If provided, appendTo config is ignored.

Has a corresponding insertBefore config.
insertFirst : HTMLElement/String
Field

Element (or element id) to append this widget element to, as a first child. If provided, appendTo config is ignored.

Has a corresponding insertFirst config.
overflowElement : HTMLElement

READONLY

ADVANCED
Field

The child element which scrolls if any. This means the element used by the scrollable.
staticClassList : DomClassList

internal

READONLY
Field

Returns the DomClassList for this widget's class. This object should not be mutated.
style : CSSStyleDeclaration/String/Object
Field

Get/set widgets elements style. The setter accepts a cssText string or a style config object, the getter always returns a CSSStyleDeclaration

Has a corresponding style config.

uiClassList : DomClassList

internal

READONLY

Field

Returns the cross-product of the classes staticClassList with each ui as a DomClassList instance.

For example, a Combo with a ui: 'foo bar' would produce:

     new DomClassList({
         'b-field-ui-foo'       : 1,
         'b-text-field-ui-foo'   : 1,
         'b-picker-field-ui-foo' : 1,
         'b-combo-ui-foo'       : 1,

         'b-field-ui-bar'       : 1,
         'b-text-field-ui-bar'   : 1,
         'b-picker-field-ui-bar' : 1,
         'b-combo-ui-bar'       : 1
     });

A Panel with a ui: 'foo bar' would produce:

     new DomClassList({
         'b-panel-ui-foo' : 1,
         'b-panel-ui-bar' : 1
     });

uiClasses : String[]

internal

READONLY

Field

Returns the cross-product of the classes staticClassList with each ui as an array of strings.

For example, a Combo with a ui: 'foo bar' would produce:

 [
     'b-widget-foo', 'b-field-foo', 'b-text-field-foo', 'b-picker-field-foo', 'b-combo-foo',
     'b-widget-bar', 'b-field-bar', 'b-text-field-bar', 'b-picker-field-bar', 'b-combo-bar'
 ]

catchEventHandlerExceptions : Booleanfalse

ADVANCED
Events

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed.

Set this to true to catch exceptions thrown by this object's event handlers and continue processing the event. The exception will be rethrown on a zero millisecond timeout, so it will not destroy the stack.

Has a corresponding catchEventHandlerExceptions config.
editable : Booleantrue
Field

Set to false to prevent user from editing the field. For TextFields it is basically the same as setting readOnly, but for PickerFields there is a distinction where it allows you to pick a value but not to type one in the field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

On mobile devices, PickerFields are set to editable : false by default so that the user must select a value from the dropdown picker rather than having to type a value which will cause a display of the virtual keyboard.

If typing is essential to the functioning of the field, configuring the field with editable : true will override this behaviour.

Has a corresponding editable config.
input : HTMLElement
Field

The input element at the heart if this field
inputValue : String

internal

READONLY
Field

A String representation of the value of this field for syncInputFieldValue to use as the input element's value.

Subclasses may override this to create string representations.

For example, DateField's implementation will format the field date value according to its configured format. And Combo's implementation will return the displayField of the selected record.
isEmpty : Boolean

READONLY
Field

Returns true if this field is empty. That is, if it would violate the required setting.

This may have different definitions in subclasses from simple text fields.
isEmptyInput : Boolean

READONLY
Field

Returns true if the field's input is empty
isValid : Boolean

READONLY
Field

Returns true if the field value is valid
needsInputSync : Boolean

private

READONLY
Field

Returns true if the input field needs to be synced with the internal value of this field.

May be overridden in subclasses where this is more complex such as multiSelect Combo with a ChipView where the input area does not reflect the field's value.
placeholder : String
Field

Text to display in empty field.

Has a corresponding placeholder config.
readOnly : Boolean
Field

Makes the field unmodifiable by user action. The input area is not editable, and triggers are unresponsive.

This is a wider-acting setting than editable which only sets the readOnly attribute of the <input> field.

PickerFields such as Combo and DateField can be editable : false, but still modifiable through the UI.

Has a corresponding readOnly config.
required : Booleanfalse
Field

Configure as true to indicate that a null field value is to be marked as invalid. This will optionally append a * to the field label if showRequiredIndicator is set.

Has a corresponding required config.
showRequiredIndicator : String
Field

true to automatically display a * after the label for this field when it is required.

Has a corresponding showRequiredIndicator config.
triggers : Object<String, FieldTriggerConfig>
Field
The triggers to add either before or after the input field. Each property name is the reference by which an instantiated Trigger Widget may be retrieved from the live triggers property.

Each trigger may have the following properties:
- cls The CSS class to apply.
- handler A method in the field to call upon click
- align (Optional) 'start' or 'end' which end of the field the trigger should go.
- weight (Optional) Higher weighted triggers gravitate towards the input field.
- key (Optional) The key name of the key to use as the activation key of this trigger.
```
const textField = new TextField({
  triggers : {
      check : {
          cls : 'fa fa-check',
          handler() {
              ...
          }
      },
      ...
  }
})
```
Has a corresponding triggers config.
validity : ValidityState

private

READONLY
Field

Returns the DOM ValidityState for this widget's input element, or null if there isn't one.
value : *
Field

Gets or sets the value. The returned type will depend upon the Field subclass.

TextField returns a String.

NumberField returns a Number.

DateField and TimeField return a Date object, and null if the field is empty.

Combo will return a String if configured with items as a simple string array. Otherwise it will return the valueField value from the selected record, or null if no selection has been made.

Has a corresponding value config.
anchorSize : Number[]

READONLY
Field

Returns an [x, y] array containing the width and height of the anchor arrow used when aligning this Widget to another Widget or element.

The height is the height of the arrow when pointing upwards, the width is the width of the baseline.
maximizeOnMobile : Number/String
Field

Only valid if this Widget is floating.

When configured as true, this widget uses isMobile to maximize itself on mobile devices.

Has a corresponding maximizeOnMobile config.
x : Number
Field

Moves this Widget to the desired x position.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding x config.
y : Number
Field

Moves this Widget to the desired y position.

Only valid if this Widget is floating and not aligned or anchored to an element.

Has a corresponding y config.
keyMapElement : HTMLElement

private

READONLY
KeyMap

Override to attach the keyMap keydown event listener to something else than this.element
keyMapSubComponents : Object

private

READONLY
KeyMap

Override to make keyMap resolve subcomponent actions to something else than this.features.
alignSelf : String
Field

Get/set this widget's align-self flexbox setting. This may be set to modify how this widget is aligned within the cross axis of a flexbox layout container.

Has a corresponding alignSelf config.
flex : Number/String
Field
Get element's flex property. This may be configured as a single number or a format string:
```
 <flex-grow> <flex-shrink> <flex-basis>
```
Numeric-only values are interpreted as the flex-grow value.

Has a corresponding flex config.
height : Number/String
Field

Get element's offsetHeight or sets its style.height, or specified height if element no created yet.

Has a corresponding height config.
margin : Number/String
Field

Get element's margin property. This may be configured as a single number or a TRBL format string. numeric-only values are interpreted as pixels.

Has a corresponding margin config.
maxHeight : String/Number
Field

Get/set element's maxHeight. Getter returns max-height from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Has a corresponding maxHeight config.
maxWidth : String/Number
Field

Get/set elements maxWidth. Getter returns max-width from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Has a corresponding maxWidth config.
minHeight : String/Number
Field

Get/set element's minHeight. Getter returns min-height from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Has a corresponding minHeight config.
minWidth : String/Number
Field

Get/set elements minWidth. Getter returns min-width from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Has a corresponding minWidth config.
scrollable : Scroller
Field

Accessor to the Scroller which can be used to both set and read scroll information.
width : Number/String
Field

Get elements offsetWidth or sets its style.width, or specified width if element not created yet.

Has a corresponding width config.
config : Object

READONLY

ADVANCED
Field

Returns a copy of the full configuration which was used to configure this object.
isConstructing : Boolean

READONLY

ADVANCED
Field

This property is set to true before the constructor returns.
isDestroyed : Boolean

READONLY
Field

This property is set to true by destroy after destruction.

It is also one of the few properties that remains on the object after returning from destroy(). This property is often checked in code paths that may encounter a destroyed object (like some event handlers) or in the destruction path during cleanup.
isDestroying : Boolean

READONLY

ADVANCED
Field

This property is set to true on entry to the destroy method. It remains on the objects after returning from destroy(). If isDestroyed is true, this property will also be true, so there is no need to test for both (for example, comp.isDestroying || comp.isDestroyed).
assignedId : String

private

READONLY
Field

Get id assigned by user (not generated id)
badge : String
Badge

Get/sets and display badge, set to null or empty string to hide.

Has a corresponding badge config.
callOnFunctions : Booleanfalse
Events
Set to true to call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.
```
const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});
```
Has a corresponding callOnFunctions config.

cellInfo : CellWidgetContext

READONLY

Field

An object providing the record and column for a widget embedded inside a WidgetColumn

columns : [
   {
       type   : 'widget',
       widgets: [{
           type     : 'button',
           icon     : 'fa fa-trash',
           onAction : ({ source : btn }) => btn.cellInfo.record.remove()
       }]
   }
]

disabled : Boolean/'inert'
Field

Get/set element's disabled state. Set to 'inert' to also set the inert DOM attribute.

Has a corresponding disabled config.
errorTip : Tooltip

READONLY
Validatable

A singleton error tooltip which activates on hover of invalid fields. before show, it gets a reference to the field and interrogates its active error list to display as the tip content.
hasGeneratedId : Boolean

private
Field

true if no id was set, will use generated id instead (widget1, ...). Toggle automatically on creation
innerItem : Boolean

internal
Field

This readonly property is true for normal widgets in the items of a container. It is false for special widgets such as a tbar.
label : String
Labelable

Get/set fields label. Please note that the Field needs to have a label specified from start for this to work, otherwise no element is created.

Has a corresponding label config.
localeHelper : LocaleHelper

READONLY

ADVANCED
Localizable

Get the global LocaleHelper
localeManager : LocaleManager

READONLY

ADVANCED
Localizable

Get the global LocaleManager
ref : String

READONLY
Field

An identifier by which this widget will be registered in the widgetMap of all ancestor containers.

If omitted, this widget will be registered using its id. In most cases ref is preferable over id since id is required to be globally unique while ref is not.

The ref value is also added to the elements dataset, to allow targeting it using CSS etc.

Has a corresponding ref config.
tab : Tab

READONLY
Field

The tab created for this widget when it is placed in a TabPanel.

Has a corresponding tab config.
rtl : Boolean
RTL

If a widget is rendered into an element which has computed style direction:rtl, this property will be set to true

Rendering a widget into an element which, either by a CSS rule, or by its inline style has an explicit direction will cause the widget to use that direction regardless of the owning document's direction.

In this way, an RTL widget may operate normally inside an LTR page and vice versa.

Has a corresponding rtl config.
hidden : Boolean
Field

Get/set the widget hidden state.

Note: hidden : false does not mean that this widget is definitely visible. To ascertain visibility, use the isVisible property.

Has a corresponding hidden config.
isVisible : Boolean

READONLY
Field

Determines visibility by checking if the Widget is hidden, or any ancestor is hidden and that it has an element which is visible in the DOM
column : Number
Field

Programmatic control over which column to start in when used in a grid layout.

Has a corresponding column config.
hideMode : 'clip'/'display'/'opacity''display'

internal
Field
Determines how a widget will prevent itself from being seen when hidden is set to true or the hide method is called.

The allowed values are as follows:
- 'display' (the default) to hide the widget using display: none style
- 'clip' to hide the widget using CSS clip style (only valid if position: absolute)
- 'opacity' to hide the widget using opacity : 0 style (and pointer-events : none)
Has a corresponding hideMode config.
isComposable : Boolean

internal

READONLY
Field

Returns true if this class uses compose() to render itself.
overflowTwin : Widget

internal

READONLY
Field

This widget's twin that is placed in an overflow menu when this widget has been hidden by its owner, typically a Toolbar due to overflow. The overflowTwin is created lazily by ensureOverflowTwin.
span : Number
Field

Programmatic control over how many columns to span when used in a grid layout.

Has a corresponding span config.
containsFocus : Boolean

READONLY
Field

This property is set to true when focus is within the ownership tree of this Widget.

This means that either the DOM of this widget contains focus, or, any widget DOM who's owner axis leads to this widget contains focus.

For example a DateField with its DatePicker open and being interacted with will still have containsFocus set.
nextSibling : Widget

READONLY
Field

Get this Widget's next sibling in the parent Container, or, if not in a Container, the next sibling widget in the same parentElement.
owner : Widget/Column

READONLY
Field

The owning Widget of this Widget. If this Widget is directly contained (i.e. it is one of the items of a Container), this property will be read-only, and will refer to the containing Widget.

If this property has not been set and this is a Popup with a forElement, this config will refer to that element's encapsulating Widget.

If this Widget is floating, this property should be set by the developer.

Registering with an owner creates a lifecycle relationship with that owning Widget. When the owner is destroyed this widget will also be destroyed.

A widget can unregister from its owner and break this relationship at any time by setting the property to null. It is then the developer's responsibility to ensure that this Widget is destroyed.

Has a corresponding owner config.
parent : Widget
Field

Get this Widget's parent when used as a child in a Container,
previousSibling : Widget

READONLY
Field

Get this Widget's previous sibling in the parent Container, or, if not in a Container, the previous sibling widget in the same parentElement.

Functions

Functions are methods available for calling on the class

hasConfigPath( object, path )
: Boolean

internal

static
Field

Determines if the specified config property exists in an instance of Base
mergeConfigs( baseConfig, ...configs )
: Object

internal

static
Field

Returns the merge of the baseConfig and config config objects based on the configs defined by this class.
new( ...configs )
: Base

private

static
Field

Factory version of the Base constructor. Merges all arguments to create a config object that is passed along to the constructor.
onClassMixedIn( )

internal

static
Field

This optional class method is called when a class is mixed in using the mixin() method.
applyDefaults( defaultsObj )

static

ADVANCED
Field
Merges the provided default configuration values with the existing defaults for this class (and its subclasses).

This method allows you to define additional or override existing default property values that apply to all instances of the class.
```
// All my input fields should be clearable
 Field.applyDefaults({
     clearable : true
});
```
getDefaultConfiguration( )
: Object

internal

static
Field

Gets the full defaultConfig block for this object's entire inheritance chain all the way up to but not including Base
setupConfigs( meta, configs, simple )

private

static
Field

This method is called as part of setupClass(). It will process the configurable() return object and the defaultConfig return object.
setupDelayableMethods( delayable, cls )

private

static
Delayable

This method initializes the delayable methods on this class.
create( config )
: Object

static
Field

Creates a new widget instance based on the passed config object. The config object is require to have a type property which determines what kind of widget to create.
destroy( ...args )

static

ADVANCED
Field
Destroys the provided objects by calling their destroy method. Skips empty values or objects that are already destroyed.
```
Base.destroy(myButton, toolbar1, helloWorldMessageBox);
```
initClass( )

static

ADVANCED
Field
Call once per class for custom widgets to have them register with the Widget class, allowing them to be created by type.

For example:
```
class MyWidget extends Widget {
  static get type() {
    return 'mywidget';
  }
}
MyWidget.initClass();
```

localize( text, templateData )

: String

internal

static

Localizable

Get localized string, returns null if no localized string found.

// Simple localization
const someText = SomeClass.localize('L{text}');

// With template data
const someText = SomeClass.localize('L{template}', { count : 5 }); // Number in object
const someText = SomeClass.localize('L{template}', { name : 'John' }); // String in object
const someText = SomeClass.localize('L{template}', 'John'); // Strings parameter

attachTooltip( element, configOrText )
: HTMLElement

static
Field
Attached a tooltip to the specified element.
```
Widget.attachTooltip(element, {
  text: 'Useful information goes here'
});
```
fromElement( element, type, limit )
: Widget/null

static
Field

Returns the Widget which owns the passed element (or event).

This is aliased on the global bryntum object as bryntum.fromElement.
fromSelector( selector )
: Widget/null

static
Field
Returns the Widget which owns the passed CSS selector.
```
const button = Widget.fromSelector('#my-button');
```
getById( id )
: Widget

static
Field

Returns the widget with the specified id.
isOfTypeName( type )
: Boolean

static

ADVANCED
Field

Checks if an obj is of type using object's $name property and doing string comparison of the property with the type parameter.
mixin( ...mixins )
: Function

static

ADVANCED
Field
Applies one or more mixins to this class and returns the produced class constructor.

For example, instead of writing this:
```
 class A extends Delayable(Events(Localizable(Base))) {
     // ...
 }
```
Using this method, one would write this:
```
 class A extends Base.mixin(Localizable, Events, Delayable) {
     // ...
 }
```
If one of the mixins specified has already been mixed into the class, it will be ignored and not mixed in a second time.
setupClass( meta )

internal

static
Field

This method is called only once for any class. This can occur when the first instance is created or when the $meta object is first requested.

constructor( ...args )

ADVANCED
Field

Base constructor, passes arguments to construct.
clear( )
: Promise

ASYNC

Clears field value
pickFile( )

internal

Opens browser file picker
_thisIsAUsedExpression( expression )

internal
Field

This method is required to help unused getters to survive production build process. Some tools, like angular, will remove unused code in production build, making our side-effected getters behind, breaking code heavily.
bindConfigs( target, mapping, options )
: Function

internal
Field

Creates a binding between the specified config properties of this object and the specified target object. Changes to these config properties of this object will be reflected to the target object as they occur, and (optionally), vise-versa.

Returns a function to call to remove the binding.
delay( fn, delay, name )
: Number

private
Field

Delays the execution of the passed function by the passed time quantum, or if the time is omitted or not a number, delays until the next animation frame. Note that this will use setTimeout || requestAnimationFrame if this class mixes in Delayable, otherwise it uses the global methods. The function will be called using this object as its execution scope.
hasConfig( name )
: Boolean

internal
Field

Returns true if this instance has a non-null value for the specified config. This will not activate a lazy config.
peekConfig( name )
: *

internal
Field

Returns the value of an uningested config without ingesting the config or transforming it from its raw value using its changeXxxxx method.
trackDetacher( name, detacher )

private
Field

Tracks a detacher function for the specified listener name.
triggerConfig( name )
: Boolean

internal
Field

Ensures that the specified config is initialized if it is needed. If there is a config value specified, and it was initialized by this call, this method returns true. If there was a config value specified, and it was already initialized, this method returns false. If there was no value specified for the given config, this method returns null.

This is not the same as just reading the property, because some property getters exist that do not actually just read the config value back, but instead produce some result. Reading such properties to incidentally trigger a possible config initializer can lead to incorrect results. For example, the Combo items config.
triggerConfigs( group )
: String[]

internal
Field

This call will activate any pending lazy configs that were assigned a string value equal to the group parameter.
untrackDetachers( eventer )

private
Field

Removes all detacher functions for the specified Events object. This is called by the removeAllListeners method on that object which is typically called by its destroy invocation.
updateConfiguration( props )

internal
Field

This is intended to set a block of configs during configuration. It is not intended to be used outside of the configuration phase.

If any of the properties are not yet ingested from the configuration object, they will be set and ingested in the normal order.

Properties which are already ingested are set immediately.
classHierarchy( topClass )
: Function[]

private
Field

Used by the Widget and GridFeatureManager class internally. Returns the class hierarchy of this object starting from the topClass class (which defaults to Base).

For example classHierarchy(Widget) on a Combo would yield [Widget, Field, TextField, PickerField, Combo]
getConfig( name, ...names )
: *

internal
Field
Returns the value of the specified config property. This is a method to allow property getters to be explicitly called in a way that does not get optimized out.

The following triggers the getter call, but optimizers will remove it:
```
 inst.foo;   // also raises "expression has no side-effects" warning
```
Instead, do the following to trigger a getter:
```
 inst.getConfig('foo');
```
getProperties( )
: Object

private
Field

Gets the full properties block for this class's entire inheritance chain all the way up to but not including Base
onConfigChange( info )

internal
Field

This method is called when any config changes.
emptyCache( )

internal
Field

Clear caches, forces all calls to fromCache to requery dom. Called on render/rerender.
focus( options )
Field

Focuses this widget if it has a focusable element.
fromCache( query, childrenfalse, element )
: HTMLElement/HTMLElement[]/null

internal
Field

Gets dom elements in the view. Caches the results for faster future calls.
getStaticWidgetClasses( topMostBase, suffix )
: DomClassList

internal
Field

Returns a DomClassList computed from the topMostBase (e.g., Widget or Panel) with the given suffix appended to each widgetClass.
asap( fn, options )
: Function

internal
Delayable

Returns a function that when called will schedule a call to fn via queueMicrotask.
buffer( fn, options )
: Function

internal
Delayable

Wraps a function with another function that delays it specified amount of time, repeated calls to the wrapper resets delay.
cancelAnimationFrame( handle )

internal
Delayable

Relays to native cancelAnimationFrame and removes from tracking.
cancelIdleCallback( handle )

internal
Delayable

Relays to native cancelIdleCallback and removes from tracking.
cancelMicrotask( task )

internal
Delayable

Given the return value from a call to queueMicrotask, cancels the pending call. This method is provided for symmetry with other timer functions, such as setTimeout.
clearInterval( id )

internal
Delayable

clearInterval wrapper
clearTimeout( idOrName )

internal
Delayable

clearTimeout wrapper, either call with timeout id as normal clearTimeout or with timeout name (if you specified a name to setTimeout()) property to null.
createOnFrame( fn, args, thisObj, cancelOutstandingfalse )
: Function

Delayable

Creates a function which will execute once, on the next animation frame. However many time it is called in one event run, it will only be scheduled to run once.
decorateWrapFn( me, wrapFn, cancelFnclearTimeout )
: Function

private
Delayable

Decorates the supported wrapFn with additional methods and an isPending readonly property. These decorations are available to user code to help manage the scheduling behavior of the buffered function.
hasTimeout( name )

internal
Delayable

Check if a named timeout is active
makeInvoker( me, fn, wrapFn, options )
: Function

private
Delayable

Creates and returns a function that will call the user-supplied fn.
queueMicrotask( fn, args, options )
: Function

internal
Delayable

Equivalent to the native queueMicrotask, but will be cancelled automatically on destroy. When queueMicrotask is not available, the provided fn is called using Promise.resolve().then(fn), which behaves similarly.

Returns a function that when called will cancel the impending call. This function can also be viewed as a timer id that can be passed to cancelMicrotask
raf( fn, options )
: Function

internal
Delayable

Returns a function that when called will schedule a call to fn on the next animation frame.
requestAnimationFrame( fn, extraArgs, thisObj )
: Number

internal
Delayable

Relays to native requestAnimationFrame and adds to tracking to have call automatically canceled on destroy.
requestIdleCallback( fn, extraArgs, thisObj )
: Number

internal
Delayable

Relays to native requestIdleCallback and adds to tracking to have call automatically canceled on destroy.
setInterval( fn, delay, name )
: Number

internal
Delayable

Same as native setInterval, but will be cleared automatically on destroy
setTimeout( timeoutSpec )
: Number

internal
Delayable

Same as native setTimeout, but will be cleared automatically on destroy. If a propertyName is supplied it will be used to store the timeout id.
throttle( fn, options )

internal
Delayable

Create a "debounced" function which will call on the "leading edge" of a timer period. When first invoked will call immediately, but invocations after that inside its buffer period will be rejected, and one invocation will be made after the buffer period has expired.

This is useful for responding immediately to a first mousemove, but from then on, only calling the action function on a regular timer while the mouse continues to move.
addListener( config, thisObj, oldThisObj )
: Function

Events
Adds an event listener. This method accepts parameters in the following format:
```
 myObject.addListener({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });
```
When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:
```
myObject.addListener('click', myController.handleClicks, myController);
```
The args in this simple case are eventName, handler and thisObj

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed. Set the catchEventHandlerExceptions config to true to catch exceptions thrown by this object's event handlers and allow the event to continue processing. The exception will be rethrown on a zero millisecond timeout,
attachAutoDetacher( )

private
Events

Internal function used to hook destroy() calls when using thisObj
await( eventName, options )
: Promise

private

ASYNC
Events
detachAutoDetacher( )

private
Events

Internal function used restore hooked destroy() calls when using thisObj
detachListeners( name )

ADVANCED
Field

Removes all event listeners that were registered with the passed names.
doDestroy( )

internal
Events

Auto detaches listeners registered from start, if set as detachable
findListener( eventName, listenerToFind, defaultThisObj )

internal
Events

Finds the index of a particular listener to the named event. Returns -1 if the passed function/thisObj listener is not present.
hasListener( eventName )
: Boolean

ADVANCED
Events

Returns true if any listener is registered for the specified eventName, or if null, for any event.
ion( )

internal
Events

Internal convenience method for adding an internal listener, that cannot be removed by the user.

Alias for on({ $internal : true, ... }). Only supports single argument form.
numListeners( eventName )
: Number

internal
Events

Returns the number of attached listener for the specified eventName, or if null, for any event.

on( config, thisObj, oldThisObj )

: Function

Events

Alias for addListener. Adds an event listener. This method accepts parameters in the following format:

 myObject.on({
     thisObj    : this,          // The this reference for the handlers
     eventname2 : 'functionName' // Resolved at invocation time using the thisObj,
     otherevent : {
         fn      : 'handlerFnName',
         once    : true          // Just this handler is auto-removed on fire
     },
     yetanother  : {
         fn      : 'yetAnotherHandler',
         args    : [ currentState1, currentState2 ] // Capture info to be passed to handler
     },
     prio        : 100           // Higher prio listeners are called before lower
 });

When listeners have a thisObj option, they are linked to the lifecycle of that object. When it is destroyed, those listeners are removed.

The config parameter allows supplying options for the listener(s), for available options see BryntumListenerConfig.

A simpler signature may be used when only adding a listener for one event and no extra options (such as once or delay) are required:

myObject.on('click', myController.handleClicks, myController);

The args in this simple case are eventName, handler and thisObj

onListen( eventName )

internal
Events

This method is called when the first listener for an event is added.
onUnlisten( eventName )

internal
Events

This method is called when the last listener for an event is removed.
once( )

private
Events

Internal function used to run a callback function after an event is triggered

relayAll( through, prefix, transformCasetrue )

ADVANCED

Events

Relays all events through another object that also implements Events mixin. Adds a prefix to the event name before relaying, for example add -> storeAdd

// Relay all events from store through grid, will make it possible to listen for store events prefixed on grid:
'storeLoad', 'storeChange', 'storeRemoveAll' etc.
store.relayAll(grid, 'store');

grid.on('storeLoad', () => console.log('Store loaded');

removeAllListeners( )
Events

Removes all listeners registered to this object by the application.
removeListener( config, thisObj, oldThisObj )
: Boolean

Events

Removes an event listener. Same API signature as addListener
resumeEvents( )
: Boolean

ADVANCED
Events

Resume event triggering after a call to suspendEvents(). If any triggered events were queued they will be triggered.
suspendEvents( queuefalse )

ADVANCED
Events

Prevents events from being triggered until resumeEvents() is called. Optionally queues events that are triggered while suspended. Multiple calls stack to require matching calls to resumeEvents() before actually resuming.
trigger( eventName, param )
: Boolean/Promise

ASYNC

ADVANCED
Events

Triggers an event, calling all registered listeners with the supplied arguments. Returning false from any listener makes function return false.

By default, if an event handler throws an exception, the error propagates up the stack and the application state is undefined. Code which follows the event handler will not be executed. Set the catchEventHandlerExceptions config to true to catch exceptions thrown by this object's event handlers and allow the event to continue processing. The exception will be rethrown on a zero millisecond timeout,
un( config, thisObj, oldThisObj )
: Boolean

Events

Shorthand for removeListener
getAfterValue( text )
: String

private
Field

Returns the input value for this field's input element that will be present if the event carrying the given text is allowed to proceed.
hasChanged( oldValue, newValue )

private
Field

Compares this field's value with its previous value. May be overridden in subclasses which have more complex value types. See, for example, DurationField.
internalOnChange( )

private
Field

Trigger event when fields input changes

Triggers: change
internalOnInput( event )

private
Field

Trigger event when user inputs into field

Triggers: input
onDisabled( )

private
Field

Called when disabled state is changed. Used to add or remove 'b-invalid' class for the invalid field based on current disabled state.
onEditComplete( )

internal
Field

Template function which may be implemented by subclasses to synchronize input state and validity state upon completion of the edit.
select( start, end )
Field

Selects the field contents. Optionally may be passed a start and end.
syncInputFieldValue( skipHighlightfalse )
: void

ADVANCED
Field

Called by the base Field class's set value to sync the state of the UI with the field's value.

Relies upon the class implementation of get inputValue to return a string representation of the value for user consumption and editing.

This method can be overridden.
alignTo( spec )
Field

If this Widget is floating or positioned, and visible, aligns the widget according to the passed specification. To stop aligning, call this method without arguments.
setXY( x, y )
Field

Moves this Widget to the x,y position. Both arguments can be omitted to just set one value.

For floating Widgets, this is a position in the browser viewport.For positioned Widgets, this is a position in the element it was rendered into.
showBy( align )
: Promise

ASYNC
Field

Show aligned to another target element or Widget or Rectangle
toFront( )
Field

Only valid for floating Widgets. Moves to the front of the visual stacking order.

addKeyBinding( key, action )

internal

KeyMap

Add a key binding to this widget's keyMap.

// Add a key binding to the widget to call its own onCtrlEnter method when Ctrl+Enter is pressed.
myWidget.addKeyBinding('Ctrl+Enter', 'onCtrlEnter');

matchKeyMapEntry( keyEvent, keyMapthis.keyMap )
: String

internal
KeyMap

Returns the keyMap property name which matches the passed KeyboardEvent if any.
mergeKeyMaps( target, source, subPrefix )

private
KeyMap

This function is used for merging two keyMaps with each other. It can be used for example by a Grid's feature to merge the fetature's keyMap into the Grid's with the use of a subPrefix.
performKeyMapAction( )
: Promise

private

ASYNC
KeyMap

Called on keyMapElement keyDown

removeKeyBinding( action )

internal

KeyMap

Remove a key binding to this widget's keyMap.

// Add a key binding to the widget to call its own onCtrlEnter method when Ctrl+Enter is pressed.
myWidget.removeKeyBinding('Ctrl+Enter', 'onCtrlEnter');

resolveKeyMapAction( )

private
KeyMap

Resolves correct this and handler function. If subComponent (action includes a dot) it will resolve in keyMapSubComponents (defaults to this.features).

For example, in feature configurable: keyMap: { ArrowUp: 'navigateUp' }

Will be translated (by InstancePlugin) to: `keyMap: { ArrowUp: 'featureName.navigateUp' }

And resolved to correct function path here.

Override to change action function mapping.
afterConfigure( )

internal
Field

Base implementation so that all subclasses and mixins may safely call super.afterConfigure. This is called by the Base class after the configure method has been called. At this point, all configs have been applied.

This method allows all classes in the hierarchy to inject functionality either before or after the super.afterConstruct();
afterConstruct( )

internal
Field

Base implementation so that all subclasses and mixins may safely call super.afterConstruct.

This is called by the Base class after the construct method has been called.

At this point, all configs have been applied.

This method allows all classes in the hierarchy to inject functionality either before or after the super.afterConstruct();
configure( config )

internal
Field

Called by the Base constructor to apply configs to this instance. This must not be called.
construct( ...args )

ADVANCED
Field

Base implementation applies configuration.

Subclasses need only implement this if they have to initialize instance specific properties required by the class. Often a construct method is unnecessary. All initialization of incoming configuration properties can be done in a set propName implementation.
destroyProperties( ...properties )

internal
Field
Destroys the named properties if they have been initialized, and if they have a destroy method. Deletes the property from this object. For example:
```
 this.destroyProperties('store', 'resourceStore', 'eventStore', 'dependencyStore', 'assignmentStore');
```
finalizeInit( )

internal
Field

Called by the Base constructor after all configs have been applied.
finishConfigure( )

internal
Field

Base implementation so that all subclasses and mixins may safely call super.finishConfigure.

This is called by the Base class before exiting the configure method.

At this point, all configs have been applied, but the isConfiguring property is still set.

This method allows all classes in the hierarchy to inject functionality into the config phase.
setConfig( config )

ADVANCED
Field

Sets configuration options this object with all the properties passed in the parameter object. Timing is taken care of. If the setter of one config is called first, and references the value of another config which has not yet been set, that config will be set just in time, and the new value will be used.
startConfigure( )

internal
Field

Base implementation so that all subclasses and mixins may safely call super.startConfigure.

This is called by the Base class before setting configuration properties, but after the active initial getters have been set, so all configurations are available.

This method allows all classes in the hierarchy to force some configs to be evaluated before others.

L( text, templateData )

: String

ADVANCED

Localizable

Localization function on the class instance that mixes Localizable.

// Simple localization
const someText = someClass.L('L{text}');

// With template data
const someText = someClass.L('L{template}', { count : 5 }); // Number in object
const someText = someClass.L('L{template}', { name : 'John' }); // String in object
const someText = someClass.L('L{template}', 'John'); // Strings parameter

animateProperty( propertyName, newValue, duration1000, easing'linear' )
Field

Changes the value of a numeric property of this object smoothly over the specified duration.
callback( fn, thisObject, args )

ADVANCED
Field

Provides a way of calling callbacks which may have been specified as the name of a function and optionally adds scope resolution.

For example, if the callback is specified as a string, then if it is prefixed with 'this.' then the function is resolved in this object. This is useful when configuring listeners at the class level.

If the callback name is prefixed with 'up.' then the ownership hierarchy is queried using the owner property until an object with the named function is present, then the named function is called upon that object.

If a named function is not found, an error is thrown. If the function should be only called when present, and may not be present, add a ? as a suffix.
downloadTestCase( )
Field

Experimental helper function, extracts the currently used configs and wraps them as an app, downloading the resulting JS file.

This function is intended to simplify creating test cases for issue reporting on Bryntum's support forum.

optionalL( text, templateData, preventThrowfalse )

: String

internal

Localizable

Localization function to get an optional translation. The difference compared to L() is that it won't throw an error when the translation is missing even if configured with throwOnMissingLocale.

button.text = grid.optionalL('L{text}');

// With template data
const someText = someClass.optionalL('L{template}', { count : 5 }); // Number in object
const someText = someClass.optionalL('L{template}', { name : 'John' }); // String in object
const someText = someClass.optionalL('L{template}', 'John'); // Strings parameter

resolveCallback( handler, thisObj, enforceCallabilitytrue )
: Object

ADVANCED
Field

Provides a way of locating callbacks which may have been specified as the name of a function and optionally adds scope resolution.

For example, if the callback is specified as a string, then if it is prefixed with 'this.' then the function is resolved in this object. This is useful when configuring listeners at the class level.

If the callback name is prefixed with 'up.' then the ownership hierarchy is queried using the owner property until an object with the named function is present, then the named function is called upon that object.
updateLocalization( )

ADVANCED
Localizable

Method that is triggered when applying a locale to the instance (happens on the instance construction steps and when switching to another locale).

The method can be overridden to dynamically translate the instance when locale is switched. When overriding the method please make sure you call super.updateLocalization().
clearError( error, silentfalse )
Validatable

Removes an error message from the list of errors on this field.

By default, the field's valid/invalid state is updated; pass false as the second parameter to disable that if multiple changes are being made to the error state.
getErrors( )
: String[]

Validatable

Returns an array of error messages as set by setError, or undefined if there are currently no errors.
setError( error, silentfalse, temporaryfalse )
Validatable

Adds an error message to the list of errors on this field. By default, the field's valid/invalid state is updated; pass false as the second parameter to disable that if multiple changes are being made to the error state.

Note, that you need to manually remove the added error with the clearError method to "release" the normal data update process (invalid data won't be synced). You can also use the 3rd argument of this method to automatically remove the error upon the next user interaction.
hide( animatetrue )
: Promise

ASYNC
Field

Hide widget
show( options )
: Promise

ASYNC
Field

Shows this widget
addRefAccessor( name, key )

private
Field

Defines an element reference accessor on the class prototype. This accessor is used to flush any pending DOM changes prior to accessing such elements.
afterRecompose( )

internal
Field

This method is called following an update to the widget's rendered DOM.
animationsFinished( element, subtreetrue )
: Promise

internal

ASYNC
Field

Returns a Promise which resolves when all finite animations on or within the element are finished.

Pass subtree as false to only consider animations directly on the element.
announceAriaLive( message )
Field

Announces a text message that can be parsed by assistive technologies using an aria-live element.
attachRef( name, el, domConfig )

internal
Field

This method is called by DomHelper.createElement and DomSync.sync as new reference elements are created.
captureFocus( )
: Function

internal
Field

Returns a function that will set the focus (document.activeElement) to the most consistent element possible based on the focus state at the time this method was called. Derived classes can implement captureFocusItem() to refine this process to include logical items (e.g., a grid cell) that would be more stable than DOM element references.

If this widget does not contain the focus, the returned function will do nothing.
captureFocusItem( activeElement )
: Function

internal
Field

This method is called by captureFocus() when this widget contains the focus and it returns a function that restores the focus to the correct internal element. The returned function is only called if the current document.activeElement is different from the passed activeElement.

This method can be replaced by derived classes to capture stable identifiers for the currently focused, logical item (for example, a cell of a grid).
compose( )
: DomConfig

ADVANCED
Field

Returns a createElement config object that defines this widget's DOM structure. This object should be determined using configurable properties to ensure this method is called again if these properties are modified.

For more information see class documentation.
configureOverflowTwin( overrides )
: Object

internal
Field

This method returns the config object to use for creating this widget's overflowTwin.
createOverflowTwin( overrides )
: Widget

internal
Field

This method creates the overflowTwin for this widget. It is called by ensureOverflowTwin if the overflowTwin does not yet exist.

The config for the overflowTwin is produced by configureOverflowTwin.
detachRef( name, el, domConfig )

internal
Field

This method is called by DomSync.sync as reference elements are removed from the DOM.
disable( )
Field

Disable the widget
doCompose( )
: Object

private
Field

This method iterates the class hierarchy from Widget down to the class of this instance and calls any compose methods implemented by derived classes.
domSyncCallback( info )

internal
Field

Template method called during DOM updates. See DomSync.sync().
enable( )
Field

Enable the widget
ensureOverflowTwin( overrides, onCreate )
: Widget

internal
Field

This method returns the existing overflowTwin or creates it, if it has not yet been created (see createOverflowTwin).
executeAndAwaitAnimations( element, fn, animationCls )
: Promise

internal

ASYNC
Field

Executes a function which initiates animations, and waits for any animations within the passed element to complete.

Takes a snapshot of animations running before and after the function executes and waits for any animations started due to that function to finish.
exitFullscreen( )
: Promise

ASYNC
Field

Exits fullscreen mode
fixRefOwnerId( el, id, oldId )

private
Field

This method fixes the element's $refOwnerId when this instance's id is changing.
getFocusRevertTarget( )

internal
Field

This method finds a close sibling (or parent, or parent's sibling etc. recursively) to which focus can be directed in the case of revertFocus not having a focusable element from our focusInEvent.

This can happen when the "from" component is destroyed or hidden. We should endeavour to prevent focus escaping to document.body for accessibility and ease of use, and keep focus close.
getRenderContext( source )
: HTMLElement[]

internal
Field

Interprets the appendTo, insertBefore and insertFirst configs to return an array containing [parentElement, insertBefore]
isCollapsified( options )
: Boolean

internal
Field

This method determines if this widget (typically a Tool) should be placed in the header of the calling Panel.
isolateFieldChange( field )

internal
Field

Returns true if the given field's value change should be isolated (kept hidden by this widget). By default, this method returns the value of isolateFields for all fields.
mask( msg )
: Mask

Field

Mask the widget, showing the specified message
onAlignTargetOutOfView( target )

internal
Field

This method is called when the alignTo target element loses intersection with the visible viewport. That means it has been scrolled out of view, or becomes zero size, or hidden or is removed from the DOM.

The base class implementation hides by default.
realign( )

internal
Field

Called when an element which affects the position of this Widget's align target scrolls so that this can realign.

If the target has scrolled out of view, then this Widget is hidden.
recompose( )
: Promise

ASYNC

ADVANCED
Field
Calling this delayable method marks this widget as dirty. The DOM will be updated on the next animation frame:
```
 widget.recompose();

 console.log(widget.recompose.isPending);
 > true
```
A pending update can be flushed by calling flush() (this does nothing if no update is pending):
```
 widget.recompose.flush();
```
This can be combined in one call to force a DOM update without first scheduling one:
```
 widget.recompose.now();
```
rectangle( which'border', relativeTo, ignorePageScrollfalse )
: Rectangle

internal
Field

Returns the specified bounding rectangle of this widget.
rectangleOf( element, which'border', relativeTo, ignorePageScrollfalse )
: Rectangle

internal
Field

Returns the specified bounding rectangle of the specified child element of this widget.
requestFullscreen( )
: Promise

ASYNC
Field

Requests fullscreen display for this widget
resumeVisibility( triggerPainttrue )

internal
Field

Resumes visibility. If the suspension counter is returned to zero by this, then the paint event is triggered, causing a cascade of paint events on all descendants. This can be prevented by passing false as the only parameter.
revertFocus( force )

ADVANCED
Field

If this Widget contains focus, focus is reverted to the source from which it entered if possible, or to a close relative if not.
suspendVisibility( )

internal
Field

Temporarily changes the isVisible to yield false regardless of this Widget's true visibility state. This can be useful for suspending operations which rely on the isVisible property.

This increments a counter which resumeVisibility decrements.
template( me )

internal
Field

A function which, when passed an instance of this Widget, produces a valid HTML string which is compiled to create the encapsulating element for this Widget, and its own internal DOM structure.

Note that this just creates the DOM structure that this Widget owns. If it contains child widgets (Such as for example a grid), this is not included. The template creates own structure.

Certain elements within the generated element can be identified as special elements with a reference="name" property. These will be extracted from the element upon creation and injected as the named property into the Widget. For example, a TextField will have an input property which is its <input> element.
triggerFieldChange( params, triggertrue )

internal
Field

Triggers a 'change' event with the supplied params. After triggering it also calls onFieldChange() on each ancestor the implements that function, supplying the same set of params.
unmask( )
Field

Unmask the widget
validateDragStartEvent( e )
: Boolean

internal
Field

Validates a dragstart event with respect to the target element. Dragging is not normally initiated when the target is interactive such as an input field or its label, or a button. This may be overridden to provide custom drag start validation.
closest( selector, deep, limit )
: Widget/null

Field

Starts with this Widget, then Looks up the owner axis to find an ancestor, which matches the passed selector. The selector may be a widget type identifier, such as 'grid', or a function, which will return true when passed the desired ancestor.
contains( elementOrWidget, strict )
: Boolean

Field

Returns true if this widget is or contains the specified element or widget.
eachAncestor( fn )
: Boolean

Field

Iterate over all ancestors of this widget.

Note: Due to this method aborting when the function returns false, beware of using short form arrow functions. If the expression executed evaluates to false, iteration will terminate.
eachWidget( fn, deeptrue )
: Boolean

Field

Iterate over all widgets owned by this widget and any descendants.

Note: Due to this method aborting when the function returns false, beware of using short form arrow functions. If the expression executed evaluates to false, iteration will terminate.

Note: for Button class: Due to the menu config being a lazy config and only being converted to be a Menu instance just before it's shown, the menu will not be part of the iteration before it has been shown once.

Note: for PickerField class: Due to the picker config being a lazy config and only being converted to be a List instance just before it's shown, the picker will not be part of the iteration before it has been shown once.
getWidgetByRef( ref )
: Widget

internal
Field

Get a widget by ref, starts on self and traverses up the owner hierarchy checking widgetMap at each level. Not checking the top level widgetMap right away to have some acceptance for duplicate refs.
owns( target )
Field

Returns true if this Widget owns the passed Element, Event or Widget. This is based on the widget hierarchy, not DOM containment. So an element in a Combo's dropdown list will be owned by the Combo.
query( filter )
: Widget

Field

Returns the first descendant widgets, which the passed filter function returns true for.
queryAll( filter )
: Widget[]

Field

Returns an array of all descendant widgets which the passed filter function returns true for.
up( selector, deep, limit )
: Widget/*

Field

Looks up the owner axis to find an ancestor which matches the passed selector. The selector may be a widget type identifier, such as 'grid', or a function which will return true when passed the desired ancestor.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

action
Field

User performed default action (typed into this field).
beforeDestroy
Events

Fires before an object is destroyed.
beforeHide

PREVENTABLE
Field

Triggered before a widget is hidden. Return false to prevent the action.
beforeShow

ASYNC

PREVENTABLE
Field

Triggered before a widget is shown. Return false to prevent the action.
catchAll
Events

Fires when any other event is fired from the object.

Note: catchAll is fired for both public and private events. Please rely on the public events only.
change
Field

Fired when this field's value changes.
clear
Field

Fired when this field is cleared.

This will be triggered when a user clicks this field's clear trigger
destroy
Events

Fires when an object is destroyed.
elementCreated
Field

Triggered when a widget's element is available.
focusIn
Field

Fired when focus enters this Widget.
focusOut
Field

Fired when focus exits this Widget's ownership tree. This is different from a blur event. focus moving from within this Widget's ownership tree, even if there are floating widgets will not trigger this event. This is when focus exits this widget completely.
hide
Field

Triggered after a widget was hidden
input
Field

Fired when the user types into this field.
paint
Field

Triggered when a widget which had been in a non-visible state for any reason achieves visibility.

A non-visible state might mean the widget is hidden and has just been shown.

But this event will also fire on widgets when a non-visible (unrendered, or hidden) ancestor achieves visibility, for example a Popup being shown.

TLDR: This event can fire multiple times
readOnly
Field

Fired when a Widget's read only state is toggled
recompose

ADVANCED
Field

This event is fired after a widget's elements have been synchronized due to a direct or indirect call to recompose, if this results in some change to the widget's rendered DOM elements.
resize
Field

Fired when the encapsulating element of a Widget resizes only when monitorResize is true.
show
Field

Triggered after a widget is shown.
trigger
Field

User clicked one of this field's triggers

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onAction
Field

User performed default action (typed into this field).
onBeforeDestroy
Events

Called before an object is destroyed.
onBeforeHide

PREVENTABLE
Field

Called before a widget is hidden. Return false to prevent the action.
onBeforeShow

ASYNC

PREVENTABLE
Field

Called before a widget is shown. Return false to prevent the action.
onCatchAll
Events

Called when any other event is called from the object.

Note: catchAll is called for both public and private events. Please rely on the public events only.
onChange
Field

Called when this field's value changes.
onClear
Field

Called when this field is cleared.

This will be called when a user clicks this field's clear trigger
onDestroy
Events

Called when an object is destroyed.
onElementCreated
Field

Called when a widget's element is available.
onFocusIn
Field

Called when focus enters this Widget.
onFocusOut
Field

Called when focus exits this Widget's ownership tree. This is different from a blur event. focus moving from within this Widget's ownership tree, even if there are floating widgets will not trigger this event. This is when focus exits this widget completely.
onHide
Field

Called after a widget was hidden
onInput
Field

Called when the user types into this field.
onPaint
Field

Called when a widget which had been in a non-visible state for any reason achieves visibility.

A non-visible state might mean the widget is hidden and has just been shown.

But this event will also fire on widgets when a non-visible (unrendered, or hidden) ancestor achieves visibility, for example a Popup being shown.

TLDR: This event can fire multiple times
onReadOnly
Field

Called when a Widget's read only state is toggled
onRecompose

ADVANCED
Field

This event is called after a widget's elements have been synchronized due to a direct or indirect call to recompose, if this results in some change to the widget's rendered DOM elements.
onResize
Field

Called when the encapsulating element of a Widget resizes only when monitorResize is true.
onShow
Field

Called after a widget is shown.
onTrigger
Field

User clicked one of this field's triggers

CSS variables

CSS variables that can be set to adjust appearance

Name	Description
--b-file-field-button-background	Button background
--b-file-field-button-color	Button color

FileField
Widget

Useful configs and properties

See also

Configs

Handlers as function name

Target element filtering

Delegation

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Resolving a value from an owner

Value Merging

Config Options

Default Value

Options

Delayable Method API

`isPending` (Boolean, readonly)

`cancel()`

`flush()`

`now()`

Target element filtering

Delegation

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree4

Mixins8

Contents

FileField Widget

Useful configs and properties

See also

Configs

Handlers as function name

Target element filtering

Delegation

Parameters

Returns

Parameters

Returns

Parameters

Returns

Properties

Resolving a value from an owner

Value Merging

Config Options

Default Value

Options

Delayable Method API

isPending (Boolean, readonly)

cancel()

flush()

now()

Target element filtering

Delegation

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree4

Mixins8

Contents

FileField
Widget

`isPending` (Boolean, readonly)

`cancel()`

`flush()`

`now()`