@m2c2kit/addons 0.3.15 → 0.3.16

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import * as _m2c2kit_core from '@m2c2kit/core';
+import { CompositeOptions, Size, RgbaColor, M2Node, Composite, TextOptions, IText, StringInterpolationMap, M2NodeEvent, CallbackOptions, Point, ShapeOptions, CompositeEvent, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene, SceneOptions } from '@m2c2kit/core';
 import { Canvas } from 'canvaskit-wasm';
-import { CompositeOptions, Size, RgbaColor, Composite, M2Node, GlobalVariables, TextOptions, IText, StringInterpolationMap, M2NodeEvent, CallbackOptions, Point, ShapeOptions, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene, SceneOptions } from '@m2c2kit/core';
 
 interface GridOptions extends CompositeOptions {
     /** Number of rows in the grid. Must be 1 or greater */
@@ -8,7 +9,7 @@ interface GridOptions extends CompositeOptions {
     columns: number;
     /** Size of the grid in pixels */
     size: Size;
-    /** Background color of the grid. Default is a transparent gray */
+    /** Background color of the grid. Default is a transparent blue */
     backgroundColor?: RgbaColor;
     /** Width of the grid lines. Default is 1 */
     gridLineWidth?: number;
@@ -20,16 +21,17 @@ interface GridChild {
     row: number;
     column: number;
 }
-declare class Grid extends Composite {
+declare class Grid extends Composite implements GridOptions {
     compositeType: string;
-    rows: number;
-    columns: number;
-    gridBackgroundColor: RgbaColor;
-    gridLineColor: RgbaColor;
-    gridLineWidth: number;
+    private _rows;
+    private _columns;
+    private _gridBackgroundColor;
+    private _gridLineColor;
+    private _gridLineWidth;
     cellWidth: number;
     cellHeight: number;
-    gridChildren: GridChild[];
+    private _gridChildren;
+    private cellContainers;
     private _gridBackground?;
     /**
      * A rectangular grid that supports placement of nodes within the grid's
@@ -42,9 +44,44 @@ declare class Grid extends Composite {
      * @param options - {@link GridOptions}
      */
     constructor(options: GridOptions);
+    get completeNodeOptions(): {
+        rows: number;
+        columns: number;
+        size: Size;
+        backgroundColor: RgbaColor;
+        gridLineWidth: number;
+        gridLineColor: RgbaColor;
+        anchorPoint?: _m2c2kit_core.Point;
+        zPosition?: number;
+        name?: string;
+        position?: _m2c2kit_core.Point;
+        scale?: number;
+        alpha?: number;
+        zRotation?: number;
+        isUserInteractionEnabled?: boolean;
+        draggable?: boolean;
+        hidden?: boolean;
+        layout?: _m2c2kit_core.Layout;
+        uuid?: string;
+        suppressEvents?: boolean;
+    };
     initialize(): void;
     private get gridBackground();
     private set gridBackground(value);
+    /**
+     * note: below we do not have getter and setter for size because the getter
+     * and setter in M2Node will handle it.
+     */
+    get rows(): number;
+    set rows(rows: number);
+    get columns(): number;
+    set columns(columns: number);
+    get gridBackgroundColor(): RgbaColor;
+    set gridBackgroundColor(backgroundColor: RgbaColor);
+    get gridLineWidth(): number;
+    set gridLineWidth(gridLineWidth: number);
+    get gridLineColor(): RgbaColor;
+    set gridLineColor(gridLineColor: RgbaColor);
     dispose(): void;
     /**
      * Duplicates a node using deep copy.
@@ -61,11 +98,23 @@ declare class Grid extends Composite {
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
     /**
-     * Removes all children from the grid, but retains grid lines.
+     * The child nodes that have been added to the grid.
+     *
+     * @remarks Do not set this property directly. Use the methods for adding
+     * and removing grid children, such as `addAtCell()`, `removeAllAtCell()`,
+     * `removeGridChild()`, and `removeAllGridChildren()`.
+     */
+    get gridChildren(): Array<GridChild>;
+    set gridChildren(gridChildren: Array<GridChild>);
+    /**
+     * Removes all grid children from the grid.
+     *
+     * @remarks This retains grid lines and grid appearance.
      */
-    removeAllChildren(): void;
+    removeAllGridChildren(): void;
     /**
-     * Adds a node to the grid at the specified row and column position.
+     * Adds a node as a grid child to the grid at the specified row and column
+     * position.
      *
      * @param node - node to add to the grid
      * @param row  - row position within grid to add node; zero-based indexing
@@ -73,46 +122,44 @@ declare class Grid extends Composite {
      */
     addAtCell(node: M2Node, row: number, column: number): void;
     /**
-     * Removes all child nodes at the specified row and column position.
+     * Removes all grid child nodes at the specified row and column position.
      *
-     * @param row - row position within grid at which to remove children; zero-based indexing
-     * @param column - column position within grid at which to remove children; zero-based indexing
+     * @param row - row position within grid at which to remove grid children; zero-based indexing
+     * @param column - column position within grid at which to remove grid children; zero-based indexing
      */
     removeAllAtCell(row: number, column: number): void;
     /**
-     * Removes the child node from the grid.
+     * Removes the grid child node from the grid.
      *
      * @param node - node to remove
      */
-    removeChild(node: M2Node): void;
-}
-
-declare global {
-    var Globals: GlobalVariables;
+    removeGridChild(node: M2Node): void;
+    addChild(child: M2Node): void;
+    removeAllChildren(): void;
+    removeChild(child: M2Node): void;
+    removeChildren(children: M2Node[]): void;
 }
-//# sourceMappingURL=Globals.d.ts.map
 
 interface ButtonOptions extends CompositeOptions, TextOptions {
-    /** Size of button */
+    /** Size of button. Default is 200 wide by 50 high. */
     size?: Size;
-    /** Corner radius of button; can be used to make rounded corners */
+    /** Corner radius of button; can be used to make rounded corners. Default is 9 */
     cornerRadius?: number;
-    /** Background color of button. Default is WebColors.RoyalBlue */
+    /** Background color of button. Default is WebColors.Black */
     backgroundColor?: RgbaColor;
     /** Color of button text. Default is WebColors.White */
     fontColor?: RgbaColor;
     /** Names of multiple fonts to use for text. For example, if a text font and an emoji font are to be used together. Must have been previously loaded */
     fontNames?: Array<string>;
+    /** Size of button text. Default is 20. */
+    fontSize?: number;
 }
-declare class Button extends Composite implements IText {
+declare class Button extends Composite implements IText, ButtonOptions {
     compositeType: string;
+    isText: boolean;
     private _backgroundColor;
-    size: {
-        width: number;
-        height: number;
-    };
-    cornerRadius: number;
-    fontSize: number;
+    private _cornerRadius;
+    private _fontSize;
     private _text;
     private _fontColor;
     private _fontName;
@@ -130,6 +177,31 @@ declare class Button extends Composite implements IText {
      * @param options - {@link ButtonOptions}
      */
     constructor(options: ButtonOptions);
+    get completeNodeOptions(): {
+        size: Size;
+        cornerRadius: number;
+        backgroundColor: RgbaColor;
+        fontNames: string[] | undefined;
+        text?: string;
+        fontName?: string;
+        fontColor?: RgbaColor;
+        fontSize?: number;
+        interpolation?: StringInterpolationMap;
+        localize?: boolean;
+        anchorPoint?: _m2c2kit_core.Point;
+        zPosition?: number;
+        name?: string;
+        position?: _m2c2kit_core.Point;
+        scale?: number;
+        alpha?: number;
+        zRotation?: number;
+        isUserInteractionEnabled?: boolean;
+        draggable?: boolean;
+        hidden?: boolean;
+        layout?: _m2c2kit_core.Layout;
+        uuid?: string;
+        suppressEvents?: boolean;
+    };
     initialize(): void;
     dispose(): void;
     get text(): string;
@@ -142,6 +214,10 @@ declare class Button extends Composite implements IText {
     set fontName(fontName: string | undefined);
     get fontNames(): Array<string> | undefined;
     set fontNames(fontNames: Array<string> | undefined);
+    get cornerRadius(): number;
+    set cornerRadius(cornerRadius: number);
+    get fontSize(): number;
+    set fontSize(fontSize: number);
     get interpolation(): StringInterpolationMap;
     set interpolation(interpolation: StringInterpolationMap);
     get localize(): boolean;
@@ -194,8 +270,6 @@ declare class Dialog extends Composite {
     contentText: string;
     positiveButtonText: string;
     negativeButtonText: string;
-    zPosition: number;
-    hidden: boolean;
     private _fontColor;
     private backgroundPaint?;
     constructor(options?: DialogOptions);
@@ -206,6 +280,8 @@ declare class Dialog extends Composite {
     set backgroundColor(backgroundColor: RgbaColor);
     get fontColor(): RgbaColor;
     set fontColor(fontColor: RgbaColor);
+    get hidden(): boolean;
+    set hidden(hidden: boolean);
     /**
      * Duplicates a node using deep copy.
      *
@@ -310,6 +386,7 @@ declare class DrawPad extends Composite {
     private isDrawingPointerDown;
     private pointerIsDownAndPointerLeftDrawAreaWhenDown;
     private currentStrokesNotAllowed;
+    private originalOptions;
     /** Array of strokes created on the DrawPad, with position and timestamps
      * of all interactions with each DrawPadStroke.
      */
@@ -323,6 +400,39 @@ declare class DrawPad extends Composite {
      * @param options - {@link DrawPadOptions}
      */
     constructor(options: DrawPadOptions);
+    get completeNodeOptions(): {
+        /** Size of the DrawPad */
+        size: Size;
+        /** Color of drawn lines. Default is red. */
+        lineColor?: RgbaColor;
+        /** Width of drawn lines. Default is 1 */
+        lineWidth?: number;
+        /** Background color of the DrawPad. Default is transparent. */
+        backgroundColor?: RgbaColor;
+        /** Width of the border. Default is 1 */
+        borderWidth?: number;
+        /** Color of the border. Default is black */
+        borderColor?: RgbaColor;
+        isUserInteractionEnabled?: boolean;
+        /** Should drawing resume when the pointer, in a down state, returns to the DrawPad area after exiting it while drawing? Default is false. */
+        resumeDrawingOnReturn?: boolean;
+        /** Should the user be permitted to draw only one continuous line? If so, no more drawing is allowed after the first stroke ends. */
+        continuousDrawingOnly?: boolean;
+        /** If `continuousDrawingOnly`, this is the maximum pixel distance from the last stroke's end point that the user is allowed to continue drawing with a new stroke. */
+        continuousDrawingOnlyExceptionDistance?: number;
+        name?: string;
+        position?: Point;
+        scale?: number;
+        alpha?: number;
+        zRotation?: number;
+        draggable?: boolean;
+        hidden?: boolean;
+        layout?: _m2c2kit_core.Layout;
+        uuid?: string;
+        suppressEvents?: boolean;
+        anchorPoint?: Point;
+        zPosition?: number;
+    };
     initialize(): void;
     private initializeDrawShape;
     private initializeDrawArea;
@@ -416,6 +526,12 @@ declare class DrawPad extends Composite {
     duplicate(newName?: string): DrawPad;
 }
 
+/**
+ * Additional, optional properties for a key in the `VirtualKeyboard`.
+ *
+ * @remarks This is used to define special keys (e.g., Shift, Backspace),
+ * keys with icons, and keys of custom size.
+ */
 interface KeyConfiguration {
     /** Width of the key in units of a regular key width. Default is 1. */
     widthRatio?: number;
@@ -434,7 +550,21 @@ interface KeyConfiguration {
     /** ShapeOptions of the optional icon to show on the key. */
     keyIconShapeOptions?: ShapeOptions;
 }
-type VirtualKeyboardRow = Array<KeyConfiguration | string | Array<string>>;
+/**
+ * A row in the `VirtualKeyboard`.
+ *
+ * @remarks Each row is an array of objects that defines a key, where each
+ * object can be one of the following:
+ * -  a string, e.g., `a`. The string is the key in the keyboard's unshifted
+ * state (`a`), and the string's value after applying `toUpperCase()` is the key
+ * in the keyboard's shifted state (`A`).
+ * - an array of two strings, e.g., `["1", "!"]`. The first string is the key
+ * in the keyboard's unshifted state (`1`), and the second string is the key
+ * in the keyboard's shifted state (`!`).
+ * - A `KeyConfiguration` object, which can be used to further customize the
+ * key's appearance and behavior.
+ */
+type VirtualKeyboardRow = Array<string | Array<string> | KeyConfiguration>;
 interface VirtualKeyboardOptions extends CompositeOptions {
     size: Size;
     /** Percent of the keyboard width that should be used for padding on the left and right sides. Default is .02 */
@@ -468,7 +598,11 @@ interface VirtualKeyboardOptions extends CompositeOptions {
     /** If true, a preview of the key that will be pressed will be shown. */
     showKeyDownPreview?: boolean;
 }
-interface VirtualKeyboardEvent extends M2NodeEvent {
+interface VirtualKeyboardEvent extends CompositeEvent {
+    type: "Composite";
+    compositeType: "VirtualKeyboard";
+    compositeEventType: "VirtualKeyboardKeyUp" | "VirtualKeyboardKeyDown" | "VirtualKeyboardKeyLeave";
+    target: VirtualKeyboard | string;
     /** String that is generated when key is pressed, with any modifiers (e.g., Shift) applied. */
     key: string;
     /** Code for the key, not taking into account any modifiers. */
@@ -487,12 +621,12 @@ interface KeyTapMetadata {
     buttons: number;
 }
 declare class VirtualKeyboard extends Composite {
-    compositeType: string;
+    readonly compositeType = "VirtualKeyboard";
     private keyboardHorizontalPaddingPercent;
     private keyboardVerticalPaddingPercent;
     private keyHorizontalPaddingPercent;
     private keyVerticalPaddingPercent;
-    private rowsConfiguration;
+    private keyboardRows;
     private keysPerRow;
     private fontSize;
     private fontNames;
@@ -503,16 +637,64 @@ declare class VirtualKeyboard extends Composite {
     private specialKeyDownColor;
     private backgroundColor;
     private showKeyDownPreview;
+    private originalOptions;
     private shiftActivated;
-    private shiftKeyShape;
     private keyShapes;
-    _isUserInteractionEnabled: boolean;
+    private keyLabels;
+    private letterCircle?;
+    private letterCircleLabel?;
     /**
      * An on-screen keyboard that can be used to enter text.
      *
      * @param options - {@link VirtualKeyboardOptions}
      */
     constructor(options: VirtualKeyboardOptions);
+    get completeNodeOptions(): {
+        size: Size;
+        /** Percent of the keyboard width that should be used for padding on the left and right sides. Default is .02 */
+        keyboardHorizontalPaddingPercent?: number;
+        /** Percent of the keyboard height that should be used for padding on the top and bottom sides. Default is .025 */
+        keyboardVerticalPaddingPercent?: number;
+        /** Percent of each key's width that should be used for padding on the left and right sides. Default is .10 */
+        keyHorizontalPaddingPercent?: number;
+        /** Percent of each key's height that should be used for padding on the top and bottom sides. Default is .10 */
+        keyVerticalPaddingPercent?: number;
+        /** Configuration of keyboard rows. Order is from top to bottom rows. */
+        rows?: Array<VirtualKeyboardRow>;
+        /** How many regular-sized keys should fit in a row? This is used for scaling purposes. If not provided, it will be inferred from the row configuration. */
+        keysPerRow?: number;
+        /** Size of font for keys. */
+        fontSize?: number;
+        /** The fonts for the key labels, if not the default font. */
+        fontNames?: Array<string> | undefined;
+        /** Comma-separated list of keys to hide. */
+        hiddenKeys?: string;
+        /** If true, only capital letters will be shown. */
+        capitalLettersOnly?: boolean;
+        /** Color of keys. */
+        keyColor?: RgbaColor;
+        /** Color of keys when pressed. */
+        keyDownColor?: RgbaColor;
+        /** Color of special keys when pressed. */
+        specialKeyDownColor?: RgbaColor;
+        /** Background color of keyboard. */
+        backgroundColor?: RgbaColor;
+        /** If true, a preview of the key that will be pressed will be shown. */
+        showKeyDownPreview?: boolean;
+        name?: string;
+        position?: Point;
+        scale?: number;
+        alpha?: number;
+        zRotation?: number;
+        isUserInteractionEnabled?: boolean;
+        draggable?: boolean;
+        hidden?: boolean;
+        layout?: _m2c2kit_core.Layout;
+        uuid?: string;
+        suppressEvents?: boolean;
+        anchorPoint?: Point;
+        zPosition?: number;
+    };
     initialize(): void;
     /**
      * Executes a callback when the user presses down on a key.
@@ -528,6 +710,45 @@ declare class VirtualKeyboard extends Composite {
      * @param options
      */
     onKeyUp(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the user has pressed a key with the pointer, but
+     * moves the pointer outside the key bounds before releasing the pointer.
+     *
+     * @remarks Typically, this event will not be used, since it is a user's
+     * inaccurate interaction with the keyboard. However, it can be used to
+     * provide feedback to the user that they have moved the pointer outside the
+     * key bounds, and thus the key stroke will not be registered.
+     *
+     * @param callback - function to execute
+     * @param options
+     */
+    onKeyLeave(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
+    update(): void;
+    draw(canvas: Canvas): void;
+    warmup(canvas: Canvas): void;
+    duplicate(newName?: string | undefined): M2Node;
+    private handleKeyShapeTapDown;
+    private handleKeyShapeTapUp;
+    private handleKeyShapeTapLeave;
+    private getKeyAsString;
+    /**
+     * Converts the keyboard rows to the internal keyboard configuration.
+     *
+     * @remarks This normalizes the keyboard rows so that each key is a
+     * full `KeyConfigurationWithShape` object, instead of a string or array of
+     * strings.
+     *
+     * @param keyboardRows
+     * @returns the keyboard for internal use
+     */
+    private internalKeyboardRowsToInternalKeyboardConfiguration;
+    handleCompositeEvent(event: VirtualKeyboardEvent): void;
+    private handleKeyDownEvent;
+    private handleKeyUpEvent;
+    private handleKeyLeaveEvent;
+    private showKeyboardShifted;
+    private showKeyboardNotShifted;
+    private createDefaultKeyboardRows;
     private addVirtualKeyboardEventListener;
     /**
      * Does the `VirtualKeyboard` respond to user events? Default is true.
@@ -537,10 +758,6 @@ declare class VirtualKeyboard extends Composite {
      * Does the `VirtualKeyboard` respond to user events? Default is true.
      */
     set isUserInteractionEnabled(isUserInteractionEnabled: boolean);
-    update(): void;
-    draw(canvas: Canvas): void;
-    warmup(canvas: Canvas): void;
-    duplicate(newName?: string | undefined): M2Node;
 }
 
 interface InstructionScene {
@@ -756,7 +973,10 @@ interface LocalePickerResult {
     /** Locale that was selected. Is undefined if dialog was dismissed. */
     locale?: string;
 }
-interface LocalePickerEvent extends M2NodeEvent {
+interface LocalePickerEvent extends CompositeEvent {
+    type: "Composite";
+    compositeType: "LocalePicker";
+    compositeEventType: "LocalePickerResult";
     result: LocalePickerResult;
 }
 interface LocaleSvg {
@@ -769,8 +989,7 @@ interface LocaleSvg {
     width: number;
 }
 declare class LocalePicker extends Composite {
-    compositeType: string;
-    zPosition: number;
+    readonly compositeType = "LocalePicker";
     private readonly DEFAULT_FONT_SIZE;
     automaticallyChangeLocale: boolean;
     private _localeOptions;
@@ -862,4 +1081,4 @@ declare class LocalePicker extends Composite {
     duplicate(newName?: string): LocalePicker;
 }
 
-export { Button, type ButtonOptions, CountdownScene, type CountdownSceneOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type LocaleOption, LocalePicker, type LocalePickerEvent, type LocalePickerIcon, type LocalePickerOptions, type LocalePickerResult, type StrokeInteraction, type TimerShape, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };
+export { Button, type ButtonOptions, CountdownScene, type CountdownSceneOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridChild, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type LocaleOption, LocalePicker, type LocalePickerEvent, type LocalePickerIcon, type LocalePickerOptions, type LocalePickerResult, type StrokeInteraction, type TimerShape, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };