@babylonjs/gui 7.12.0 → 7.13.1

package/2D/controls/control.d.ts

@@ -12,15 +12,17 @@ import type { Style } from "../style";
 import { Matrix2D, Vector2WithInfo } from "../math2D";
 import type { ICanvasGradient, ICanvasRenderingContext } from "@babylonjs/core/Engines/ICanvas.js";
 import type { IAccessibilityTag } from "@babylonjs/core/IAccessibilityTag.js";
+import type { IKeyboardEvent } from "@babylonjs/core/Events/deviceInputEvents.js";
 import type { IAnimatable } from "@babylonjs/core/Animations/animatable.interface.js";
 import type { Animation } from "@babylonjs/core/Animations/animation.js";
 import type { BaseGradient } from "./gradient/BaseGradient";
 import type { AbstractEngine } from "@babylonjs/core/Engines/abstractEngine.js";
+import type { IFocusableControl } from "./focusableControl";
 /**
  * Root class used for all 2D controls
  * @see https://doc.babylonjs.com/features/featuresDeepDive/gui/gui#controls
  */
-export declare class Control implements IAnimatable {
+export declare class Control implements IAnimatable, IFocusableControl {
     /** defines the name of the control */
     name?: string | undefined;
     /**
@@ -242,6 +244,10 @@ export declare class Control implements IAnimatable {
      * An event triggered when a control is clicked on
      */
     onPointerClickObservable: Observable<Vector2WithInfo>;
+    /**
+     * An event triggered when a control receives an ENTER key down event
+     */
+    onEnterPressedObservable: Observable<Control>;
     /**
      * An event triggered when pointer enters the control
      */
@@ -562,6 +568,52 @@ export declare class Control implements IAnimatable {
      * Array of animations
      */
     animations: Nullable<Animation[]>;
+    protected _focusedColor: Nullable<string>;
+    /**
+     * Border color when control is focused
+     * When not defined the ADT color will be used. If no ADT color is defined, focused state won't have any border
+     */
+    get focusedColor(): Nullable<string>;
+    set focusedColor(value: Nullable<string>);
+    /**
+     * The tab index of this control. -1 indicates this control is not part of the tab navigation.
+     * A positive value indicates the order of the control in the tab navigation.
+     * A value of 0 indicated the control will be focused after all controls with a positive index.
+     * More than one control can have the same tab index and the navigation would then go through all controls with the same value in an order defined by the layout or the hierarchy.
+     * The value can be changed at any time.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
+     */
+    tabIndex: number;
+    protected _isFocused: boolean;
+    protected _unfocusedColor: Nullable<string>;
+    /** Observable raised when the control gets the focus */
+    onFocusObservable: Observable<Control>;
+    /** Observable raised when the control loses the focus */
+    onBlurObservable: Observable<Control>;
+    /** Observable raised when a key event was processed */
+    onKeyboardEventProcessedObservable: Observable<IKeyboardEvent>;
+    /** @internal */
+    onBlur(): void;
+    /** @internal */
+    onFocus(): void;
+    /**
+     * Function called to get the list of controls that should not steal the focus from this control
+     * @returns an array of controls
+     */
+    keepsFocusWith(): Nullable<Control[]>;
+    /**
+     * Function to focus a button programmatically
+     */
+    focus(): void;
+    /**
+     * Function to unfocus a button programmatically
+     */
+    blur(): void;
+    /**
+     * Handles the keyboard event
+     * @param evt Defines the KeyboardEvent
+     */
+    processKeyboard(evt: IKeyboardEvent): void;
     /**
      * Creates a new control
      * @param name defines the name of the control

package/2D/controls/control.js

@@ -826,6 +826,67 @@ export class Control {
         this._disabledColorItem = value;
         this._markAsDirty();
     }
+    /**
+     * Border color when control is focused
+     * When not defined the ADT color will be used. If no ADT color is defined, focused state won't have any border
+     */
+    get focusedColor() {
+        return this._focusedColor;
+    }
+    set focusedColor(value) {
+        this._focusedColor = value;
+    }
+    /** @internal */
+    onBlur() {
+        if (this._isFocused) {
+            this._isFocused = false;
+            if (this.focusedColor && this._unfocusedColor != null) {
+                // Set color back to saved unfocused color
+                this.color = this._unfocusedColor;
+            }
+            this.onBlurObservable.notifyObservers(this);
+        }
+    }
+    /** @internal */
+    onFocus() {
+        this._isFocused = true;
+        if (this.focusedColor) {
+            // Save the unfocused color
+            this._unfocusedColor = this.color;
+            this.color = this.focusedColor;
+        }
+        this.onFocusObservable.notifyObservers(this);
+    }
+    /**
+     * Function called to get the list of controls that should not steal the focus from this control
+     * @returns an array of controls
+     */
+    keepsFocusWith() {
+        return null;
+    }
+    /**
+     * Function to focus a button programmatically
+     */
+    focus() {
+        this._host.moveFocusToControl(this);
+    }
+    /**
+     * Function to unfocus a button programmatically
+     */
+    blur() {
+        this._host.focusedControl = null;
+    }
+    /**
+     * Handles the keyboard event
+     * @param evt Defines the KeyboardEvent
+     */
+    processKeyboard(evt) {
+        // if enter, trigger the new observable
+        if (evt.key === "Enter") {
+            this.onEnterPressedObservable.notifyObservers(this);
+        }
+        this.onKeyboardEventProcessedObservable.notifyObservers(evt, -1, this);
+    }
     // Functions
     /**
      * Creates a new control
@@ -978,6 +1039,10 @@ export class Control {
          * An event triggered when a control is clicked on
          */
         this.onPointerClickObservable = new Observable();
+        /**
+         * An event triggered when a control receives an ENTER key down event
+         */
+        this.onEnterPressedObservable = new Observable();
         /**
          * An event triggered when pointer enters the control
          */
@@ -1012,6 +1077,25 @@ export class Control {
          * Array of animations
          */
         this.animations = null;
+        // Focus functionality
+        this._focusedColor = null;
+        /**
+         * The tab index of this control. -1 indicates this control is not part of the tab navigation.
+         * A positive value indicates the order of the control in the tab navigation.
+         * A value of 0 indicated the control will be focused after all controls with a positive index.
+         * More than one control can have the same tab index and the navigation would then go through all controls with the same value in an order defined by the layout or the hierarchy.
+         * The value can be changed at any time.
+         * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
+         */
+        this.tabIndex = -1;
+        this._isFocused = false;
+        this._unfocusedColor = null;
+        /** Observable raised when the control gets the focus */
+        this.onFocusObservable = new Observable();
+        /** Observable raised when the control loses the focus */
+        this.onBlurObservable = new Observable();
+        /** Observable raised when a key event was processed */
+        this.onKeyboardEventProcessedObservable = new Observable();
         this._tmpMeasureA = new Measure(0, 0, 0, 0);
     }
     /** @internal */
@@ -2064,6 +2148,10 @@ export class Control {
         this.onPointerUpObservable.clear();
         this.onPointerClickObservable.clear();
         this.onWheelObservable.clear();
+        // focus
+        this.onBlurObservable.clear();
+        this.onFocusObservable.clear();
+        this.onKeyboardEventProcessedObservable.clear();
         if (this._styleObserver && this._style) {
             this._style.onChangedObservable.remove(this._styleObserver);
             this._styleObserver = null;