Widget
The base class for all other widgets in the Bryntum libraries. The Widget base class encapsulates a native DOM element, and can optionally contain html. See also Container which lets you build a component tree where widgets can contain other widgets. Simple widget example (inspect with the DOM inspector to see it's really just a simple DIV):
Rendering
Subclasses should override the compose method to return their encapsulating element and internal DOM structure. The compose() method returns a createElement config object that is* used to create the DOM structure, based on its configurable properties:
class Button extends Widget {
static configurable = {
cls : null,
text : null
};
compose() {
const { cls, text } = this; // collect all relevant configs properties (for auto-detection)
return {
tag : 'button',
class : cls,
text
};
}
}
The config properties used by the compose() method are auto-detected when the method is first called for a class. All relevant properties must be read, even if they end up not being used so that future changes to these properties will mark the rendering as dirty.
When a config property used by compose() is modified, the recompose method is called. Since recompose() is a delayable method, calling it schedules a delayed call to compose() and a DOM update. Accessing the Widget's primary element or any reference element property will force the DOM update to occur immediately.
Lifecycle events
The lifecycle events provide hooks into the various stages of a widget's existence, allowing for custom behavior at key points.
These events include
-
elementCreated - Fired once, after the widget's main element has been created but before it is added to the DOM. At this stage it will have its style and cls applied. But since the element is not yet in the DOM, it will not be visible, nor will styles from CSS be applied.
If you need to measure the element (for example to set its size based on its content), you should add a listener for the paint event and perform your measurements there.
-
paint - Fired whenever the widget becomes visible and eligible for layout. This event may be fired multiple times during the lifetime of a widget, whenever it becomes visible after being hidden, or when an ancestor widget is shown after being hidden.
Note that to only react the first time a widget is painted, you can use the
onceoption when adding a listener early in the widget's lifecycle or check thefirstPaintproperty of the event object. -
beforeDestroy - Fired when the widget is being destroyed. At this stage the widget is still fully functional and can be interacted with if certain actions need to be called.
-
destroy - Fired after the widget has been destroyed. At this stage the widget's DOM elements have been removed from the DOM and all event listeners have been detached. The widget is completely inert and has no properties or methods.
Child Elements
Unlike typical DOM config objects, the object returned by compose() can use an object to simplify naming:
class Button extends Widget {
...
compose() {
const { cls, iconCls, text } = this; // collect all relevant configs properties (for auto-detection)
return {
tag : 'button',
class : cls,
children : {
iconElement : iconCls && {
class : {
'button-icon' : 1,
[iconCls] : 1
}
},
textElement : {
text
}
}
};
}
}
The keys of the children are iterated to convert the values into the array required by createElement. The names of the properties becomes the reference of the element.
For example, the above is equivalent to the following:
class Button extends Widget {
...
compose() {
const { cls, iconCls, text } = this; // collect all relevant configs properties (for auto-detection)
return {
tag : 'button',
class : cls,
children : [iconCls && {
reference : 'iconElement',
class : {
'button-icon' : 1,
[iconCls] : 1
}
}, {
reference : 'textElement',
text
}]
};
}
}
In other places inside your class, you can then access those elements as this.iconElement and this.textElement, no need to use querySelector etc.
The object form of children is preferred for clarity but also because it facilitates inheritance.
Inheritance
When a derived class implements compose(), the object it returns is automatically merged with the object returned by the base class.
For example, the following class adds a new child element:
class MenuButton extends Button {
...
compose() {
const { menuCls } = this; // collect all relevant configs properties (for auto-detection)
return {
children : {
menuElement : {
class : {
'button-menu' : 1,
[menuCls] : 1
}
}
}
};
}
}
Listeners
Reference elements may also define event listeners in the compose() method:
class Button extends Widget {
compose() {
const { cls, text } = this;
return {
tag : 'button',
class : cls,
text,
listeners : {
click : 'onClick'
}
};
}
onClick(event) {
// handle click event
}
}
Resolving properties
Values for a Widgets properties can be resolved from the ownership hierarchy. For example a text field in a toolbar can get its initial value from a property on the container owning the toolbar. This is achieved by prefixing the desired property name with 'up.':
const grid = new Grid((
tbar : [{
type : 'numberfield',
// Fields value will be retrieved from the grids rowHeight property
value : 'up.rowHeight'
}]
});
NOTE: 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.
Configs
Configs are options you supply in a configuration object when creating an instance of this class-
The
bottomCSS absolute position for this widget. If specified, the widget is implicitly configured as positionable. -
Programmatic control over which column to start in when used in a grid layout.
Has a corresponding runtime column property.
-
The
inset-inline-startCSS absolute position for this widget. If specified, the widget is implicitly configured as positionable. -
Set this config to
falseto 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. -
The
inset-inline-endCSS absolute position for this widget. If specified, the widget is implicitly configured as positionable. -
Programmatic control over how many columns to span when used in a grid layout.
Has a corresponding runtime span property.
-
The
topCSS absolute position for this widget. If specified, the widget is implicitly configured as positionable. -
The CSS class(es) to add when HTML content is being applied to this widget.
-
Custom style spec to add to element
Has a corresponding runtime style property.
-
The HTML content that coexists with 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 class added to its classList, to allow targeted styling.
Has a corresponding runtime content property.
-
Object to apply to elements dataset (each key will be used as a data-attribute on the element)
Has a corresponding runtime dataset property.
-
A createElement config object or HTML string from which to create the Widget's element.
Has a corresponding runtime element property.
-
Widget id, if not specified one will be generated. Also used for lookups through Widget.getById
Has a corresponding runtime id property.
-
Element (or element id) to insert this widget before. If provided, appendTo config is ignored.
Has a corresponding runtime insertBefore property.
-
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.
-
The tag name of this Widget's root element
-
A title to display for the widget. Only in effect when inside a container that uses it (such as TabPanel)
-
Only valid if this Widget is floating. Set to
trueto centre the Widget in browser viewport space. -
Only valid if this Widget is floating or positioned. Element, Widget or Rectangle to which this Widget is constrained.
-
Set to
trueto move the widget out of the document flow and position it absolutely in browser viewport space. -
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. -
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.
-
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 theflex-growvalue.Has a corresponding runtime flex property.
-
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.
-
Widget's margin. This may be configured as a single number or a
TRBLformat string. numeric-only values are interpreted as pixels.Has a corresponding runtime margin property.
-
A widgets weight determines its position among siblings when added to a Container. Higher weights go further down.
-
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.
-
When this Widget configuration is used in the Grid's RowExpander feature's
widgetconfig, provide the field on the expanded record to use for populating this widget's store (if applicable) -
Event that should be considered the default action of the widget. When that event is triggered the widget is also expected to trigger an
actionevent. Purpose is to allow reacting to most widgets in a coherent way. -
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
fieldis applied. -
Set to
trueto apply the default mask to the widget. Alternatively, this can be the mask message or a Mask config object. -
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.
-
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 -
Set to
falseto not show the tooltip when this widget is disabled -
The class to instantiate to use as the scrollable. Defaults to Scroller.
Properties
Properties are getters/setters or publicly accessible variables on this class-
Returns an array containing all existing Widgets. The returned array is generated by this call and is not an internal structure.
-
This property yields
trueif the currently focused element has been reached through other means than mouse click. If theactiveElementmatches:focus-visible. -
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
nullto disable the default setting for new widgets while leaving existing widgets unaffected.Has a corresponding recomposeAsync config.
-
Identifies an object as an instance of Widget class, or subclass thereof.
-
Programmatic control over which column to start in when used in a grid layout.
Has a corresponding column config.
-
Returns
trueif this class usescompose()to render itself. -
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
overflowTwinis created lazily by ensureOverflowTwin. -
Programmatic control over how many columns to span when used in a grid layout.
Has a corresponding span config.
-
This property yields
trueif the currently focused element has been reached through other means than mouse click. If theactiveElementmatches:focus-visible. -
Identifies an object as an instance of Widget class, or subclass thereof.
-
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.
Has a corresponding content config.
-
Get widgets elements dataset or assign to it
Has a corresponding dataset config.
-
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.
-
Get this widget's primary focus holding element if this widget is itself focusable, or contains focusable widgets.
-
Returns an object describing the focus and keyboard navigation aspects of this widget's focusElement.
-
Returns this widget's focusElement if that element can currently be given focus (e.g., this widget is not disabled, or hidden).
-
This property is set to
trueafter processing the initial paint for the widget. It remainsfalseduring 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 istrue, the initial paint has already taken place, otherwise, it has yet to run. This field differs fromisPaintedwhich checks that the widget's element is attached to the DOM. -
Get/set widgets id
Has a corresponding id config.
-
Element (or element id) to insert this widget before. If provided, appendTo config is ignored.
Has a corresponding insertBefore config.
-
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.
-
The child element which scrolls if any. This means the element used by the scrollable.
-
Returns the
DomClassListfor this widget's class. This object should not be mutated. -
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.
-
Get/set this widget's
align-selfflexbox 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.
-
Get element's
offsetHeightor sets itsstyle.height, or specified height if element no created yet.Has a corresponding height config.
-
Get element's margin property. This may be configured as a single number or a
TRBLformat string. numeric-only values are interpreted as pixels.Has a corresponding margin config.
-
Accessor to the Scroller which can be used to both set and read scroll information.
Has a corresponding scrollable config.
-
Get elements
offsetWidthor sets itsstyle.width, or specified width if element not created yet.Has a corresponding width config.
-
Get id assigned by user (not generated id)
-
Get/set element's disabled state. Set to
'inert'to also set theinertDOM attribute.Has a corresponding disabled config.
-
true if no id was set, will use generated id instead (widget1, ...). Toggle automatically on creation
-
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
-
Get this Widget's next sibling in the parent Container, or, if not in a Container, the next sibling widget in the same parentElement.
-
Get this Widget's parent when used as a child in a Container,
-
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-
afterRecompose( )internal
This method is called following an update to the widget's rendered DOM.
-
disable( )
Disable the widget
-
enable( )
Enable the widget
-
unmask( )
Unmask the widget
-
emptyCache( )internal
Clear caches, forces all calls to fromCache to requery dom. Called on render/rerender.
-
toFront( )
Only valid for floating Widgets. Moves to the front of the visual stacking order.
-
finalizeInit( )internal
Called by the Base constructor after all configs have been applied.