@m2c2kit/core 0.3.11 → 0.3.13

package/dist/index.d.ts

@@ -422,6 +422,8 @@ interface EntityOptions {
     position?: Point;
     /** Scale of the entity. Default is 1.0 */
     scale?: number;
+    /** Opacity of the entity. 0 is fully transparent, 1 is fully opaque. Default is 1.0. Alpha has multiplicative in inheritance. For example, if the entity's parent is alpha .5 and this entity's is alpha .4, then the entity will appear with alpha .2. */
+    alpha?: number;
     /** Does the entity respond to user events, such as taps? Default is false */
     isUserInteractionEnabled?: boolean;
     /** Can the entity be dragged? */
@@ -502,6 +504,7 @@ declare class Scene extends Entity implements IDrawable, SceneOptions {
      * @param callback
      */
     onAppear(callback: (scene: Scene) => void): void;
+    update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
 }
@@ -1248,6 +1251,7 @@ declare class Game implements Activity {
     private raiseTapUpEvent;
     private raiseTapUpAny;
     private raiseM2PointerMoveEvent;
+    private raiseM2PointerLeaveEvent;
     private raiseM2DragStartEvent;
     private raiseM2DragEvent;
     private raiseM2DragEndEvent;
@@ -1681,39 +1685,41 @@ interface Activity {
  */
 interface EventBase {
     /** Type of event. */
-    type: EventType;
+    type: EventType | string;
     /** The object on which the event occurred. */
     target: Entity | Session | Activity;
     /** Has the event been taken care of by the listener and not be dispatched to other targets? */
     handled?: boolean;
 }
 /**
- * The different events that are dispatched by m2c2kit.
+ * The different events that are dispatched by m2c2kit core.
  */
-declare enum EventType {
-    SessionInitialize = "SessionInitialize",
-    SessionStart = "SessionStart",
-    SessionEnd = "SessionEnd",
-    ActivityStart = "ActivityStart",
-    ActivityEnd = "ActivityEnd",
-    ActivityCancel = "ActivityCancel",
-    ActivityData = "ActivityData",
-    TapDown = "TapDown",
-    TapUp = "TapUp",
-    TapUpAny = "TapUpAny",
-    TapLeave = "TapLeave",
-    PointerDown = "PointerDown",
-    PointerUp = "PointerUp",
-    PointerMove = "PointerMove",
-    Drag = "Drag",
-    DragStart = "DragStart",
-    DragEnd = "DragEnd",
-    CompositeCustom = "CompositeCustom",
-    FrameDidSimulatePhysics = "FrameDidSimulatePhysics"
-}
+declare const EventType: {
+    readonly SessionInitialize: "SessionInitialize";
+    readonly SessionStart: "SessionStart";
+    readonly SessionEnd: "SessionEnd";
+    readonly ActivityStart: "ActivityStart";
+    readonly ActivityEnd: "ActivityEnd";
+    readonly ActivityCancel: "ActivityCancel";
+    readonly ActivityData: "ActivityData";
+    readonly TapDown: "TapDown";
+    readonly TapUp: "TapUp";
+    readonly TapUpAny: "TapUpAny";
+    readonly TapLeave: "TapLeave";
+    readonly PointerDown: "PointerDown";
+    readonly PointerUp: "PointerUp";
+    readonly PointerMove: "PointerMove";
+    readonly PointerLeave: "PointerLeave";
+    readonly Drag: "Drag";
+    readonly DragStart: "DragStart";
+    readonly DragEnd: "DragEnd";
+    readonly CompositeCustom: "CompositeCustom";
+    readonly FrameDidSimulatePhysics: "FrameDidSimulatePhysics";
+};
+type EventType = (typeof EventType)[keyof typeof EventType];
 
 interface EntityEventListener {
-    type: EventType;
+    type: EventType | string;
     /** For composites that raise events, type of the composite custom event. */
     compositeType?: string;
     entityUuid: string;
@@ -1789,6 +1795,7 @@ declare abstract class Entity implements EntityOptions {
     name: string;
     position: Point;
     scale: number;
+    alpha: number;
     isUserInteractionEnabled: boolean;
     draggable: boolean;
     hidden: boolean;
@@ -1799,6 +1806,8 @@ declare abstract class Entity implements EntityOptions {
     absolutePosition: Point;
     size: Size;
     absoluteScale: number;
+    absoluteAlpha: number;
+    absoluteAlphaChange: number;
     actions: Action[];
     queuedAction?: Action;
     originalActions: Action[];
@@ -1810,6 +1819,7 @@ declare abstract class Entity implements EntityOptions {
     /** Is the entity in a pressed state? E.g., did the user put the pointer
      * down on the entity and not yet release it? */
     pressed: boolean;
+    withinHitArea: boolean;
     /** Is the entity in a pressed state AND is the pointer within the entity's
      * hit area? For example, a user may put the pointer down on the entity, but
      * then move the pointer, while still down, beyond the entity's hit area. In
@@ -1915,13 +1925,9 @@ declare abstract class Entity implements EntityOptions {
      * the bounds of the entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onTapDown(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
+    onTapDown(callback: (tapEvent: TapEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press, that has been fully
      * within the entity, from the entity.
@@ -1931,13 +1937,9 @@ declare abstract class Entity implements EntityOptions {
      * beyond the bounds of the entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}ue.
      */
-    onTapUp(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
+    onTapUp(callback: (tapEvent: TapEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press from the entity within
      * the bounds of the entity.
@@ -1948,13 +1950,9 @@ declare abstract class Entity implements EntityOptions {
      * release.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onTapUpAny(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
+    onTapUpAny(callback: (tapEvent: TapEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user moves the pointer (mouse, touches) beyond
      * the bounds of the entity while the pointer is down.
@@ -1964,13 +1962,9 @@ declare abstract class Entity implements EntityOptions {
      * before the press release.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onTapLeave(callback: (tapEvent: TapEvent) => void, callbackOptions?: CallbackOptions): void;
+    onTapLeave(callback: (tapEvent: TapEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the pointer first is down on the entity.
      *
@@ -1978,13 +1972,9 @@ declare abstract class Entity implements EntityOptions {
      * the bounds of the entity. It occurs under the same conditions as TapDown.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onPointerDown(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
+    onPointerDown(callback: (m2PointerEvent: M2PointerEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user releases a press from the entity within
      * the bounds of the entity.
@@ -1994,62 +1984,61 @@ declare abstract class Entity implements EntityOptions {
      * previous PointerDown on the entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onPointerUp(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
+    onPointerUp(callback: (m2PointerEvent: M2PointerEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user moves the pointer (mouse or touches)
      * within the bounds of the entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
+     */
+    onPointerMove(callback: (m2PointerEvent: M2PointerEvent) => void, options?: CallbackOptions): void;
+    /**
+     * Executes a callback when the user moves the pointer (mouse or touches)
+     * outside the bounds of the entity.
+     *
+     * @param callback - function to execute
+     * @param options - {@link CallbackOptions}
      */
-    onPointerMove(callback: (m2PointerEvent: M2PointerEvent) => void, callbackOptions?: CallbackOptions): void;
+    onPointerLeave(callback: (m2PointerEvent: M2PointerEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user begins dragging an entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onDragStart(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
+    onDragStart(callback: (m2DragEvent: M2DragEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user continues dragging an entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
+     * @param options - {@link CallbackOptions}
      */
-    onDrag(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
+    onDrag(callback: (m2DragEvent: M2DragEvent) => void, options?: CallbackOptions): void;
     /**
      * Executes a callback when the user stop dragging an entity.
      *
      * @param callback - function to execute
-     * @param replaceExistingCallback  - should the provided callback replace
-     * any existing callbacks of the same event type on this entity? Usually
-     * there should be only one callback defined, instead of chaining multiple
-     * ones. It is strongly recommended not to change this, unless you have a
-     * special use case. Default is true.
-     */
-    onDragEnd(callback: (m2DragEvent: M2DragEvent) => void, callbackOptions?: CallbackOptions): void;
-    addEventListener(type: EventType, callback: (ev: EntityEvent) => void, callbackOptions?: CallbackOptions): void;
+     * @param options - {@link CallbackOptions}
+     */
+    onDragEnd(callback: (m2DragEvent: M2DragEvent) => void, options?: CallbackOptions): void;
+    addEventListener(type: EventType | string, callback: (ev: EntityEvent) => void, callbackOptions?: CallbackOptions): void;
     private parseLayoutConstraints;
     private calculateYFromConstraint;
     private calculateXFromConstraint;
+    /**
+     * Calculates the absolute alpha of the entity, taking into account the
+     * alpha of all ancestor parent entities.
+     *
+     * @remarks Alpha has multiplicative inheritance from all ancestors.
+     *
+     * @param alpha - Opacity of the entity
+     * @param ancestors - Array of ancestor parent entities
+     * @returns
+     */
+    private calculateAbsoluteAlpha;
     update(): void;
     /**
      * Draws each child entity that is Drawable and is not hidden, by zPosition
@@ -2145,6 +2134,15 @@ interface ScaleActionOptions {
     runDuringTransition?: boolean;
 }
 
+interface FadeAlphaActionOptions {
+    /** Opacity of the entity. 0 is fully transparent, 1 is fully opaque. */
+    alpha: number;
+    /** Duration of scale, in milliseconds */
+    duration: number;
+    /** Should the action run during screen transitions? Default is no */
+    runDuringTransition?: boolean;
+}
+
 interface IActionContainer {
     children?: Array<Action>;
 }
@@ -2156,7 +2154,8 @@ declare enum ActionType {
     Wait = "Wait",
     Custom = "Custom",
     Move = "Move",
-    Scale = "Scale"
+    Scale = "Scale",
+    FadeAlpha = "FadeAlpha"
 }
 
 /**
@@ -2208,6 +2207,15 @@ declare abstract class Action {
      * @returns The scale action
      */
     static scale(options: ScaleActionOptions): Action;
+    /**
+     * Creates an action that will change the entity's alpha (opacity).
+     *
+     * @remarks Alpha has multiplicative inheritance. For example, if the entity's parent is alpha .5 and this entity's action fades alpha to .4, then the entity will appear with alpha .2.
+     *
+     * @param options - {@link FadeAlphaActionOptions}
+     * @returns The fadeAlpha action
+     */
+    static fadeAlpha(options: FadeAlphaActionOptions): Action;
     /**
      * Creates an array of actions that will be run in order.
      *
@@ -2308,6 +2316,12 @@ declare class ScaleAction extends Action {
     delta: number;
     constructor(scale: number, duration: number, runDuringTransition?: boolean);
 }
+declare class FadeAlphaAction extends Action {
+    type: ActionType;
+    alpha: number;
+    delta: number;
+    constructor(alpha: number, duration: number, runDuringTransition?: boolean);
+}
 
 declare class CanvasKitHelpers {
     /**
@@ -2467,6 +2481,8 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
     private paragraph?;
     private paraStyle?;
     private builder?;
+    private _fontPaint?;
+    private _backgroundPaint?;
     private _translatedText;
     /**
      * Single or multi-line text formatted and rendered on the screen.
@@ -2495,6 +2511,10 @@ declare class Label extends Entity implements IDrawable, IText, LabelOptions {
     set preferredMaxLayoutWidth(preferredMaxLayoutWidth: number | undefined);
     get backgroundColor(): RgbaColor | undefined;
     set backgroundColor(backgroundColor: RgbaColor | undefined);
+    private get backgroundPaint();
+    private set backgroundPaint(value);
+    private get fontPaint();
+    private set fontPaint(value);
     /**
      * Duplicates an entity using deep copy.
      *
@@ -2685,7 +2705,6 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     ckPath: Path | null;
     ckPathWidth?: number;
     ckPathHeight?: number;
-    pathSvgString?: string;
     cornerRadius: number;
     private _fillColor;
     private _strokeColor?;
@@ -2700,10 +2719,9 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     private svgPathScaleForResizing;
     private svgPathWidth;
     private svgPathHeight;
-    private svgPreviousAbsoluteScale;
     private svgPreviousAbsoluteX;
     private svgPreviousAbsoluteY;
-    private pathIsSvgStringPath;
+    private svgFirstPathDraw;
     /**
      * Rectangular, circular, or path-based shape
      *
@@ -2725,13 +2743,16 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     duplicate(newName?: string): Shape;
     update(): void;
     draw(canvas: Canvas): void;
+    private applyAlphaToPaints;
     private drawPathFromM2Path;
     private drawPathFromSvgString;
     private calculateSvgPathY;
     private calculateSvgPathX;
-    private saveSvgPathDrawParameters;
+    private saveSvgPathAbsolutePosition;
     private calculateTransformationMatrix;
     private pathNeedsTransform;
+    private shapeIsSvgStringPath;
+    private shapeIsM2Path;
     private drawCircle;
     private drawRectangle;
     private drawCircleWithCanvasKit;
@@ -2775,6 +2796,7 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     zPosition: number;
     private _imageName;
     private loadedImage?;
+    private _paint?;
     /**
      * Visual image displayed on the screen.
      *
@@ -2787,6 +2809,8 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     dispose(): void;
     set imageName(imageName: string);
     get imageName(): string;
+    private set paint(value);
+    private get paint();
     /**
      * Duplicates an entity using deep copy.
      *
@@ -3132,4 +3156,4 @@ declare class WebGlInfo {
     static dispose(): void;
 }
 
-export { Action, Activity, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, ActivityType, BrowserImage, CallbackOptions, CanvasKitHelpers, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, EasingFunction, Easings, Entity, EntityEvent, EntityEventListener, EntityOptions, EntityType, Equals, EventBase, EventListenerBase, EventType, FontData, FontManager, Game, GameData, GameOptions, GameParameters, GlobalVariables, GoToActivityOptions, GroupAction, I18n, IDataStore, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, M2DragEvent, M2Path, MoveAction, MoveActionOptions, MutablePath, NoneTransition, Point, RandomDraws, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionDictionaryValues, SessionLifecycleEvent, SessionOptions, Shape, ShapeOptions, ShapeType, Size, SlideTransition, SlideTransitionOptions, Sprite, SpriteOptions, Story, StoryOptions, TapEvent, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, Translations, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };
+export { Action, Activity, ActivityKeyValueData, ActivityLifecycleEvent, ActivityResultsEvent, ActivityType, BrowserImage, CallbackOptions, CanvasKitHelpers, Composite, CompositeOptions, Constants, ConstraintType, Constraints, CustomAction, CustomActionOptions, DefaultParameter, Dimensions, DrawableOptions, EasingFunction, Easings, Entity, EntityEvent, EntityEventListener, EntityOptions, EntityType, Equals, EventBase, EventListenerBase, EventType, FadeAlphaAction, FadeAlphaActionOptions, FontData, FontManager, Game, GameData, GameOptions, GameParameters, GlobalVariables, GoToActivityOptions, GroupAction, I18n, IDataStore, IDrawable, IText, ImageManager, Label, LabelHorizontalAlignmentMode, LabelOptions, Layout, LayoutConstraint, LoadedImage, M2DragEvent, M2Path, M2PointerEvent, MoveAction, MoveActionOptions, MutablePath, NoneTransition, Point, RandomDraws, RectOptions, RgbaColor, ScaleAction, ScaleActionOptions, Scene, SceneOptions, SceneTransition, SequenceAction, Session, SessionDictionaryValues, SessionLifecycleEvent, SessionOptions, Shape, ShapeOptions, ShapeType, Size, SlideTransition, SlideTransitionOptions, Sprite, SpriteOptions, Story, StoryOptions, TapEvent, TextLine, TextLineOptions, TextOptions, Timer, Transition, TransitionDirection, TransitionType, Translations, TrialData, TrialSchema, Uuid, WaitAction, WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };