Component

Components are the building blocks of a Typescene application.

class Component

extends ManagedObject

Component base class. Represents a managed object (see ManagedObject) that can be initialized from a ‘preset’ structure passed to its static with method.

Component property values may be bound (see bind) to properties of a ‘composite’ parent, i.e. the component that references sub components through a property decorated with the @compose decorator.

Note: For a better understanding of how components are used in Typescene applications, read this guide.

Constructor

(): Component

.with() static

[1]. <TComponentCtor extends ComponentConstructor<Component>>(this: ComponentCtorWithPreset<TComponentCtor>, ...rest: ComponentPresetRestType<TComponentCtor>): TComponentCtor
[2]. <TComponentCtor extends ComponentConstructor<Component>>(this: ComponentCtorWithPreset<TComponentCtor>, presets: new () => any, ...rest: ComponentPresetRestType<TComponentCtor>): "INVALID_PRESET_ARGUMENT"
[3]. <TComponentCtor extends ComponentConstructor<Component>>(this: ComponentCtorWithPreset<TComponentCtor>, presets: ComponentPresetArgType<TComponentCtor>, ...rest: ComponentPresetRestType<TComponentCtor>): TComponentCtor

Create a new component constructor, for which instances are automatically updated with given properties, bindings, event handlers, and other values.

  • When an instance is activated, components included as preset properties are instantiated and assigned to properties with the same name as the preset object property.

  • When an instance becomes a (nested) child component of an active composite object (or upon activation of such an object), bindings are activated to reflect values from the composite object.

  • Event handlers are added on all instances of the component class, using one of the following patterns:

    • { ... onEventName: "methodName()" } to invoke given method directly on the first composite object that defines a method with this name, whenever an event with given name is emitted, passing the event as the first and only argument, or

    • { ... onEventName: "+OtherEvent" } to emit another event with given name. The event is created and emitted using the Component.propagateComponentEvent method.

  • Upon initialization of each instance, the update method is called with the remaining properties in the intializer argument, and all rest arguments (component classes) of the same type as the arguments to this method.

.preset() static

(presets: object, ...rest: unknown[]): Function

Add bindings, components, and event handlers from given presets to the current component constructor. This method is called by Component.with with the same arguments.

Component classes may override this method and return the result of super.preset(...) if:

  • the .with() function for a component class should accept custom type(s) for its arguments. The parameter signature for the preset method is used to determine the parameter signature for .with() on a component class.

  • component instances should be prepared in any way other than setting property values, adding bindings, or event handlers immediately after being constructed (using the returned callback).

Returns: A function (must be typed as Function even in derived classes) that is called by the constructor for each new instance, to apply remaining values from the preset object to the component object that is passed through this.

.presetBinding() static

<TComponent extends Component>(this: ComponentConstructor<TComponent>, propertyName: string, binding: Binding, applyBoundValue?: (this: TComponent, boundValue: any) => any): void

Add given binding to this component constructor, so that the property with given name on all instances will be updated with value(s) taken from the parent composite object. Optionally given function is used to set the property value using the updated (bound) value; otherwise, values are copied directly except for arrays, which are used to replace the values in a managed list (see ManagedList.replace).

Note: This method is used by preset when the argument to .with() includes a binding (see bind). This method should not be used directly unless passing a binding to .with() is not possible.

.presetBindingsFrom() static

(...constructors: ComponentConstructor<Component>[]): void

Inherit bindings from given component constructor(s) on this constructor. Inherited bindings will be bound to the same parent composite object as bindings passed to .with() directly, to update bound properties of (nested) child instances.

Note: This method must be used by a custom preset function if the preset component (may) have managed child objects (see @managedChild) of the given type and the constructor is not passed to super.preset(...).

.presetActiveComponent() static

(propertyName: string, constructor: ComponentConstructor<Component> & (new () => Component), ...include: ComponentConstructor<Component>[]): Composition

Add a sub component to this component; see compose.

Given property must already be decorated with the @managedChild decorator. This method is intended for use by Component.preset.

.isPresetComponent() protected

(): boolean

Returns true if the class that this instance has been created from was itself created using Component.with somewhere along the prototype chain.

.getParentComponent()

[1]. (): Component
[2]. <TParent extends Component>(ParentClass: ComponentConstructor<TParent>): TParent

[1] Returns the current parent component. See @managedChild decorator.

[2] Returns the current parent component. See @managedChild decorator.

.getCompositeParent()

<TParent extends Component>(ParentClass?: ComponentConstructor<TParent>): TParent

Returns the parent component that contains the @compose property which references this component (or the parent’s parent if this component’s parent is referenced by a @compose property instead, and so on).

If there is no component that (indirectly) references this component through a @compose property, this method returns undefined.

.propagateComponentEvent()

(name: string, inner?: ManagedEvent): void

Create and emit an event with given name, a reference to this component, and an optional inner (propagated) event. The base implementation emits a plain ComponentEvent, but this method may be overridden to emit other events.

Note: This method is used by classes created using Component.with if an event handler is specified using the { ... onEventName: "+OtherEvent" } pattern.

.managedId

number

Inherited from ManagedObject.managedId.

.managedState

ManagedState

Inherited from ManagedObject.managedState.

.getReferenceCount() protected

(): number

Inherited from ManagedObject.getReferenceCount.

.getManagedReferrers() protected

(): ManagedObject[]

Inherited from ManagedObject.getManagedReferrers.

.getManagedParent() protected

[1]. (): ManagedObject
[2]. <TParent extends ManagedObject>(ParentClass: ManagedObjectConstructor<TParent>): TParent

Inherited from ManagedObject.getManagedParent.

.emit()

<TEvent extends ManagedEvent = ManagedEvent, TConstructorArgs extends any[] = any[]>(e: string | TEvent | (new (...args: TConstructorArgs) => TEvent), ...constructorArgs: TConstructorArgs): this

Inherited from ManagedObject.emit.

.propagateChildEvents() protected

[1]. (f?: (this: this, e: ManagedEvent, propertyName: string) => void | ManagedEvent | ManagedEvent[]): this
[2]. (...types: (ManagedEvent | (new (...args: any[]) => ManagedEvent))[]): this

Inherited from ManagedObject.propagateChildEvents.

.activateManagedAsync() protected

(): Promise<any>

Inherited from ManagedObject.activateManagedAsync.

.deactivateManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.deactivateManagedAsync.

.destroyManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.destroyManagedAsync.

.onManagedStateActivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActivatingAsync.

.onManagedStateActiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActiveAsync.

.onManagedStateDeactivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDeactivatingAsync.

.onManagedStateInactiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateInactiveAsync.

.onManagedStateDestroyingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDestroyingAsync.


Component.Composition

Represents the relationship between a composite parent component class and the active component class.

Constructor

(Composite: typeof Component, propertyName: string, ActiveComponent: ComponentConstructor<Component> & (new () => Component), ...include: ComponentConstructor<Component>[]): Composition

.getBindings()

(): Binding[]

Returns a list of all bindings that should be bound to the composite parent.

.limitBindings()

(...propertyNames: string[]): void

Remove all bindings that are to be bound to properties that are not included in the list of parameters; this causes any of those bindings on instances of the active component and its child component to be bound to the parent composite component instead.