@m2c2kit/core 0.3.12 → 0.3.14

package/dist/index.d.ts

@@ -365,7 +365,7 @@ declare enum EntityType {
 type RgbaColor = [number, number, number, number];
 
 interface DrawableOptions {
-    /** Point within the entity that determines its position. Default is \{ x: 0.5, y: 0.5 \}, which centers the entity on its position */
+    /** Point within the entity that determines its position. Default is { x: 0.5, y: 0.5 }, which centers the entity on its position */
     anchorPoint?: Point;
     /** Value along the z-axis to determine drawing and tap order. Larger values are on top. */
     zPosition?: number;
@@ -422,6 +422,10 @@ 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 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;
+    /** Rotation of the entity around the Z axis. Unit is radians. Default is 0 (no rotation). zRotation has inheritance. In addition to this entity's zRotation, all ancestors' zRotations will be applied. */
+    zRotation?: number;
     /** Does the entity respond to user events, such as taps? Default is false */
     isUserInteractionEnabled?: boolean;
     /** Can the entity be dragged? */
@@ -502,6 +506,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;
 }
@@ -1085,12 +1090,12 @@ declare class Game implements Activity {
      * Rather than modify the source code for the game, you can do the following
      * to ensure that the participant ID is saved for each trial:
      *
-     *   game.addTrialSchema({
-     *     participant_id: {
+     *   game.addTrialSchema(&#123
+     *     participant_id: &#123
      *       type: "string",
      *       description: "ID of the participant",
-     *     }
-     *   });
+     *     }
+     *   });
      *   game.addStaticTrialData("participant_id", "12345");
      *
      *  When Game.trialComplete() is called, the participant_id variable will
@@ -1295,7 +1300,6 @@ declare class Game implements Activity {
      * @returns true if x, y point is within the entity's bounds
      */
     private IsCanvasPointWithinEntityBounds;
-    private calculateEntityAbsoluteBoundingBox;
     prependAssetsGameIdUrl(url: string): string;
 }
 
@@ -1792,6 +1796,8 @@ declare abstract class Entity implements EntityOptions {
     name: string;
     position: Point;
     scale: number;
+    alpha: number;
+    zRotation: number;
     isUserInteractionEnabled: boolean;
     draggable: boolean;
     hidden: boolean;
@@ -1802,6 +1808,8 @@ declare abstract class Entity implements EntityOptions {
     absolutePosition: Point;
     size: Size;
     absoluteScale: number;
+    absoluteAlpha: number;
+    absoluteAlphaChange: number;
     actions: Action[];
     queuedAction?: Action;
     originalActions: Action[];
@@ -2022,6 +2030,17 @@ declare abstract class Entity implements EntityOptions {
     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
@@ -2117,6 +2136,28 @@ 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 RotateActionOptions {
+    /** Relative amount to rotate the entity, in counter-clockwise radians */
+    byAngle?: number;
+    /** Absolute angle to which rotate the entity, in counter-clockwise radians */
+    toAngle?: number;
+    /** If `toAngle` is provided, should the rotation be performed in the direction that leads to the smallest rotation? Default is true */
+    shortestUnitArc?: boolean;
+    /** Duration of rotation, in milliseconds */
+    duration: number;
+    /** Should the action run during screen transitions? Default is false */
+    runDuringTransition?: boolean;
+}
+
 interface IActionContainer {
     children?: Array<Action>;
 }
@@ -2128,7 +2169,9 @@ declare enum ActionType {
     Wait = "Wait",
     Custom = "Custom",
     Move = "Move",
-    Scale = "Scale"
+    Scale = "Scale",
+    FadeAlpha = "FadeAlpha",
+    Rotate = "Rotate"
 }
 
 /**
@@ -2180,6 +2223,24 @@ 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 action that will rotate the entity.
+     *
+     * @remarks Rotate actions are applied to their children. In addition to this entity's rotate action, all ancestors' rotate actions will also be applied.
+     *
+     * @param options - {@link RotateActionOptions}
+     * @returns The rotate action
+     */
+    static rotate(options: RotateActionOptions): Action;
     /**
      * Creates an array of actions that will be run in order.
      *
@@ -2280,6 +2341,21 @@ 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 RotateAction extends Action {
+    type: ActionType;
+    byAngle?: number;
+    toAngle?: number;
+    shortestUnitArc?: boolean;
+    delta: number;
+    finalValue: number;
+    constructor(byAngle: number | undefined, toAngle: number | undefined, shortestUnitArc: boolean | undefined, duration: number, runDuringTransition?: boolean);
+}
 
 declare class CanvasKitHelpers {
     /**
@@ -2293,6 +2369,101 @@ declare class CanvasKitHelpers {
     static makePaint(canvasKit: CanvasKit, color: RgbaColor, style: PaintStyle, isAntialiased: boolean): Paint;
 }
 
+/**
+ * A collection of lines to draw.
+ */
+interface M2Path {
+    /** The subpath that compose up the path */
+    subpaths: Array<Array<Point>>;
+}
+
+/**
+ * Subpaths and methods for creating them.
+ *
+ * @remarks Subpaths are an array of lines that are drawn together.
+ */
+declare class MutablePath implements M2Path {
+    _subpaths: Point[][];
+    get subpaths(): Array<Array<Point>>;
+    protected currentPath: Point[];
+    /**
+     * Starts a new subpath at a given point.
+     *
+     * @param point - location at which to start the new subpath
+     */
+    move(point: Point): void;
+    /**
+     * Adds a straight line to the current subpath.
+     *
+     * @remarks The line is added from the last point in the current subpath to
+     * the given point.
+     *
+     * @param point - location where the line will end
+     */
+    addLine(point: Point): void;
+    /**
+     * Removes all subpaths from the shape.
+     */
+    clear(): void;
+    /**
+     * Makes a deep copy.
+     *
+     * @returns a deep copy
+     */
+    duplicate(): MutablePath;
+}
+
+/**
+ * Properties that describe line colors and widths in a `M2ColorfulPath`.
+ */
+interface LinePresentation {
+    strokeColor: RgbaColor;
+    lineWidth: number;
+    subpathIndex: number;
+    pointIndex: number;
+}
+
+/**
+ * Multi-color subpaths and methods for creating them.
+ *
+ * @remarks Subpaths are an array of lines that are drawn together.
+ */
+declare class ColorfulMutablePath extends MutablePath {
+    /** Stroke color to be applied to subsequent lines. */
+    strokeColor: RgbaColor;
+    /** Line width to be applied to subsequent lines. */
+    lineWidth: number;
+    /** Colors and widths of lines in the path. */
+    linePresentations: Array<LinePresentation>;
+    /**
+     * Adds a straight line to the current subpath
+     *
+     * @remarks The line is added from the last point in the current subpath to
+     * the given point, with the current stroke color and line width.
+     *
+     * @param point - location where the line will end
+     */
+    addLine(point: Point): void;
+    /**
+     * Checks if the current line presentation (stroke color and line width) is
+     * different from the last line presentation.
+     *
+     * @returns true if the current line presentation is different from the last
+     */
+    private isNewLinePresentation;
+    /**
+     * Removes all subpaths from the shape and resets the stroke color and line
+     * width to their default values.
+     */
+    clear(): void;
+    /**
+     * Makes a deep copy.
+     *
+     * @returns a deep copy
+     */
+    duplicate(): ColorfulMutablePath;
+}
+
 interface CompositeOptions extends EntityOptions, DrawableOptions {
 }
 
@@ -2439,6 +2610,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.
@@ -2467,6 +2640,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.
      *
@@ -2507,40 +2684,14 @@ declare class LayoutConstraint {
 }
 
 /**
- * A set of lines and/or shapes to draw.
- */
-interface M2Path {
-    /** The subpath that compose up the path */
-    subpaths: Array<Array<Point>>;
-    /** The size of the path. This is needed to properly position the shape that is drawn by the path */
-    size: Size;
-}
-
-/**
- * Lines and/or shapes, and methods for creating them.
+ * A collection of multi-color lines to draw.
+ *
+ * @remarks Unlike `M2Path`, this interface allows for lines of different
+ * colors and widths to be drawn in the same path.
  */
-declare class MutablePath implements M2Path {
-    size: Size;
-    _subpaths: Point[][];
-    get subpaths(): Array<Array<Point>>;
-    private currentPath;
-    /**
-     * Starts a new subpath at a given point.
-     *
-     * @param point - location at which to start the new subpath
-     */
-    move(point: Point): void;
-    /**
-     * Adds a straight line to the current subpath.
-     *
-     * @remarks The line is added from the last point in the current subpath to
-     * the given point.
-     *
-     * @param point - location where the line will end
-     */
-    addLine(point: Point): void;
-    clear(): void;
-    duplicate(newName?: string | undefined): Entity;
+interface M2ColorfulPath extends M2Path {
+    /** Colors and widths of lines in the path. */
+    linePresentations: Array<LinePresentation>;
 }
 
 declare class RandomDraws {
@@ -2577,7 +2728,7 @@ declare class RandomDraws {
      * grid location to be along the diagonal, the predicate would be:
      * (row, column) => row === column
      * @returns Array of grid cells. Each cell is object in form of:
-     * \{ row: number, column: number \}. Grid cell locations are zero-based
+     * &#123 row: number, column: number &#125;. Grid cell locations are zero-based
      */
     static FromGridWithoutReplacement(n: number, rows: number, columns: number, predicate?: (row: number, column: number) => boolean): Array<{
         row: number;
@@ -2611,7 +2762,9 @@ declare enum ShapeType {
  * A path created from an SVG string path.
  */
 interface SvgStringPath {
-    /** SVG string from which to create te path */
+    /** SVG string from which to create the path */
+    pathString?: string;
+    /** SVG string from which to create the path @deprecated Use `pathString` */
     svgPathString?: string;
     /** If provided, scale the SVG path to this height, and scale the width to keep the original SVG proportions */
     height?: number;
@@ -2634,8 +2787,8 @@ interface ShapeOptions extends EntityOptions, DrawableOptions {
     /** Width of outline. Default is undefined for rectangle and circle, 2 for path. */
     lineWidth?: number;
     /** A path from which to create the shape */
-    path?: M2Path | SvgStringPath;
-    /** Size of container "view box" for path shapes. Leave undefined for circle and rectangle shapes. */
+    path?: M2Path | M2ColorfulPath | SvgStringPath;
+    /** Size of container "view box" for M2Path and M2ColorfulPath shapes. Leave undefined for circle, rectangle, and SvgStringPath shapes. */
     size?: Size;
     /** Should the shape be drawn with anti-aliasing. Default is yes. */
     isAntialiased?: boolean;
@@ -2653,7 +2806,7 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     shapeType: ShapeType;
     circleOfRadius?: number;
     rect?: RectOptions;
-    path?: M2Path | SvgStringPath;
+    path?: M2Path | M2ColorfulPath | SvgStringPath;
     ckPath: Path | null;
     ckPathWidth?: number;
     ckPathHeight?: number;
@@ -2674,6 +2827,7 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     private svgPreviousAbsoluteX;
     private svgPreviousAbsoluteY;
     private svgFirstPathDraw;
+    private colorfulPathPaints;
     /**
      * Rectangular, circular, or path-based shape
      *
@@ -2695,6 +2849,7 @@ 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;
@@ -2704,6 +2859,7 @@ declare class Shape extends Entity implements IDrawable, ShapeOptions {
     private pathNeedsTransform;
     private shapeIsSvgStringPath;
     private shapeIsM2Path;
+    private pathIsM2ColorfulPath;
     private drawCircle;
     private drawRectangle;
     private drawCircleWithCanvasKit;
@@ -2747,6 +2903,7 @@ declare class Sprite extends Entity implements IDrawable, SpriteOptions {
     zPosition: number;
     private _imageName;
     private loadedImage?;
+    private _paint?;
     /**
      * Visual image displayed on the screen.
      *
@@ -2759,6 +2916,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.
      *
@@ -3104,4 +3263,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, 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 };
+export { Action, type Activity, type ActivityKeyValueData, type ActivityLifecycleEvent, type ActivityResultsEvent, ActivityType, type BrowserImage, type CallbackOptions, CanvasKitHelpers, ColorfulMutablePath, Composite, type CompositeOptions, Constants, ConstraintType, type Constraints, CustomAction, type CustomActionOptions, type DefaultParameter, Dimensions, type DrawableOptions, type EasingFunction, Easings, Entity, type EntityEvent, type EntityEventListener, type EntityOptions, EntityType, Equals, type EventBase, type EventListenerBase, EventType, FadeAlphaAction, type FadeAlphaActionOptions, type FontData, FontManager, Game, type GameData, type GameOptions, type GameParameters, GlobalVariables, type GoToActivityOptions, GroupAction, I18n, type IDataStore, type IDrawable, type IText, ImageManager, Label, LabelHorizontalAlignmentMode, type LabelOptions, type Layout, LayoutConstraint, LoadedImage, type M2ColorfulPath, type M2DragEvent, type M2Path, type M2PointerEvent, MoveAction, type MoveActionOptions, MutablePath, NoneTransition, type Point, RandomDraws, type RectOptions, type RgbaColor, RotateAction, ScaleAction, type ScaleActionOptions, Scene, type SceneOptions, SceneTransition, SequenceAction, Session, type SessionDictionaryValues, type SessionLifecycleEvent, type SessionOptions, Shape, type ShapeOptions, ShapeType, type Size, SlideTransition, type SlideTransitionOptions, Sprite, type SpriteOptions, Story, type StoryOptions, type TapEvent, TextLine, type TextLineOptions, type TextOptions, Timer, Transition, TransitionDirection, TransitionType, type Translations, type TrialData, type TrialSchema, Uuid, WaitAction, type WaitActionOptions, WebColors, WebGlInfo, handleInterfaceOptions };