melonjs 20.12.0 → 20.13.0

package/build/renderable/ui/uispriteelement.d.ts

@@ -1,114 +1,190 @@
-import type Pointer from "./../../input/pointer.ts";
+import type Camera2d from "../../camera/camera2d.ts";
+import type Renderer from "../../video/renderer.js";
 import Sprite from "./../sprite.js";
+import type { UIJuiceSettings } from "./uibaseelement.ts";
+import UIBaseElement from "./uibaseelement.ts";
 /**
- * This is a basic sprite based button which you can use in your Game UI.
+ * Settings for a {@link UISpriteElement}: the {@link Sprite} settings for its
+ * image, plus the bounce shared by every UI element.
  * @category UI
  */
-export default class UISpriteElement extends Sprite {
+export type UISpriteElementSettings = {
     /**
-     * if this UISpriteElement should use screen coordinates or local coordinates
-     * (Note: any UISpriteElement elements added to a floating parent container should have their floating property to false)
-     * @see Renderable.floating
-     * @default true
+     * The image: a loader key, an image, or a {@link TextureAtlas} (with
+     * `region`). Every other {@link Sprite} setting is accepted too:
+     * `region`, `framewidth`, `frameheight`, `anchorPoint`, `tint`...
      */
-    floating: boolean;
+    image: any;
     /**
-     * object can be clicked or not
+     * Whether the element starts turned on.
      * @default true
      */
-    isClickable: boolean;
+    enabled?: boolean;
+    [key: string]: any;
+} & UIJuiceSettings;
+/**
+ * An image that takes clicks: use it for an image-only button or a clickable
+ * icon, such as a pause or a sound toggle, with no label.
+ *
+ * It is a {@link UIBaseElement} holding a {@link Sprite}, so it behaves like
+ * every other UI element: the same pointer callbacks, `enabled`,
+ * `cancelPress()` / `onCancel()`, dragging, the bounce (`hoverScale`,
+ * `pressScale`), and keyboard and gamepad focus once `focusable` is set. A
+ * press stops here by default, so what is under it does not get it too.
+ *
+ * The image is {@link UISpriteElement#sprite}: change its region, add and
+ * play animations or tint it there. It takes the {@link Sprite} settings, and
+ * as a sprite does, `(x, y)` is where its anchor point goes, the centre by
+ * default (`anchorPoint` 0.5, 0.5). The element covers the image, so
+ * `pos` is its top left corner and `width` / `height` its size.
+ *
+ * A disabled element (`enabled = false`) is drawn at half opacity.
+ * @category UI
+ * @example
+ * // a sound toggle icon from an atlas, swapping its region on each click
+ * import { UISpriteElement, audio } from "melonjs";
+ *
+ * class SoundIcon extends UISpriteElement {
+ *     constructor(x, y) {
+ *         super(x, y, { image: atlas, region: "sound_on", hoverScale: 1.1 });
+ *         this.muted = false;
+ *     }
+ *     onClick() {
+ *         this.muted = !this.muted;
+ *         if (this.muted) {
+ *             audio.muteAll();
+ *         } else {
+ *             audio.unmuteAll();
+ *         }
+ *         this.sprite.setRegion(atlas.getRegion(this.muted ? "sound_off" : "sound_on"));
+ *         return false;
+ *     }
+ * }
+ *
+ * app.world.addChild(new SoundIcon(40, 40));
+ * @example
+ * // a pause button from a spritesheet: frame 0 at rest, frame 1 under the pointer
+ * import { UISpriteElement, state } from "melonjs";
+ *
+ * class PauseButton extends UISpriteElement {
+ *     constructor(x, y) {
+ *         super(x, y, { image: "pause_button", framewidth: 64, frameheight: 64 });
+ *         this.sprite.addAnimation("idle", [0]);
+ *         this.sprite.addAnimation("over", [1]);
+ *         this.sprite.setCurrentAnimation("idle");
+ *     }
+ *     onOver() {
+ *         this.sprite.setCurrentAnimation("over");
+ *     }
+ *     onOut() {
+ *         this.sprite.setCurrentAnimation("idle");
+ *     }
+ *     onRelease() {
+ *         state.pause();
+ *         return false;
+ *     }
+ * }
+ * @example
+ * // placed by its top left corner, and reachable with the arrow keys
+ * const icon = new UISpriteElement(16, 16, {
+ *     image: atlas,
+ *     region: "gear",
+ *     anchorPoint: { x: 0, y: 0 },
+ * });
+ * icon.focusable = true;
+ */
+export default class UISpriteElement extends UIBaseElement {
+    /**
+     * The image, drawn to fill the element. Change its region, animations
+     * or tint here.
+     * @example
+     * icon.sprite.setRegion(atlas.getRegion("sound_off"));
+     */
+    readonly sprite: Sprite;
+    /** the sprite's size and anchor the element was last fitted to */
+    private readonly _fitted;
     /**
-     * Tap and hold threshold timeout in ms
-     * @default 250
+     * @param x - where the image's anchor point goes (its centre by
+     * default), in screen pixels
+     * @param y - where the image's anchor point goes (its centre by
+     * default), in screen pixels
+     * @param settings - the {@link Sprite} settings, and the bounce
+     * @example
+     * // a button image loaded as "button", logging each press
+     * class MyButton extends UISpriteElement {
+     *     constructor(x, y) {
+     *         super(x, y, { image: "button" });
+     *     }
+     *     onClick() {
+     *         console.log("clicked!");
+     *         return false;
+     *     }
+     * }
+     *
+     * app.world.addChild(new MyButton(100, 50));
      */
-    holdThreshold: number;
+    constructor(x: number, y: number, settings: UISpriteElementSettings);
     /**
-     * object can be tap and hold
-     * @default false
+     * Show another region of the texture: a shortcut for
+     * `sprite.setRegion(region)`. The element takes the region's size, with
+     * the image's anchor point staying where it was, as a sprite's does.
+     * @param region - a region from {@link TextureAtlas#getRegion}
+     * @returns this element
+     * @example
+     * icon.setRegion(atlas.getRegion("sound_off"));
      */
-    isHoldable: boolean;
+    setRegion(region: object): this;
     /**
-     * true if the pointer is over the object
-     * @default false
+     * Follow the sprite after its frame, region or anchor changed: the
+     * element takes the image's size, and the image's anchor point stays
+     * where it was on screen, as a sprite's `pos` does. Runs every update, so
+     * a `sprite.setRegion()` or an animation with frames of different sizes
+     * is followed too.
+     * @ignore
      */
-    hover: boolean;
-    holdTimeout: number;
-    released: boolean;
+    private fitToSprite;
     /**
-     * @param x - the x coordinate of the UISpriteElement Object
-     * @param y - the y coordinate of the UISpriteElement Object
-     * @param settings - See {@link Sprite}
-     * @param settings.image - the image to use for the sprite
-     * @example
-     * // create a basic GUI Object
-     * class myButton extends UISpriteElement {
-     *    constructor(x, y) {
-     *       // call the UISpriteElement parent constructor
-     *       super(x, y, {
-     *          image: "button",
-     *          framewidth: 100,
-     *          frameheight: 50
-     *       });
-     *    }
-     *
-     *    // output something in the console
-     *    // when the object is clicked
-     *    onClick(event) {
-     *       console.log("clicked!");
-     *       // don't propagate the event
-     *       return false;
-     *    }
-     * });
-     *
-     * // add the object at pos (10,10)
-     * world.addChild(new myButton(10,10));
+     * note the sprite's size and anchor the element now fits
+     * @ignore
      */
-    constructor(x: number, y: number, settings: {
-        image: any;
-        [key: string]: any;
-    });
+    private rememberFit;
     /**
-     * function called when the object is pressed (to be extended)
-     * @param _event - the event object
-     * @returns return false if we need to stop propagating the event
+     * update the sprite, its animation included, and follow its frame
+     * @param dt - the time since the last update, in milliseconds
+     * @returns whether anything changed
+     * @ignore
      */
-    onClick(_event?: Pointer): boolean;
+    update(dt: number): boolean;
     /**
-     * function called when the pointer is over the object.
-     *
-     * Fires once, on the frame the pointer crosses into the element. To stay
-     * opaque for as long as the pointer rests on it, an element also wants a
-     * `"pointermove"` callback registered through
-     * {@link input.registerPointerEvent} returning `false`, since by then the
-     * pointer is already inside and this no longer runs.
-     * @param _event - the event object
-     * @returns return false if we need to stop propagating the event, so that an
-     * element covered by this one does not also light up on hover
+     * A shortcut for `sprite.addAnimation(...)`: see
+     * {@link Sprite#addAnimation}.
+     * @param name - the animation name
+     * @param index - the frames, by index or region name
+     * @param animationspeed - the time between frames, in milliseconds
+     * @returns the number of frames added
      */
-    onOver(_event?: Pointer): boolean | void;
+    addAnimation(name: string, index: number[] | string[] | object[], animationspeed?: number): number;
     /**
-     * function called when the pointer is leaving the object area.
-     *
-     * Fires when the pointer leaves the element's bounds, and also when it is
-     * still inside them but something drawn above has consumed the move, since
-     * the pointer is then over that instead.
-     *
-     * Unlike {@link UISpriteElement#onOver} this one cannot consume the event, on
-     * purpose: an element that suppressed its own leave would stay in its hover
-     * state after the pointer had gone.
-     * @param _event - the event object
+     * A shortcut for `sprite.setCurrentAnimation(...)`: see
+     * {@link Sprite#setCurrentAnimation}.
+     * @param name - the animation to play
+     * @param resetAnim - what to do at the end, see {@link Sprite#setCurrentAnimation}
+     * @param preserve_dt - keep the time already spent on the current frame
+     * @returns this element
      */
-    onOut(_event?: Pointer): void;
+    setCurrentAnimation(name: string, resetAnim?: any, preserve_dt?: boolean): this;
     /**
-     * function called when the object is pressed and released (to be extended)
-     * @param _event - the event object
-     * @returns return false if we need to stop propagating the event
+     * A shortcut for `sprite.isCurrentAnimation(name)`.
+     * @param name - the animation name
+     * @returns whether it is the one playing
      */
-    onRelease(_event?: Pointer): boolean;
+    isCurrentAnimation(name: string): boolean;
     /**
-     * function called when the object is pressed and held<br>
-     * to be extended <br>
+     * draw the image, at half opacity while disabled
+     * @param renderer - the renderer
+     * @param viewport - the camera being drawn through
+     * @ignore
      */
-    onHold(): void;
+    draw(renderer: Renderer, viewport?: Camera2d): void;
 }
 //# sourceMappingURL=uispriteelement.d.ts.map

package/build/renderable/ui/uispriteelement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uispriteelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uispriteelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AAEpD,OAAO,MAAM,MAAM,gBAAgB,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,MAAM;IAClD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IAGf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBAEF,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE;IAyC7C;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAelC;;;;;;;;;;;OAWG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAgBxC;;;;;;;;;;;OAWG;IAEH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAmB7B;;;;OAIG;IAEH,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAkBpC;;;OAGG;IACH,MAAM,IAAI,IAAI;CAyCd"}
+{"version":3,"file":"uispriteelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uispriteelement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,MAAM,MAAM,gBAAgB,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACrC;;;;OAIG;IACH,KAAK,EAAE,GAAG,CAAC;IACX;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB,GAAG,eAAe,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,aAAa;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IAExD;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,uBAAuB;IAwBnE;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO/B;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAsBnB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;;OAKG;IACM,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAMpC;;;;;;;OAOG;IACH,YAAY,CACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,EACrC,cAAc,CAAC,EAAE,MAAM,GACrB,MAAM;IAIT;;;;;;;OAOG;IACH,mBAAmB,CAClB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,GAAG,EACf,WAAW,UAAQ,GACjB,IAAI;IAOP;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;;OAKG;IACM,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI;CAU5D"}