Widget<TSettings>
Defined in: js-api/src/widgets/base.ts:206
Base class for controls that have a visual root and a set of properties.
Extends
Extended by
Type Parameters
| Type Parameter | Default type |
|---|---|
TSettings | any |
Constructors
Constructor
new Widget<
TSettings>(widgetRoot):Widget<TSettings>
Defined in: js-api/src/widgets/base.ts:228
Parameters
| Parameter | Type |
|---|---|
widgetRoot | HTMLElement |
Returns
Widget<TSettings>
Overrides
Properties
| Property | Modifier | Type | Default value | Description | Inherited from | Defined in |
|---|---|---|---|---|---|---|
_functions | protected | Func[] | [] | - | - | js-api/src/widgets/base.ts:218 |
_properties | protected | Property[] | [] | - | - | js-api/src/widgets/base.ts:217 |
_root | protected | HTMLElement | undefined | - | Control._root | js-api/src/u2core/component.ts:666 |
_u2 | readonly | ComponentState | undefined | - | Control._u2 | js-api/src/u2core/component.ts:119 |
componentMeta? | public | ComponentMetaBase | undefined | The registry metadata of the tag that built this component, stamped by the spec renderer — the single source the introspection surface below is generated from. | Control.componentMeta | js-api/src/u2core/component.ts:114 |
dart | public | any | undefined | - | - | js-api/src/widgets/base.ts:223 |
factory | public | Func | null | null | Constructor function. No parameters, returns [Widget]. | - | js-api/src/widgets/base.ts:215 |
isDetached | public | boolean | false | Whether detach has been called. | - | js-api/src/widgets/base.ts:225 |
props | public | TSettings & ObjectPropertyBag | undefined | Property bag over this widget's properties; read and write them by name. | - | js-api/src/widgets/base.ts:220 |
specProps? | public | Record<string, unknown> | undefined | The props the registry's create was handed, stamped alongside componentMeta: the last resort of the property read below, for a component that keeps a prop under another name or not at all (a create wrapping a bare element). Construction-time values — a live one always wins. | Control.specProps | js-api/src/u2core/component.ts:118 |
subs | public | Subscription[] | undefined | Subscriptions cancelled when the widget is detached. | - | js-api/src/widgets/base.ts:222 |
temp | public | any | undefined | Contains auxiliary information | - | js-api/src/widgets/base.ts:212 |
isRoot | static | boolean | false | A root has no owner by design (a dialog): built with none, it is not reported as owner-missing. | Control.isRoot | js-api/src/u2core/component.ts:81 |
Accessors
aiDescription
Get Signature
get aiDescription():
string|null
Defined in: js-api/src/u2core/component.ts:337
A short AI-facing briefing, seeded from the registry's usage or description.
Returns
string | null
Set Signature
set aiDescription(
x):void
Defined in: js-api/src/u2core/component.ts:341
Parameters
| Parameter | Type |
|---|---|
x | string | null |
Returns
void
Inherited from
ambientAdoption
Get Signature
get
protectedambientAdoption():boolean
Defined in: js-api/src/widgets/base.ts:278
A widget wrapper minted inside somebody's effect scope must not be auto-disposed with it.
Returns
boolean
Overrides
children
Get Signature
get children():
Widget<any>[]
Defined in: js-api/src/widgets/base.ts:313
Parent widget up the DOM tree, or null.
Returns
Widget<any>[]
name
Get Signature
get name():
string|undefined
Defined in: js-api/src/u2core/component.ts:882
A named control carries its name in the DOM: data-u2-name is the stable automation id
selectors, tutorials and agents address the control by — the same attribute the spec renderer
stamps on named nodes, so hand-built and spec-built UI share one selector vocabulary.
Derived names (an input's label fallback) never stamp — see Component.deriveName.
Returns
string | undefined
Set Signature
set name(
x):void
Defined in: js-api/src/u2core/component.ts:886
Unique within a spec: the anchor for selection, patches and automation. An accessor pair
(not a field), so a platform descendant's own name accessors override it legally (TS2611).
Parameters
| Parameter | Type |
|---|---|
x | string | undefined |
Returns
void
Inherited from
parent
Get Signature
get parent():
Widget<any> |null
Defined in: js-api/src/widgets/base.ts:310
Parent widget up the DOM tree, or null.
Returns
Widget<any> | null
propertyTarget
Get Signature
get propertyTarget():
unknown
Defined in: js-api/src/u2core/component.ts:435
What this component's properties are read from and written to — prop.get(target) /
prop.set(target, v): the component itself, unless an adoption says otherwise.
Returns
unknown
Inherited from
propertyTier
Get Signature
get propertyTier():
boolean
Defined in: js-api/src/widgets/base.ts:282
Every property getProperties declares is a bind step, read and written on propertyTarget.
Returns
boolean
Overrides
root
Get Signature
get root():
HTMLElement
Defined in: js-api/src/u2core/component.ts:675
Returns
HTMLElement
Set Signature
set root(
x):void
Defined in: js-api/src/u2core/component.ts:679
Parameters
| Parameter | Type |
|---|---|
x | HTMLElement |
Returns
void
Inherited from
rootId
Get Signature
get rootId():
string
Defined in: js-api/src/u2core/component.ts:704
Stable element id, minted (u2-<n>) on first ask unless the root has one: the anchor of
for, aria-* and data-u2-owner-id references.
Returns
string
Inherited from
scope
Get Signature
get scope():
Scope
Defined in: js-api/src/u2core/component.ts:86
Minted on first use; assigned before _scopeMinted fires, so the hook's own
this.scope.own(...) reads the stored scope instead of re-entering the mint. Lazy: counted and tracked only
once it owns something, so a static control costs nothing.
Returns
Inherited from
type
Get Signature
get type():
string
Defined in: js-api/src/widgets/base.ts:209
Widget type name; subclasses override it.
Returns
string
visible
Get Signature
get visible():
boolean
Defined in: js-api/src/u2core/component.ts:694
Hidden ⇔ the root carries the hidden attribute.
Returns
boolean
Set Signature
set visible(
x):void
Defined in: js-api/src/u2core/component.ts:698
Parameters
| Parameter | Type |
|---|---|
x | boolean |
Returns
void
Inherited from
Methods
_notifyPropertyChange()
protected_notifyPropertyChange(p):void
Defined in: js-api/src/widgets/base.ts:360
Notifies the property tier. Called from both the addProperty setter (overrides that skip
super would otherwise lose props.x = writes) and onPropertyChanged (direct calls);
the double notify collapses into one microtask refresh.
Parameters
| Parameter | Type |
|---|---|
p | Property | null |
Returns
void
_ownPropertyChanges()
protected_ownPropertyChanges():ObservableLike<PropertyChange>
Defined in: js-api/src/widgets/base.ts:365
Returns
ObservableLike<PropertyChange>
_scopeMinted()
protected_scopeMinted(_scope):void
Defined in: js-api/src/widgets/base.ts:329
First-mint hook: a platform descendant wires its lifecycle here. Never fired for a scope provided to init — that path runs inside the constructor chain.
Parameters
| Parameter | Type |
|---|---|
_scope | Scope |
Returns
void
Overrides
_wireDartLifecycle()
protected_wireDartLifecycle():void
Defined in: js-api/src/widgets/base.ts:345
Dart-owned lifecycle: the platform kill disposes the scope, and disposing the scope kills the widget through the kill-walk.
Returns
void
_wireJsLifecycle()
protected_wireJsLifecycle():void
Defined in: js-api/src/widgets/base.ts:336
JS-owned lifecycle: disposing the scope detaches the widget, and vice versa.
Returns
void
_wireLifecycle()
protected_wireLifecycle():void
Defined in: js-api/src/widgets/base.ts:331
Returns
void
accessibleLabel()
protectedaccessibleLabel():string|undefined
Defined in: js-api/src/u2core/component.ts:762
The accessible name: aria-label, then the aria-labelledby texts, then this control's own
data-u2-part="label" element, then — for a root that is a button — its own text.
Returns
string | undefined
Inherited from
addProperty()
addProperty(
propertyName,propertyType,defaultValue?,options?):any
Defined in: js-api/src/widgets/base.ts:388
Registers an property with the specified type, name, and defaultValue.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
propertyName | string | undefined | - |
propertyType | "string" | "bigint" | "object" | "map" | "file" | "bool" | "int" | "double" | "byte_array" | "datetime" | "qnum" | "dataframe" | "num" | "string_list" | "dataframe_list" | "cell" | "column" | "column_list" | "graphics" | "blob" | "tablerowfiltercall" | "colfiltercall" | "bitset" | "dynamic" | "viewer" | "list" | "semantic_value" | "func" | "funccall" | "property" | "categorical" | "numerical" | "GridCellRenderArgs" | "element" | "view" | "TableView" | "User" | "Menu" | "Project" | "event_data" | "progressindicator" | "Credentials" | "ScriptEnvironment" | "Notebook" | undefined | - |
defaultValue | any | null | - |
options | object & IProperty | null | null | - |
Returns
any
See
Registered property gets added to properties. Returns default value, thus allowing to combine registering a property with the initialization
options.get/options.set override how the property reads/writes (instead of the default
fieldName field access); the change notification (onPropertyChanged) always fires
on write, and a {get}-only options yields a custom read with the default fieldName write.
addStatusProvider()
addStatusProvider(
name,provider):void
Defined in: js-api/src/widgets/base.ts:468
Adds live parts, hit areas and readings to this widget's status. Providers run in registration
order on every read; an existing name is replaced in place, and later providers override earlier
entries. Coordinates use the widget's own hit-area system. Detaching the widget removes all
providers. A subclass that overrides getWidgetStatus composes with super.getWidgetStatus().
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | Stable name of the component contributing the status. |
provider | StatusProvider | Computes the contribution each time the status is requested. |
Returns
void
Example
widget.addStatusProvider('selection', () => ({values: {'selected rows': table.selection.trueCount}}));
console.log(widget.getWidgetStatus().values?.['selected rows']);
widget.removeStatusProvider('selection');
see samples/grid/custom-renderer-status
apply()
apply(
properties):Widget
Defined in: js-api/src/widgets/base.ts:267
Sets each key of properties as the property of that name; returns this widget.
Parameters
| Parameter | Type |
|---|---|
properties | object |
Returns
Widget
bindProps()
bindProps():
BindProp[]
Defined in: js-api/src/u2core/component.ts:492
The signal-backed subset of the meta props — what a binding picker offers on a named node — plus, under propertyTier, every declared property. Allocates no signal.
Returns
BindProp[]
Inherited from
bindStep()
bindStep(
name):Signal<unknown> |BindSource|null
Defined in: js-api/src/u2core/component.ts:481
One binding step (DD5): a meta-declared prop's same-named Signal member — a named node is a
bind source, generated off componentMeta the way getProperties is — then, under
propertyTier, a cached signal over the declared property. '' answers the default
binding: the component's own value signal, where one exists.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
Signal<unknown> | BindSource | null
Inherited from
deriveName()
protectedderiveName(x):void
Defined in: js-api/src/u2core/component.ts:109
Sets the introspection/form key without claiming an automation id — the label-fallback path:
a caption is not a stable identity, so it never reaches data-u2-name.
Parameters
| Parameter | Type |
|---|---|
x | string | undefined |
Returns
void
Inherited from
detach()
detach():
void
Defined in: js-api/src/widgets/base.ts:317
Gets called when a widget is detached and will no longer be used. Typically used for unsubscribing from events. Be sure to call super.detach() if this method is overridden.
Returns
void
dispose()
dispose():
void
Defined in: js-api/src/u2core/component.ts:687
Disposes the control; disposed by hand, it also leaves the page — a dead control left on show looks alive. One its owner disposes leaves the DOM to whoever holds it: a region swapping its content, a spec re-rendering.
Returns
void
Inherited from
effect()
effect(
fn):this
Defined in: js-api/src/u2core/component.ts:260
Runs fn now and on every change of the signals it reads, until this component is disposed.
Called while a row of each() or an effect run is being built, it belongs on a control built
there (input.effect(...)) — on a longer-lived one it piles up with every rebuild, and u2 warns.
Parameters
| Parameter | Type |
|---|---|
fn | () => void |
Returns
this
Inherited from
fireEvent()
protectedfireEvent(eventId,args?):void
Defined in: js-api/src/u2core/component.ts:636
Every matching listener runs inside one batch; a throwing one is reported to this component's scope and does not stop the rest.
Parameters
| Parameter | Type |
|---|---|
eventId | string |
args? | unknown |
Returns
void
Inherited from
getDartProperties()
getDartProperties():
any[]
Defined in: js-api/src/widgets/base.ts:296
Dart handles of the properties that have one.
Returns
any[]
getFunctions()
getFunctions():
Func[]
Defined in: js-api/src/widgets/base.ts:289
Functions that are applicable to this particular widget. Used in the UI to display context actions, and for the AI integrations.
Returns
Func[]
Overrides
getItems()
getItems(
_opts?):IItemsState|undefined
Defined in: js-api/src/u2core/component.ts:737
Items of a collection-like control; undefined for other kinds. list holds the first
ITEMS_CAP unless all.
Parameters
| Parameter | Type |
|---|---|
_opts? | { all?: boolean; } |
_opts.all? | boolean |
Returns
IItemsState | undefined
Inherited from
getProperties()
getProperties():
Property[]
Defined in: js-api/src/widgets/base.ts:285
Returns all properties of this widget: the meta-generated ones plus addProperty's.
Returns
Property[]
Overrides
getState()
getState():
IControlState
Defined in: js-api/src/u2core/component.ts:713
The state block generic tests read (DG.U2.state). This base reads the DOM — kind, name,
accessible name, aria-disabled, hidden, focus, aria-busy — plus getItems; a
subclass adds what the DOM cannot say and spreads super.getState(). Synchronous, side-effect
free, never cached.
Returns
Inherited from
getWidgetStatus()
getWidgetStatus():
IWidgetStatus
Defined in: js-api/src/widgets/base.ts:432
Returns the widget's runtime structure for automated testing and introspection; state is read off
the DOM (kind, label, enabled, visible, focused …), then merged with what providers contribute.
Returns
Overrides
link()
link(
name,source,twoWay):void
Defined in: js-api/src/u2core/component.ts:453
Keeps this component's name step and source equal, echo-suppressed by value; the reverse
direction only where twoWay. A component that took source as its own signal needs no link
and gets none; a read-only step cannot follow anything and gets none either.
Parameters
| Parameter | Type |
|---|---|
name | string |
source | Signal<unknown> |
twoWay | boolean |
Returns
void
Inherited from
on()
on(
eventId,handler): () =>void
Defined in: js-api/src/u2core/component.ts:623
Subscribes handler to onEvent(eventId); it gets the payload and this component.
Owned by the ambient scope when there is one (the subscriber's), else by this component; runs
as Scope.bind runs a handler. Answers the unsubscribe.
Parameters
| Parameter | Type |
|---|---|
eventId | string |
handler | (arg, source) => void |
Returns
() => void
Inherited from
onEvent()
onEvent(
eventId?):Observable<any>
Defined in: js-api/src/widgets/base.ts:423
Observes events with the specified eventId: what fireEvent raises and, for an id, the DOM
events of that name on the root — as on every u2 Control.
Parameters
| Parameter | Type | Default value |
|---|---|---|
eventId | string | null | null |
Returns
Observable<any>
Overrides
onFrameAttached()
onFrameAttached(
dataFrame):void
Defined in: js-api/src/widgets/base.ts:304
Called when a DataFrame is attached; override to bind data.
Parameters
| Parameter | Type |
|---|---|
dataFrame | DataFrame |
Returns
void
onPropertyChanged()
onPropertyChanged(
property):void
Defined in: js-api/src/widgets/base.ts:293
Gets called when viewer's property is changed.
Parameters
| Parameter | Type | Description |
|---|---|---|
property | Property | null | or null, if multiple properties were changed. |
Returns
void
own()
own(
dispose):this
Defined in: js-api/src/u2core/component.ts:267
Registers a cleanup that runs when this component is disposed.
Parameters
| Parameter | Type |
|---|---|
dispose | () => void |
Returns
this
Inherited from
propertyChanges()
protectedpropertyChanges():ObservableLike<PropertyChange>
Defined in: js-api/src/widgets/base.ts:375
What refreshes the property tier's cached signals from outside: null where nothing announces a change (one-way).
Returns
ObservableLike<PropertyChange>
Overrides
registerFunction()
protectedregisterFunction(f):void
Defined in: js-api/src/u2core/component.ts:616
Parameters
| Parameter | Type |
|---|---|
f | FuncLike |
Returns
void
Inherited from
removeStatusProvider()
removeStatusProvider(
name):void
Defined in: js-api/src/widgets/base.ts:477
Removes the status contribution registered under name; an absent name is a no-op.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The name passed to addStatusProvider. |
Returns
void
Example
widget.removeStatusProvider('selection');
see samples/grid/custom-renderer-status
revealItem()
revealItem(
keyOrLabel):Promise<HTMLElement|null>
Defined in: js-api/src/u2core/component.ts:746
Brings the item into view and resolves to its element, or null when none matches: the exact
key (data-u2-item) first, then the label, trimmed and case-insensitive. Several label matches
reject, naming the candidates. This base searches the rendered [data-u2-item] elements under
the root and in the popups it owns; a virtual or collapsible control overrides it to scroll or
expand first.
Parameters
| Parameter | Type |
|---|---|
keyOrLabel | string |
Returns
Promise<HTMLElement | null>
Inherited from
runInScope()
runInScope<
T>(fn):T
Defined in: js-api/src/u2core/component.ts:253
Runs fn with this component's scope ambient: what it builds is owned by this component.
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
fn | () => T |
Returns
T
Deprecated
Use the owner verb build(fn) (OwnerVerbs.build): this.build(fn), dialog.build(fn).
Inherited from
sourceRowsChanged()
sourceRowsChanged():
void
Defined in: js-api/src/widgets/base.ts:301
Called when the rows the widget shows change; override to refresh.
Returns
void
sub()
sub(
subscription):void
Defined in: js-api/src/widgets/base.ts:261
Registers a subscription to an external event.
Parameters
| Parameter | Type |
|---|---|
subscription | Subscription |
Returns
void
subscribe()
subscribe<
T>(source,handler): () =>void
Defined in: js-api/src/u2core/component.ts:1040
Subscribes handler to source until this owner is disposed. See Scope.subscribe.
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
source | ObservableLike<T> |
handler | (value) => void |
Returns
() => void
Inherited from
task()
task<
R>(fn,options?):TaskRun
Defined in: js-api/src/u2core/component.ts:1038
Async work owned here. See Scope.task.
Type Parameters
| Type Parameter |
|---|
R |
Parameters
| Parameter | Type |
|---|---|
fn | (t) => R | PromiseLike<R> |
options? | TaskOptions |
Returns
Inherited from
toDart()
toDart():
any
Defined in: js-api/src/widgets/base.ts:254
The Dart handle of this widget, created on first use.
Returns
any
_isPlain()
protectedstatic_isPlain(x):x is Record<string, unknown>
Defined in: js-api/src/u2core/component.ts:244
Parameters
| Parameter | Type |
|---|---|
x | unknown |
Returns
x is Record<string, unknown>
Inherited from
build()
Call Signature
staticbuild(builder,options?):Control
Defined in: js-api/src/u2core/component.ts:943
The function component component makes, under its old name.
Parameters
| Parameter | Type |
|---|---|
builder | (self) => BuiltRoot |
options? | ControlBuildOptions |
Returns
Deprecated
Use component: one spelling, apart from an owner's build(fn).
Inherited from
Call Signature
staticbuild<R>(builder,options?):never
Defined in: js-api/src/u2core/component.ts:944
The function component component makes, under its old name.
Type Parameters
| Type Parameter |
|---|
R extends BuiltHandle |
Parameters
| Parameter | Type |
|---|---|
builder | (self) => R |
options? | ControlBuildOptions |
Returns
never