@m2c2kit/core 0.3.26 → 0.3.28

package/dist/index.d.ts

@@ -403,6 +403,32 @@ interface SceneOptions extends M2NodeOptions, DrawableOptions {
     backgroundColor?: RgbaColor;
 }
 
+/**
+ * Describes an event on the device's built-in keyboard.
+ *
+ * @remarks The built-in keyboard is defined as the hardware keyboard on a
+ * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+ * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+ * in the `@m2c2kit/addons` package should be used for key events.
+ * @remarks Key events can occur only on a `Scene` node.
+ */
+interface M2KeyboardEvent extends M2NodeEvent {
+    /** 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. */
+    code: string;
+    /** True if the Shift key is pressed. */
+    shiftKey: boolean;
+    /** True if the Control key is pressed. */
+    ctrlKey: boolean;
+    /** True if the Alt key is pressed. */
+    altKey: boolean;
+    /** True if the Meta key is pressed. */
+    metaKey: boolean;
+    /** True if the event is being repeated. */
+    repeat: boolean;
+}
+
 declare class Scene extends M2Node implements IDrawable, SceneOptions {
     readonly type = M2NodeType.Scene;
     isDrawable: boolean;
@@ -485,6 +511,34 @@ declare class Scene extends M2Node implements IDrawable, SceneOptions {
      * @param options - {@link CallbackOptions}
      */
     onAppear(callback: (nodeEvent: M2NodeEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Code that will be called after a key is pressed on the device's
+     * built-in keyboard.
+     *
+     * @remarks The built-in keyboard is defined as the hardware keyboard on a
+     * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+     * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+     * in the `@m2c2kit/addons` package should be used for key events.
+     * @remarks Key events can occur only on a `Scene` node.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
+     */
+    onKeyDown(callback: (m2KeyboardEvent: M2KeyboardEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Code that will be called after a key is released on the device's
+     * built-in keyboard.
+     *
+     * @remarks The built-in keyboard is defined as the hardware keyboard on a
+     * desktop/laptop or the built-in soft keyboard on a tablet or phone. The
+     * latter is not used in m2c2kit. On tablet or phone, the `VirtualKeyboard`
+     * in the `@m2c2kit/addons` package should be used for key events.
+     * @remarks Key events can occur only on a `Scene` node.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
+     */
+    onKeyUp(callback: (m2KeyboardEvent: M2KeyboardEvent) => void, options?: CallbackOptions): void;
     update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
@@ -2111,6 +2165,8 @@ declare class Game implements Activity {
     private htmlCanvasPointerUpHandler;
     private htmlCanvasPointerMoveHandler;
     private htmlCanvasPointerLeaveHandler;
+    private documentKeyDownHandler;
+    private documentKeyUpHandler;
     /**
      * Determines if/how m2c2kit nodes respond to the DOM PointerDown event
      *
@@ -2428,6 +2484,8 @@ declare const M2EventType: {
     readonly PointerUp: "PointerUp";
     readonly PointerMove: "PointerMove";
     readonly PointerLeave: "PointerLeave";
+    readonly KeyDown: "KeyDown";
+    readonly KeyUp: "KeyUp";
     readonly Drag: "Drag";
     readonly DragStart: "DragStart";
     readonly DragEnd: "DragEnd";
@@ -3676,8 +3734,8 @@ declare class Constants {
     /** Placeholder that will be populated during the build process. */
     static readonly MODULE_METADATA_PLACEHOLDER: ModuleMetadata;
     static readonly DEFAULT_ROOT_ELEMENT_ID = "m2c2kit";
-    static readonly ERUDA_URL = "https://cdn.jsdelivr.net/npm/eruda@3.2.3/eruda.js";
-    static readonly ERUDA_SRI = "sha384-KlRzgy/c+nZSV+eiFqoTkkbZ5pUqToho7HsNuebTbOsYTh4m0m/PAqkGsTMLXK14";
+    static readonly ERUDA_URL = "https://cdn.jsdelivr.net/npm/eruda@3.4.1/eruda.js";
+    static readonly ERUDA_SRI = "sha384-daS5bEfWdSq146t9c4BureB/fQWO3lHohseXBelPqKvbOUx2D6PE3TxcQ9jrKZDM";
 }
 
 /**
@@ -4739,10 +4797,49 @@ declare class SoundRecorder extends M2Node implements Omit<SoundRecorderOptions,
      */
     constructor(options?: SoundRecorderOptions);
     initialize(): void;
+    /**
+     * Starts recording audio from the microphone.
+     *
+     * @remarks If the `SoundRecorder` is already recording, an error will be
+     * thrown. If permission to use the microphone has not been granted, the
+     * browser will prompt the user to allow or deny access. Denial of access
+     * will result in an error being thrown. To avoid this, use the
+     * `queryPermission()` and `requestPermission()` methods to check and request
+     * permission, respectively, and handle the results accordingly.
+     */
     start(): Promise<void>;
+    /**
+     * Stops recording audio from the microphone.
+     *
+     * @remarks If the `stop()` method is not awaited, the method returns a
+     * Promise and the useable data will be lost.
+     *
+     * @returns A promise that resolves to a {@link SoundRecorderResults} object.
+     * The `audioBase64` property of the object contains the recorded audio as a
+     * base64 string.
+     */
     stop(): Promise<SoundRecorderResults>;
     pause(): void;
     resume(): void;
+    /**
+     * Checks if the microphone permission is granted.
+     *
+     * @remarks This does not request permission from the user. It only queries
+     * the current microphone permission state.
+     *
+     * @returns The `state` property ("granted", "denied", or "prompt") of
+     * `PermissionStatus` or undefined if the browser does not support the
+     * "microphone" permission.
+     * See https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state
+     */
+    queryPermission(): Promise<string | undefined>;
+    /**
+     * Requests permission to use the microphone, and possibly prompts the user
+     * to allow or deny access.
+     *
+     * @returns true if the microphone permission is granted, false if denied.
+     */
+    requestPermission(): Promise<boolean>;
     /** Is the `SoundRecorder` currently recording? */
     get isRecording(): boolean;
     /** Is the `SoundRecorder` currently paused? */
@@ -5244,4 +5341,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, type Activity, type ActivityCallbacks, type ActivityEvent, type ActivityEventListener, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type BrowserImageDataReadyEvent, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeEvent, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DomPointerDownEvent, type DrawableOptions, type EasingFunction, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, type FadeAlphaActionOptions, type FontAsset, type FontData, FontManager, Game, type GameData, type GameEvent, type GameOptions, type GameParameters, type GlobalVariables, GroupAction, I18n, type I18nDataReadyEvent, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LegacyTimer, type LocaleSvg, type M2ColorfulPath, type M2DragEvent, type M2Event, type M2EventListener, M2EventType, type M2Image, M2ImageStatus, M2Node, type M2NodeAddChildEvent, type M2NodeConstructor, type M2NodeEvent, type M2NodeEventListener, M2NodeFactory, type M2NodeNewEvent, type M2NodeOptions, type M2NodePropertyChangeEvent, type M2NodeRemoveChildEvent, M2NodeType, type M2Path, type M2PointerEvent, type M2Sound, M2SoundStatus, M2c2KitHelpers, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, PlayAction, type PlayActionOptions, type Plugin, type PluginEvent, type Point, RandomDraws, type RectOptions, RepeatAction, RepeatForeverAction, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, type ScenePresentEvent, SceneTransition, type ScoringSchema, SequenceAction, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, type SoundAsset, SoundManager, SoundPlayer, type SoundPlayerOptions, SoundRecorder, type SoundRecorderOptions, type SoundRecorderResults, Sprite, type SpriteOptions, Story, type StoryOptions, type StringInterpolationMap, type TapEvent, type TextAndFont, TextLine, type TextLineOptions, type TextLocalizationResult, type TextOptions, type TextWithFontCustomization, Timer, Transition, TransitionDirection, TransitionType, type Translation, type TranslationConfiguration, type TranslationOptions, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, type Activity, type ActivityCallbacks, type ActivityEvent, type ActivityEventListener, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type BrowserImageDataReadyEvent, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeEvent, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DomPointerDownEvent, type DrawableOptions, type EasingFunction, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, type FadeAlphaActionOptions, type FontAsset, type FontData, FontManager, Game, type GameData, type GameEvent, type GameOptions, type GameParameters, type GlobalVariables, GroupAction, I18n, type I18nDataReadyEvent, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LegacyTimer, type LocaleSvg, type M2ColorfulPath, type M2DragEvent, type M2Event, type M2EventListener, M2EventType, type M2Image, M2ImageStatus, type M2KeyboardEvent, M2Node, type M2NodeAddChildEvent, type M2NodeConstructor, type M2NodeEvent, type M2NodeEventListener, M2NodeFactory, type M2NodeNewEvent, type M2NodeOptions, type M2NodePropertyChangeEvent, type M2NodeRemoveChildEvent, M2NodeType, type M2Path, type M2PointerEvent, type M2Sound, M2SoundStatus, M2c2KitHelpers, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, PlayAction, type PlayActionOptions, type Plugin, type PluginEvent, type Point, RandomDraws, type RectOptions, RepeatAction, RepeatForeverAction, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, type ScenePresentEvent, SceneTransition, type ScoringSchema, SequenceAction, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, type SoundAsset, SoundManager, SoundPlayer, type SoundPlayerOptions, SoundRecorder, type SoundRecorderOptions, type SoundRecorderResults, Sprite, type SpriteOptions, Story, type StoryOptions, type StringInterpolationMap, type TapEvent, type TextAndFont, TextLine, type TextLineOptions, type TextLocalizationResult, type TextOptions, type TextWithFontCustomization, Timer, Transition, TransitionDirection, TransitionType, type Translation, type TranslationConfiguration, type TranslationOptions, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };