Skip to main content

Control class

๐Ÿ“– Descriptionโ€‹

The Control class is the base from which UI control classes are derived. It is an abstract class and cannot be instantiated directly.

๐Ÿ“ฆ Derived controlsโ€‹

The following controls are derived from this class and are available in the Forms module:


๐Ÿ†• constructorโ€‹

Creates a new Control instance.

Signatureโ€‹

constructor(properties: IControlProperties): Control

Parametersโ€‹

NameTypeOptionalDescription
propertiesIControlPropertiesNoSpecifies the control properties.

Return valueโ€‹

Returns a reference to the new Control instance.

๐Ÿ—ƒ๏ธ Fieldsโ€‹


๐Ÿท๏ธ featureโ€‹

Retrieves a reference to the feature of the form card.

Typeโ€‹

Feature | undefined


๐Ÿท๏ธ formโ€‹

Sets or retrieves the parent form.

Typeโ€‹

Form | undefined


๐Ÿท๏ธ hasFocusโ€‹

Retrieves if the control has input focus.

Typeโ€‹

boolean


๐Ÿท๏ธ hasLabelโ€‹

Retrieves if a label is set.

Typeโ€‹

boolean


๐Ÿท๏ธ isAwaitingโ€‹

Sets or retrieves if the control validation is awaiting.

Typeโ€‹

boolean


๐Ÿท๏ธ isDisabledโ€‹

Sets or retrieves if the control is disabled.

Typeโ€‹

boolean


๐Ÿท๏ธ isFailedโ€‹

Sets or retrieves if the control validation has failed.

Typeโ€‹

boolean


๐Ÿท๏ธ isFeatureEnabledโ€‹

Retrieves if the control is attached to an enabled feature.

Typeโ€‹

boolean


๐Ÿท๏ธ isFormEnabledโ€‹

Retrieves if the form is enabled.

Typeโ€‹

boolean


๐Ÿท๏ธ isFormReadyโ€‹

Retrieves if the form is ready.

Typeโ€‹

boolean


๐Ÿท๏ธ isFormVisibleโ€‹

Retrieves if the form is visible.

Typeโ€‹

boolean


๐Ÿท๏ธ isFusedโ€‹

Retrieves if the control is fused with the form card. This is only possible with controls which have no separate label and are the one and only control inside of the form.

Typeโ€‹

boolean


๐Ÿท๏ธ isGroupVisibleโ€‹

Retrieves if the form group is visible.

Typeโ€‹

boolean


๐Ÿท๏ธ isHoveredโ€‹

Retrieves if the control is hovered.

Typeโ€‹

boolean


๐Ÿท๏ธ isInteractableโ€‹

Retrieves if the control is interactable.

Typeโ€‹

boolean


๐Ÿท๏ธ isInvalidโ€‹

Sets or retrieves if the control validation is invalid.

Typeโ€‹

boolean


๐Ÿท๏ธ isLockedโ€‹

Sets or retrieves if the control is locked (readonly).

Typeโ€‹

boolean


๐Ÿท๏ธ isObservableโ€‹

Retrieves if the control is observable.

Typeโ€‹

boolean


๐Ÿท๏ธ isPassedโ€‹

Sets or retrieves if the control validation has passed.

Typeโ€‹

boolean


๐Ÿท๏ธ isReadableโ€‹

Specifies it the control value is readable.

Typeโ€‹

boolean


๐Ÿท๏ธ isRequiredโ€‹

Sets or retrieves if the control is required.

Typeโ€‹

boolean


๐Ÿท๏ธ isVisibleโ€‹

Sets or retrieves the visibility of the control.

Typeโ€‹

boolean


๐Ÿท๏ธ modesโ€‹

Retrieves the supported modes for the control.

Typeโ€‹

Mode


๐Ÿท๏ธ styleโ€‹

Retrieves the control style.

Typeโ€‹

Style | undefined


๐Ÿท๏ธ stylesheetโ€‹

Retrieves the stylesheet for the control.

Typeโ€‹

Stylesheet


๐Ÿท๏ธ tabโ€‹

Retrieves the tab index for the control.

Typeโ€‹

number


๐Ÿท๏ธ validationโ€‹

Sets or retrieves the validation state of the control.

Typeโ€‹

"unknown" | "fail" | "invalid" | "pass" | "await"

โ–ถ๏ธ Methodsโ€‹


๐Ÿ”ง autoFocusโ€‹

Enables auto-focus for the control.

Signatureโ€‹

autoFocus(focusAuto?: boolean): this

Parametersโ€‹

NameTypeOptionalDescription
focusAutobooleanYesSpecifies if auto-focus is enabled or not.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง autoValidateโ€‹

Enables automatic control validation.

Signatureโ€‹

autoValidate(
fn: (
control: Control,
sType: "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur",
callback: Callback
) => "unknown" | "fail" | "invalid" | "pass" | "await" | Callback
): this

Parametersโ€‹

NameTypeOptionalDescription
fnSee signatureNoSpecifies the validator function.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง awaitโ€‹

Sets the control validation to waiting.

Signatureโ€‹

await(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง bindโ€‹

Specifies a bind function (invoked when the control is initialized).

Signatureโ€‹

bind(fn: (control: this) => void): this

Parametersโ€‹

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง blurโ€‹

Blurs the focus of the control.

Signatureโ€‹

blur(): void

๐Ÿ”ง compactModeOnlyโ€‹

Sets the control mode to compact only.

Signatureโ€‹

compactModeOnly(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง destroyโ€‹

Destroys the control.

Signatureโ€‹

destroy(): void

๐Ÿ”ง disableโ€‹

Disables the control.

Signatureโ€‹

disable(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง disabledโ€‹

Specifies the state of the control.

Signatureโ€‹

disabled(disabled?: boolean): this

Parametersโ€‹

NameTypeOptionalDescription
disabledbooleanYesSpecifies if the control is disabled (default is true).

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง drawโ€‹

Draws the control.

Signatureโ€‹

draw(parent: Element): void

Parametersโ€‹

NameTypeOptionalDescription
parentElementNoReference to the parent form element.

๐Ÿ”ง enableโ€‹

Enables the control.

Signatureโ€‹

enable(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง executeโ€‹

Specifies a function which is invoked when the control is initialized.

Signatureโ€‹

execute(fn: (control: this) => void): this

Parametersโ€‹

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง failโ€‹

Sets the control validation to failed.

Signatureโ€‹

fail(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง focusโ€‹

Sets the focus to the control.

Signatureโ€‹

focus(to?: "first" | "last"): boolean

Parametersโ€‹

NameTypeOptionalDescription
to"first" | "last"YesSpecifies if the focus should be set to the first or last item in the control (in case a control has multiple items).

Return valueโ€‹

Returns true if the focus is set.


๐Ÿ”ง focusToโ€‹

Sets the focus to the previous or next item in the control. Override this function if you need to shift focus within a control.

Signatureโ€‹

focusTo(to: "previous" | "next"): boolean

Parametersโ€‹

NameTypeOptionalDescription
to"previous" | "next"NoSpecifies if the focus is set to the previous or next control.

Return valueโ€‹

Returns true if the focus is set.


๐Ÿ”ง groupVisibilityโ€‹

Specifies the visibility of the control group.

Signatureโ€‹

groupVisibility(visible: boolean): void

Parametersโ€‹

NameTypeOptionalDescription
visiblebooleanNoSpecifies if the control group is visible.

๐Ÿ”ง hideโ€‹

Hides the control.

Signatureโ€‹

hide(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”’ hoverโ€‹

Sets the hover state.

Signatureโ€‹

hover(hover: boolean): void

Parametersโ€‹

NameTypeOptionalDescription
hoverbooleanNoSpecifies if the hover is active.

๐Ÿ”ง indentโ€‹

Enables control indentation. This can only be set during construction.

Signatureโ€‹

indent(size: number): this

Parametersโ€‹

NameTypeOptionalDescription
sizenumberNoSpecifies the indent size in pixels.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”’ initializedโ€‹

Marks the control as initialized.

Signatureโ€‹

initialized(): void

๐Ÿ”ง invalidโ€‹

Sets the control validation to invalid.

Signatureโ€‹

invalid(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”’ keyboardโ€‹

Attach keyboard events to the control.

Signatureโ€‹

keyboard(
element: Element,
onEnter?: () => boolean,
enterOverride?: boolean,
onKeyPress?: (keyboardEvent: IKeyboardEvent) => boolean
): void

Parametersโ€‹

NameTypeOptionalDescription
elementElementNoReference to the element to bind the events to.
onEnter() => booleanYesSpecifies the function which is invoked when an enter is detected.
enterOverridebooleanYesOverrides the default enter behavior from an element (for example the textarea, default is false).
onKeyPress(keyboardEvent: IKeyboardEvent) => booleanYesInvoked when a key is pressed.

๐Ÿ”ง labelโ€‹

Sets the label for the control.

tip

If you want to use markdown in the label, activate it first using the markdown method.

Signatureโ€‹

label(label: string): this

Parametersโ€‹

NameTypeOptionalDescription
labelstringNoSpecifies the control label.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง labelCompactโ€‹

Sets the compact label for the control.

Signatureโ€‹

labelCompact(label: string): this

Parametersโ€‹

NameTypeOptionalDescription
labelstringNoSpecifies the compact control label.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง lockโ€‹

Locks the control.

Signatureโ€‹

lock(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง lockedโ€‹

Specifies if the control is locked (readonly).

Signatureโ€‹

locked(locked?: boolean): this

Parametersโ€‹

NameTypeOptionalDescription
lockedbooleanYesSpecifies if the control is locked/readonly (default is true).

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง markdownโ€‹

Specifies if the label should support markdown formatting.

Signatureโ€‹

markdown(options?: IMarkdownOptions): this

Parametersโ€‹

NameTypeOptionalDescription
optionsIMarkdownOptionsYesSpecifies the markdown options.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง modeโ€‹

Sets the supported mode for the control.

Signatureโ€‹

mode(mode: "compact" | "normal" | "both"): this

Parametersโ€‹

NameTypeOptionalDescription
mode"compact" | "normal" | "both"NoSpecifies the desired mode.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง normalModeOnlyโ€‹

Sets the control mode to normal only.

Signatureโ€‹

normalModeOnly(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”’ onBlurโ€‹

Invoked when the control loses focus.

Signatureโ€‹

onBlur(): void

๐Ÿ”’ onChangeโ€‹

Invoked when the control changed.

Signatureโ€‹

onChange(
change: "visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"
): void

Parametersโ€‹

NameTypeOptionalDescription
change"visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"NoSpecifies the change that occurred.

๐Ÿ”’ onDisableโ€‹

Invoked when the control is disabled.

Signatureโ€‹

onDisable(): void

๐Ÿ”’ onDrawโ€‹

Abstract method

This method is abstract and needs implementation in the derived control class.

Invoked when the control should be drawn.

Signatureโ€‹

onDraw(parent: Element): Element

Parametersโ€‹

NameTypeOptionalDescription
parentElementNoReference to the parent form element.

Return valueโ€‹

Returns a reference to the control element.


๐Ÿ”’ onEnableโ€‹

Invoked when the control is enabled.

Signatureโ€‹

onEnable(): void

๐Ÿ”’ onEnterโ€‹

Invoked when the enter (return) key is pressed.

Signatureโ€‹

onEnter(element: Element): boolean

Parametersโ€‹

NameTypeOptionalDescription
elementElementNoReference to the element.

Return valueโ€‹

Return true if you want to cancel key bubbling.


๐Ÿ”’ onEscapeโ€‹

Invoked when the escape key is pressed.

Signatureโ€‹

onEscape(element: Element): boolean

Parametersโ€‹

NameTypeOptionalDescription
elementElementNoReference to the element.

Return valueโ€‹

Return true if you want to cancel key bubbling.


๐Ÿ”’ onExecuteโ€‹

Invoked when the control is executed.

Signatureโ€‹

onExecute(): void

๐Ÿ”’ onFocusโ€‹

Invoked when the control captures focus.

Signatureโ€‹

onFocus(autoFocus: boolean): void

Parametersโ€‹

NameTypeOptionalDescription
autoFocusbooleanNoSpecifies if an auto-focus was active.

๐Ÿ”’ onFocusOptionsโ€‹

Invoked when the focus state of the control is changed.

Signatureโ€‹

onFocusOptions(): void

๐Ÿ”ง onFormActivateโ€‹

Invoked when the control form is activated.

Signatureโ€‹

onFormActivate(): void

๐Ÿ”ง onFormDeactivateโ€‹

Invoked when the control form is deactivated.

Signatureโ€‹

onFormDeactivate(): void

๐Ÿ”ง onFormDisableโ€‹

Invoked when the control form is disabled.

Signatureโ€‹

onFormDisable(): void

๐Ÿ”ง onFormEnableโ€‹

Invoked when the control form is enabled.

Signatureโ€‹

onFormEnable(): void

๐Ÿ”ง onFormResizeโ€‹

Invoked when the parent form is resized.

Signatureโ€‹

onFormResize(): void

๐Ÿ”ง onHideโ€‹

Invoked when the control is hidden.

Signatureโ€‹

onHide(): void

๐Ÿ”’ onHoverโ€‹

Invoked when the control is hovered.

Signatureโ€‹

onHover(): void

๐Ÿ”ง onInitโ€‹

Invoked when the control is initialized.

Signatureโ€‹

onInit(): boolean

Return valueโ€‹

Return true if the control is initialized.


๐Ÿ”’ onLockโ€‹

Invoked when the control is locked.

Signatureโ€‹

onLock(): void

๐Ÿ”ง onMeasureโ€‹

Invoked when the control is measured. A measure correction in pixels can be supplied in the return value.

Signatureโ€‹

onMeasure(): number

Return valueโ€‹

Returns the measure correction for the control.


๐Ÿ”ง onModeโ€‹

Invoked when the control mode is changed.

Signatureโ€‹

onMode(): void

๐Ÿ”’ onOptionalโ€‹

Invoked when the control is optional.

Signatureโ€‹

onOptional(): void

๐Ÿ”ง onRequestAutoFocusโ€‹

Fired when auto-focus is requested.

Signatureโ€‹

onRequestAutoFocus(): boolean

Return valueโ€‹

Returns true if the focus is set.


๐Ÿ”’ onRequireโ€‹

Invoked when the control is required.

Signatureโ€‹

onRequire(): void

๐Ÿ”ง onResizedโ€‹

Invoked when the control is resized.

Signatureโ€‹

onResized(): void

๐Ÿ”ง onShowโ€‹

Invoked when the control is shown.

Signatureโ€‹

onShow(): void

๐Ÿ”’ onUnlockโ€‹

Invoked when the control is unlocked.

Signatureโ€‹

onUnlock(): void

๐Ÿ”’ onUpdateโ€‹

Invoked when the control needs to be updated.

Signatureโ€‹

onUpdate(): void

๐Ÿ”’ onValidateโ€‹

Invoked when the control validation state is changed.

Signatureโ€‹

onValidate(): void

๐Ÿ”ง passโ€‹

Sets the control validation to passed.

Signatureโ€‹

pass(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง readonlyโ€‹

Makes the control readonly.

Signatureโ€‹

readonly(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง redrawโ€‹

Redraws a control.

Signatureโ€‹

redraw(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง referenceโ€‹

Sets the control reference.

tip

This can be used in combination with the controlWithReference method of the Form class to retrieve a control from a form (in case you didn't assign the control instance to a variable).

Signatureโ€‹

reference(reference: string): this

Parametersโ€‹

NameTypeOptionalDescription
referencestringNoSpecifies the reference.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง requireโ€‹

Makes the control required.

Signatureโ€‹

require(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง requiredโ€‹

Specifies if the control is required.

Signatureโ€‹

required(required?: boolean): this

Parametersโ€‹

NameTypeOptionalDescription
requiredbooleanYesSpecifies if the control is required (default is true).

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง resizeโ€‹

Resizes the parent form.

Signatureโ€‹

resize(): void

๐Ÿ”ง showโ€‹

Shows the control.

Signatureโ€‹

show(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง unbindโ€‹

Specifies an unbind function (invoked when the control is destroyed).

Signatureโ€‹

unbind(fn: (control: this) => void): this

Parametersโ€‹

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง unlockโ€‹

Unlocks the control.

Signatureโ€‹

unlock(): this

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”’ updateControlโ€‹

Updates the control state.

Signatureโ€‹

updateControl(
change: "visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation",
): void
NameTypeOptionalDescription
change"visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"NoSpecifies what is changed.

๐Ÿ”’ updateFocusโ€‹

Updates the focus state of a control.

Signatureโ€‹

updateFocus(
hover: boolean,
autoBlur: boolean,
virtualElement?: Element,
physicalElement?: Element
): void

Parametersโ€‹

NameTypeOptionalDescription
hoverbooleanNoSpecifies if the control has captured focus.
autoBlurbooleanNoSpecifies if the auto-blur should be used.
virtualElementElementYesSpecifies the virtual focus subject (the element that renders the visual focus indication).
physicalElementElementYesSpecifies the physical focus subject (the element that actually gets the focus, for example, a text input field).

๐Ÿ”ง validateโ€‹

Sets the validation state of the control or invokes a validation cycle if automatic validation is activated.

Signatureโ€‹

validate(
validation?: "unknown" | "fail" | "invalid" | "pass" | "await" | "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur"
): this

Parametersโ€‹

NameTypeOptionalDescription
validation"unknown" | "fail" | "invalid" | "pass" | "await" | "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur"YesSpecifies the validation state.

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.


๐Ÿ”ง visibleโ€‹

Specifies the visibility of the control.

Signatureโ€‹

visible(visible?: boolean): this

Parametersโ€‹

NameTypeOptionalDescription
visiblebooleanYesSpecifies if the control is visible (default is true).

Return valueโ€‹

Returns a reference to the Control instance to allow chaining.

โ›“๏ธ Interfacesโ€‹


๐Ÿ”— IControlPropertiesโ€‹

Describes the interface for the control properties.

Type declarationโ€‹

interface IControlProperties {
/* Specifies the control style. */
style?: IControlStyle;

/* Specifies the index name for the control styles in the form style object. */
styleName?: string;

/* Specifies the default control style. */
styleDefault?: Style;

/* Label for the control. */
label?: string;
}