melonjs 20.11.0 → 20.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/README.md +3 -1
  2. package/build/application/application.d.ts.map +1 -1
  3. package/build/application/settings.d.ts +6 -2
  4. package/build/application/settings.d.ts.map +1 -1
  5. package/build/audio/backend/sound.d.ts.map +1 -1
  6. package/build/audio/playback.d.ts.map +1 -1
  7. package/build/audio/spatial.d.ts +13 -2
  8. package/build/audio/spatial.d.ts.map +1 -1
  9. package/build/audio/types.d.ts +25 -3
  10. package/build/audio/types.d.ts.map +1 -1
  11. package/build/camera/camera2d.d.ts +2 -0
  12. package/build/camera/camera2d.d.ts.map +1 -1
  13. package/build/camera/camera3d.d.ts.map +1 -1
  14. package/build/camera/effects/fade_effect.d.ts.map +1 -1
  15. package/build/camera/effects/pixelate_transition_effect.d.ts +67 -0
  16. package/build/camera/effects/pixelate_transition_effect.d.ts.map +1 -0
  17. package/build/geometries/ellipse.d.ts +11 -4
  18. package/build/geometries/ellipse.d.ts.map +1 -1
  19. package/build/geometries/line.d.ts +2 -2
  20. package/build/geometries/line.d.ts.map +1 -1
  21. package/build/geometries/polygon.d.ts +5 -4
  22. package/build/geometries/polygon.d.ts.map +1 -1
  23. package/build/geometries/rectangle.d.ts +2 -2
  24. package/build/geometries/rectangle.d.ts.map +1 -1
  25. package/build/geometries/roundrect.d.ts +2 -2
  26. package/build/geometries/roundrect.d.ts.map +1 -1
  27. package/build/index.d.ts +14 -2
  28. package/build/index.d.ts.map +1 -1
  29. package/build/index.js +12716 -7233
  30. package/build/index.js.map +4 -4
  31. package/build/input/gamepad.d.ts.map +1 -1
  32. package/build/input/pointerevent.d.ts.map +1 -1
  33. package/build/lang/console.d.ts +16 -1
  34. package/build/lang/console.d.ts.map +1 -1
  35. package/build/level/tiled/TMXLayer.d.ts +48 -14
  36. package/build/level/tiled/TMXLayer.d.ts.map +1 -1
  37. package/build/level/tiled/TMXTileMap.d.ts +1 -1
  38. package/build/level/tiled/TMXTileMap.d.ts.map +1 -1
  39. package/build/level/tiled/TMXTileset.d.ts.map +1 -1
  40. package/build/level/tiled/TMXUtils.d.ts.map +1 -1
  41. package/build/level/tiled/renderer/TMXHexagonalRenderer.d.ts.map +1 -1
  42. package/build/level/tiled/renderer/TMXIsometricRenderer.d.ts.map +1 -1
  43. package/build/level/tiled/renderer/TMXObliqueRenderer.d.ts.map +1 -1
  44. package/build/level/tiled/renderer/TMXOrthogonalRenderer.d.ts.map +1 -1
  45. package/build/level/tiled/renderer/TMXRenderer.d.ts +1 -1
  46. package/build/level/tiled/renderer/TMXRenderer.d.ts.map +1 -1
  47. package/build/level/tiled/renderer/TMXStaggeredRenderer.d.ts.map +1 -1
  48. package/build/loader/loader.d.ts +55 -11
  49. package/build/loader/loader.d.ts.map +1 -1
  50. package/build/loader/loadingscreen.d.ts.map +1 -1
  51. package/build/math/color.d.ts.map +1 -1
  52. package/build/math/math.d.ts +6 -1
  53. package/build/math/math.d.ts.map +1 -1
  54. package/build/math/matrix2d.d.ts +3 -2
  55. package/build/math/matrix2d.d.ts.map +1 -1
  56. package/build/math/matrix3d.d.ts +4 -1
  57. package/build/math/matrix3d.d.ts.map +1 -1
  58. package/build/math/observableVector2d.d.ts +6 -6
  59. package/build/math/observableVector2d.d.ts.map +1 -1
  60. package/build/math/observableVector3d.d.ts +8 -8
  61. package/build/math/observableVector3d.d.ts.map +1 -1
  62. package/build/particles/emitter.d.ts +15 -3
  63. package/build/particles/emitter.d.ts.map +1 -1
  64. package/build/particles/particle.d.ts +6 -0
  65. package/build/particles/particle.d.ts.map +1 -1
  66. package/build/particles/settings.d.ts +22 -5
  67. package/build/particles/settings.d.ts.map +1 -1
  68. package/build/physics/bounds.d.ts +5 -5
  69. package/build/physics/bounds.d.ts.map +1 -1
  70. package/build/physics/builtin/body.d.ts +15 -4
  71. package/build/physics/builtin/body.d.ts.map +1 -1
  72. package/build/physics/builtin/builtin-adapter.d.ts.map +1 -1
  73. package/build/physics/builtin/detector.d.ts.map +1 -1
  74. package/build/physics/builtin/raycast.d.ts.map +1 -1
  75. package/build/physics/world.d.ts.map +1 -1
  76. package/build/renderable/animation.d.ts +6 -1
  77. package/build/renderable/animation.d.ts.map +1 -1
  78. package/build/renderable/container.d.ts +40 -6
  79. package/build/renderable/container.d.ts.map +1 -1
  80. package/build/renderable/entity/entity.d.ts.map +1 -1
  81. package/build/renderable/frameAnimation.d.ts.map +1 -1
  82. package/build/renderable/imagelayer.d.ts.map +1 -1
  83. package/build/renderable/instanced_mesh.d.ts.map +1 -1
  84. package/build/renderable/mesh.d.ts.map +1 -1
  85. package/build/renderable/renderable.d.ts.map +1 -1
  86. package/build/renderable/sprite.d.ts +8 -2
  87. package/build/renderable/sprite.d.ts.map +1 -1
  88. package/build/renderable/text/bitmaptext.d.ts +12 -3
  89. package/build/renderable/text/bitmaptext.d.ts.map +1 -1
  90. package/build/renderable/text/text.d.ts +147 -4
  91. package/build/renderable/text/text.d.ts.map +1 -1
  92. package/build/renderable/text/textmetrics.d.ts +10 -2
  93. package/build/renderable/text/textmetrics.d.ts.map +1 -1
  94. package/build/renderable/text/textstyle.d.ts.map +1 -1
  95. package/build/renderable/trail3d.d.ts.map +1 -1
  96. package/build/renderable/ui/panelpaint.d.ts +5 -1
  97. package/build/renderable/ui/panelpaint.d.ts.map +1 -1
  98. package/build/renderable/ui/progressbar.d.ts +267 -95
  99. package/build/renderable/ui/progressbar.d.ts.map +1 -1
  100. package/build/renderable/ui/uibaseelement.d.ts +436 -50
  101. package/build/renderable/ui/uibaseelement.d.ts.map +1 -1
  102. package/build/renderable/ui/uicheckbox.d.ts +383 -0
  103. package/build/renderable/ui/uicheckbox.d.ts.map +1 -0
  104. package/build/renderable/ui/uifocus.d.ts +6 -0
  105. package/build/renderable/ui/uifocus.d.ts.map +1 -0
  106. package/build/renderable/ui/uilabel.d.ts +31 -0
  107. package/build/renderable/ui/uilabel.d.ts.map +1 -0
  108. package/build/renderable/ui/uipanel.d.ts +589 -116
  109. package/build/renderable/ui/uipanel.d.ts.map +1 -1
  110. package/build/renderable/ui/uiskin.d.ts +25 -0
  111. package/build/renderable/ui/uiskin.d.ts.map +1 -0
  112. package/build/renderable/ui/uislider.d.ts +518 -0
  113. package/build/renderable/ui/uislider.d.ts.map +1 -0
  114. package/build/renderable/ui/uispriteelement.d.ts +161 -85
  115. package/build/renderable/ui/uispriteelement.d.ts.map +1 -1
  116. package/build/renderable/ui/uitextbutton.d.ts +369 -63
  117. package/build/renderable/ui/uitextbutton.d.ts.map +1 -1
  118. package/build/state/stage.d.ts +3 -2
  119. package/build/state/stage.d.ts.map +1 -1
  120. package/build/state/state.d.ts +31 -6
  121. package/build/state/state.d.ts.map +1 -1
  122. package/build/system/legacy_pool.d.ts.map +1 -1
  123. package/build/system/pool.d.ts.map +1 -1
  124. package/build/system/save.d.ts +2 -1
  125. package/build/system/save.d.ts.map +1 -1
  126. package/build/tweens/tween.d.ts +5 -2
  127. package/build/tweens/tween.d.ts.map +1 -1
  128. package/build/utils/fetchdata.d.ts.map +1 -1
  129. package/build/video/canvas/canvas_renderer.d.ts +1 -5
  130. package/build/video/canvas/canvas_renderer.d.ts.map +1 -1
  131. package/build/video/effects/bloom.d.ts +3 -2
  132. package/build/video/effects/bloom.d.ts.map +1 -1
  133. package/build/video/effects/blur.d.ts +1 -1
  134. package/build/video/effects/chromaticAberration.d.ts +1 -1
  135. package/build/video/effects/dissolve.d.ts.map +1 -1
  136. package/build/video/effects/dropShadow.d.ts +1 -1
  137. package/build/video/effects/glow.d.ts +1 -1
  138. package/build/video/effects/glsl_realization.d.ts.map +1 -1
  139. package/build/video/effects/hologram.d.ts.map +1 -1
  140. package/build/video/effects/local_space.d.ts +19 -0
  141. package/build/video/effects/local_space.d.ts.map +1 -0
  142. package/build/video/effects/mesh_splice.d.ts.map +1 -1
  143. package/build/video/effects/outline.d.ts +1 -1
  144. package/build/video/effects/pixelate.d.ts +1 -1
  145. package/build/video/effects/radialGradient.d.ts +4 -12
  146. package/build/video/effects/radialGradient.d.ts.map +1 -1
  147. package/build/video/effects/scanline.d.ts.map +1 -1
  148. package/build/video/effects/shadereffect.d.ts.map +1 -1
  149. package/build/video/effects/shine.d.ts +5 -0
  150. package/build/video/effects/shine.d.ts.map +1 -1
  151. package/build/video/effects/sway.d.ts +9 -4
  152. package/build/video/effects/sway.d.ts.map +1 -1
  153. package/build/video/effects/vignette.d.ts.map +1 -1
  154. package/build/video/effects/wave.d.ts +9 -7
  155. package/build/video/effects/wave.d.ts.map +1 -1
  156. package/build/video/effects/wgsl/parse.d.ts.map +1 -1
  157. package/build/video/effects/wgsl/scaffold.d.ts.map +1 -1
  158. package/build/video/effects/wgsl_realization.d.ts.map +1 -1
  159. package/build/video/renderer.d.ts +22 -5
  160. package/build/video/renderer.d.ts.map +1 -1
  161. package/build/video/renderstate.d.ts +26 -3
  162. package/build/video/renderstate.d.ts.map +1 -1
  163. package/build/video/rendertarget/webgpurendertarget.d.ts +1 -0
  164. package/build/video/rendertarget/webgpurendertarget.d.ts.map +1 -1
  165. package/build/video/texture/atlas.d.ts +31 -31
  166. package/build/video/texture/atlas.d.ts.map +1 -1
  167. package/build/video/utils/pixel_snap.d.ts +44 -0
  168. package/build/video/utils/pixel_snap.d.ts.map +1 -0
  169. package/build/video/utils/tessellation.d.ts +11 -0
  170. package/build/video/utils/tessellation.d.ts.map +1 -1
  171. package/build/video/webgl/batchers/lit_quad_batcher.d.ts.map +1 -1
  172. package/build/video/webgl/batchers/mesh_batcher.d.ts.map +1 -1
  173. package/build/video/webgl/batchers/quad_batcher.d.ts +2 -1
  174. package/build/video/webgl/batchers/quad_batcher.d.ts.map +1 -1
  175. package/build/video/webgl/renderers/tmxlayer/orthogonal.d.ts.map +1 -1
  176. package/build/video/webgl/webgl_renderer.d.ts +3 -6
  177. package/build/video/webgl/webgl_renderer.d.ts.map +1 -1
  178. package/build/video/webgpu/batchers/mesh_batcher.d.ts +0 -1
  179. package/build/video/webgpu/batchers/mesh_batcher.d.ts.map +1 -1
  180. package/build/video/webgpu/batchers/primitive_batcher.d.ts.map +1 -1
  181. package/build/video/webgpu/batchers/quad_batcher.d.ts.map +1 -1
  182. package/build/video/webgpu/effect_binding.d.ts.map +1 -1
  183. package/build/video/webgpu/renderers/tmxlayer/orthogonal.d.ts.map +1 -1
  184. package/build/video/webgpu/webgpu_renderer.d.ts +6 -10
  185. package/build/video/webgpu/webgpu_renderer.d.ts.map +1 -1
  186. package/package.json +1 -1
  187. package/skills/AGENTS.md +2 -1
  188. package/skills/melonjs/SKILL.md +3 -2
  189. package/skills/melonjs-audio/SKILL.md +31 -8
  190. package/skills/melonjs-camera-and-drawing/SKILL.md +41 -1
  191. package/skills/melonjs-display-and-scaling/SKILL.md +19 -5
  192. package/skills/melonjs-effects-and-shaders/SKILL.md +53 -17
  193. package/skills/melonjs-events/SKILL.md +3 -1
  194. package/skills/melonjs-getting-started/SKILL.md +1 -2
  195. package/skills/melonjs-input/SKILL.md +61 -3
  196. package/skills/melonjs-lighting/SKILL.md +4 -3
  197. package/skills/melonjs-loading-assets/SKILL.md +57 -15
  198. package/skills/melonjs-math/SKILL.md +14 -3
  199. package/skills/melonjs-particles-and-trails/SKILL.md +72 -8
  200. package/skills/melonjs-performance/SKILL.md +3 -0
  201. package/skills/melonjs-physics/SKILL.md +53 -4
  202. package/skills/melonjs-plugins/SKILL.md +25 -1
  203. package/skills/melonjs-renderables/SKILL.md +11 -3
  204. package/skills/melonjs-renderer-backends/SKILL.md +2 -2
  205. package/skills/melonjs-scenes-and-state/SKILL.md +32 -2
  206. package/skills/melonjs-sprites-and-animation/SKILL.md +14 -0
  207. package/skills/melonjs-tilemaps/SKILL.md +96 -2
  208. package/skills/melonjs-ui-and-text/SKILL.md +560 -23
@@ -1,20 +1,165 @@
1
1
  import type Pointer from "./../../input/pointer.ts";
2
2
  import type { Vector2d } from "../../math/vector2d.ts";
3
+ import type Renderer from "../../video/renderer.js";
3
4
  import Container from "../container.js";
5
+ import type { UINavAction } from "./uifocus.ts";
4
6
  /**
5
- * This is a basic clickable and draggable container which you can use in your game UI.
6
- * Use this for example if you want to display a panel that contains text, images or other UI elements.
7
+ * The bounce settings every built-in widget takes in its settings object:
8
+ * a small grow under the pointer and a squash while held. Only the drawing
9
+ * scales; the hit area and the layout stay as they are. See
10
+ * {@link UIBaseElement#hoverScale}.
11
+ * @category UI
12
+ * @example
13
+ * // a button that grows 5% under the pointer and squashes while held
14
+ * const play = new UITextButton(100, 200, {
15
+ * text: "Play",
16
+ * hoverScale: 1.05,
17
+ * pressScale: 0.92,
18
+ * });
19
+ */
20
+ export interface UIJuiceSettings {
21
+ /**
22
+ * The scale the widget is drawn at under the pointer, or while it has
23
+ * the keyboard and gamepad focus, such as `1.05`. `1` turns it off.
24
+ * @default 1
25
+ */
26
+ hoverScale?: number;
27
+ /**
28
+ * The scale the widget is drawn at while held down, such as `0.92`.
29
+ * `1` turns it off.
30
+ * @default 1
31
+ */
32
+ pressScale?: number;
33
+ }
34
+ /**
35
+ * A clickable, draggable container: the base every UI widget builds on
36
+ * ({@link UITextButton}, {@link UICheckbox}, {@link UISlider},
37
+ * {@link UIPanel}, {@link UISpriteElement}). Extend it to make a widget of your own; it can hold
38
+ * other renderables as children.
39
+ *
40
+ * It uses screen coordinates (`floating` is `true`), so it stays put when
41
+ * the camera moves. Children added to it should keep `floating` at `false`.
42
+ *
43
+ * ## Pointer callbacks
44
+ * Override these in a subclass:
45
+ * - {@link UIBaseElement#onClick}: the pointer went DOWN on the element
46
+ * (or Enter / A with the focus here). It is a press, not a completed click.
47
+ * - {@link UIBaseElement#onRelease}: the press ended: the pointer came up,
48
+ * left the element while held, or the browser cancelled it.
49
+ * - {@link UIBaseElement#onOver} / {@link UIBaseElement#onOut}: the pointer
50
+ * came in / went out. `hover` is `true` in between.
51
+ * - {@link UIBaseElement#onHold}: held for `holdThreshold` ms, when
52
+ * `isHoldable` is set.
53
+ * - {@link UIBaseElement#onCancel}: the press was called off without a
54
+ * release (see {@link UIBaseElement#cancelPress}), as when the element is
55
+ * removed while held.
7
56
  *
8
- * Regions under the pointer are asked in the order they are drawn, topmost
9
- * first, and the walk carries on downwards until a handler returns `false`. An
10
- * element that can overlap another one is therefore not opaque until it says
11
- * so: by default a widget it covers still answers clicks and still lights up on
12
- * hover. {@link UIBaseElement#onClick}, {@link UIBaseElement#onRelease} and
13
- * {@link UIBaseElement#onOver} each consume by returning `false`.
57
+ * Elements under the pointer are asked topmost first, and the event carries
58
+ * on to the ones below until a handler returns `false`. `onClick` and
59
+ * `onRelease` return `false` by default, so a press on a UI element stops
60
+ * there: a button over the game does not also click the world behind it.
61
+ * Return `true` from them to let the press through as well. Hover is not
62
+ * stopped by default: return `false` from `onOver` for that.
63
+ *
64
+ * ## Turning it off
65
+ * Set {@link UIBaseElement#enabled} to `false`: it stops answering the
66
+ * pointer, the keys and the pad, and a press in progress is called off.
67
+ *
68
+ * ## Dragging
69
+ * Set {@link UIBaseElement#isDraggable}: the element then follows the
70
+ * pointer while held. `onClick` is the pick-up, {@link UIBaseElement#onMove}
71
+ * runs on each move, and `onRelease` is the drop. Inside a scrolling
72
+ * {@link UIPanel}, a drag that starts on a widget scrolls the panel instead;
73
+ * set {@link UIBaseElement#keepsDrag} on a widget that is dragged itself.
74
+ *
75
+ * ## Bounce
76
+ * {@link UIBaseElement#hoverScale} and {@link UIBaseElement#pressScale}
77
+ * scale the drawing under the pointer and while held, easing there and back.
78
+ * The hit area and the layout do not change.
79
+ *
80
+ * ## Keyboard and gamepad focus
81
+ * For a game played without a mouse or a touch screen. Nothing listens until
82
+ * a widget takes the focus with {@link UIBaseElement#focus}; until then the
83
+ * arrow keys and the pad are left to the game. With a widget focused:
84
+ * - the arrow keys or the D-pad move the focus to the nearest
85
+ * {@link UIBaseElement#focusable} widget that way, measured edge to edge;
86
+ * - Enter, Space or the pad's A button press the focused widget, as a click
87
+ * does;
88
+ * - a ring in {@link UIBaseElement.focusRingColor} shows the focus while the
89
+ * keyboard or a pad is used, and hides when the mouse moves;
90
+ * - a focused widget inside a scrolling {@link UIPanel} is scrolled into view;
91
+ * - {@link UIBaseElement#blur}, or removing the widget, gives the keys and
92
+ * the pad back to the game.
93
+ *
94
+ * The built-in widgets are focusable. A widget of your own sets `focusable`
95
+ * and can override {@link UIBaseElement#onNavigate} to use the arrows itself.
14
96
  * @category UI
15
97
  * @example
16
- * // a panel that is opaque to the pointer and comes to the front when picked
17
- * class Panel extends UIBaseElement {
98
+ * // a widget of your own: draws itself, bounces, and acts on release
99
+ * import { UIBaseElement } from "melonjs";
100
+ *
101
+ * class Card extends UIBaseElement {
102
+ * constructor(x, y) {
103
+ * super(x, y, 120, 160);
104
+ * this.focusable = true; // reachable with the arrow keys and the pad
105
+ * this.hoverScale = 1.05;
106
+ * this.pressScale = 0.95;
107
+ * }
108
+ * draw(renderer, viewport) {
109
+ * renderer.setColor(this.hover ? "#ffffff" : "#cccccc");
110
+ * renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
111
+ * super.draw(renderer, viewport); // draws the children
112
+ * }
113
+ * onRelease() {
114
+ * console.log("card picked");
115
+ * return false; // stop the event here (the default)
116
+ * }
117
+ * }
118
+ *
119
+ * app.world.addChild(new Card(50, 50));
120
+ * @example
121
+ * // a token dragged around and snapped to a 32 pixel grid when dropped
122
+ * import { UIBaseElement, Sprite } from "melonjs";
123
+ *
124
+ * class Token extends UIBaseElement {
125
+ * constructor(x, y) {
126
+ * super(x, y, 64, 64);
127
+ * this.isDraggable = true;
128
+ * // a sprite is centred on its position by default
129
+ * this.addChild(new Sprite(32, 32, { image: "token" }));
130
+ * }
131
+ * onMove() {
132
+ * // runs on each move while dragged: this.pos follows the pointer
133
+ * }
134
+ * onRelease() {
135
+ * this.pos.x = Math.round(this.pos.x / 32) * 32;
136
+ * this.pos.y = Math.round(this.pos.y / 32) * 32;
137
+ * return false;
138
+ * }
139
+ * }
140
+ * @example
141
+ * // a menu played with the keyboard or a pad: start on the first button
142
+ * import { UITextButton, state } from "melonjs";
143
+ *
144
+ * const play = new UITextButton(100, 200, {
145
+ * text: "Play",
146
+ * onClick: () => state.change(state.PLAY),
147
+ * });
148
+ * const quit = new UITextButton(100, 260, {
149
+ * text: "Quit",
150
+ * onClick: () => state.change(state.MENU),
151
+ * });
152
+ * app.world.addChild(play);
153
+ * app.world.addChild(quit);
154
+ * // the arrows / D-pad now move between them, Enter / Space / A press;
155
+ * // the mouse still works as before
156
+ * play.focus();
157
+ * @example
158
+ * // a panel that is opaque to hover too, and comes to the front when picked
159
+ * // (UIPanel does this with its `blocking` setting)
160
+ * import { UIBaseElement, input } from "melonjs";
161
+ *
162
+ * class Dialog extends UIBaseElement {
18
163
  * onClick() {
19
164
  * this.ancestor.moveToTop(this);
20
165
  * return false;
@@ -27,107 +172,348 @@ import Container from "../container.js";
27
172
  * // `onOver` no longer fires
28
173
  * onActivateEvent() {
29
174
  * super.onActivateEvent();
30
- * me.input.registerPointerEvent("pointermove", this, () => false);
175
+ * input.registerPointerEvent("pointermove", this, () => false);
31
176
  * }
32
177
  * onDeactivateEvent() {
33
- * me.input.releasePointerEvent("pointermove", this);
178
+ * input.releasePointerEvent("pointermove", this);
34
179
  * super.onDeactivateEvent();
35
180
  * }
36
181
  * }
37
182
  */
38
183
  export default class UIBaseElement extends Container {
39
184
  /**
40
- * UI base elements use screen coordinates by default
41
- * (Note: any child elements added to a UIBaseElement should have their floating property to false)
185
+ * UI elements use screen coordinates by default, so they stay put when
186
+ * the camera moves. Children added to a UIBaseElement should keep their
187
+ * own `floating` at `false`.
42
188
  * @see Renderable.floating
43
189
  * @default true
44
190
  */
45
191
  floating: boolean;
46
192
  /**
47
- * object can be clicked or not
193
+ * Whether the pointer can press the element. The low-level flag under
194
+ * {@link UIBaseElement#enabled}: prefer `enabled`, which also calls off a
195
+ * press in progress, blocks the keys and the pad, and draws a built-in
196
+ * widget disabled.
48
197
  * @default true
49
198
  */
50
199
  isClickable: boolean;
51
200
  /**
52
- * object can be dragged or not
201
+ * Whether the element follows the pointer while held. `onClick` runs on
202
+ * the pick-up, {@link UIBaseElement#onMove} on each move and `onRelease`
203
+ * on the drop.
53
204
  * @default false
54
205
  */
55
206
  isDraggable: boolean;
56
207
  /**
57
- * Tap and hold threshold timeout in ms
208
+ * How long a press must be held before {@link UIBaseElement#onHold}
209
+ * runs, in milliseconds. Needs `isHoldable`.
58
210
  * @default 250
59
211
  */
60
212
  holdThreshold: number;
61
213
  /**
62
- * object can be tap and hold
214
+ * Whether a press held for `holdThreshold` ms calls
215
+ * {@link UIBaseElement#onHold}.
63
216
  * @default false
64
217
  */
65
218
  isHoldable: boolean;
66
219
  /**
67
- * true if the pointer is over the object
220
+ * `true` while the pointer is over the element. A tap on a touch screen
221
+ * does not set it. Cleared when the element is removed, so one added back
222
+ * later is not drawn lit until the pointer comes over it again.
68
223
  * @default false
69
224
  */
70
225
  hover: boolean;
71
226
  /**
72
- * false if the pointer is down, or true when the pointer status is up
227
+ * `false` while the element is held down (by the pointer, or by Enter /
228
+ * A with the focus), `true` otherwise. Removing a held element calls the
229
+ * press off (see {@link UIBaseElement#cancelPress}), so it is `true` again
230
+ * once out of the scene.
73
231
  * @default true
74
232
  */
75
233
  released: boolean;
234
+ /**
235
+ * the tap-and-hold timer of a press in progress, or -1
236
+ * @ignore
237
+ */
76
238
  holdTimeout: number;
239
+ /**
240
+ * While dragged: where the element was grabbed, relative to its
241
+ * position. `undefined` otherwise.
242
+ */
77
243
  grabOffset: Vector2d | undefined;
78
244
  /**
79
- * @param x - The x position of the container
80
- * @param y - The y position of the container
81
- * @param w - width of the container
82
- * @param h - height of the container
245
+ * @param x - the x position of the element, in screen pixels
246
+ * @param y - the y position of the element, in screen pixels
247
+ * @param w - the width of the element, in pixels
248
+ * @param h - the height of the element, in pixels
83
249
  */
84
250
  constructor(x: number, y: number, w?: number, h?: number);
85
251
  /**
86
- * function called when the object is pressed (to be extended)
87
- * @param _event - the event object
88
- * @returns return false if we need to stop propagating the event
252
+ * Whether a drag that starts on this element belongs to it.
253
+ *
254
+ * When `false`, a drag that starts on the element inside a scrolling
255
+ * {@link UIPanel} scrolls the panel and calls off the press. Set it on a
256
+ * widget that handles its own drags, such as a knob or a colour picker,
257
+ * as {@link UISlider} does. An `isDraggable` element keeps its drags
258
+ * anyway.
259
+ * @default false
260
+ * @example
261
+ * // a colour wheel that reads drags itself, inside a scrolling panel
262
+ * class ColourWheel extends UIBaseElement {
263
+ * constructor(x, y) {
264
+ * super(x, y, 128, 128);
265
+ * this.keepsDrag = true;
266
+ * }
267
+ * }
268
+ */
269
+ keepsDrag: boolean;
270
+ /**
271
+ * The scale the widget is drawn at under the pointer, or while it shows
272
+ * the focus ring: a little bounce, such as `1.05`. `1` turns it off.
273
+ *
274
+ * Only the drawing scales, about the widget's centre. Its hit area and
275
+ * its place in a layout stay the same, so the widgets around it do not
276
+ * move. The scale eases there and back by itself (about 0.2 s). A
277
+ * disabled widget does not grow.
278
+ * @default 1
279
+ * @example
280
+ * button.hoverScale = 1.05;
281
+ * button.pressScale = 0.92;
282
+ */
283
+ hoverScale: number;
284
+ /**
285
+ * The scale the widget is drawn at while held down, such as `0.92`.
286
+ * `1` turns it off. Drawing only, as {@link UIBaseElement#hoverScale}.
287
+ * @default 1
288
+ */
289
+ pressScale: number;
290
+ /**
291
+ * Whether this element can take the keyboard and gamepad focus: see
292
+ * {@link UIBaseElement#focus}. The built-in buttons, checkboxes and
293
+ * sliders set it; set it on a widget of your own to make it reachable.
294
+ * A disabled or hidden element is skipped.
295
+ * @default false
296
+ */
297
+ focusable: boolean;
298
+ /**
299
+ * The colour of the ring drawn around the element with the focus, for
300
+ * every element. Any CSS colour.
301
+ * @default "#ffcc33"
302
+ * @example
303
+ * UIBaseElement.focusRingColor = "#00e0ff";
304
+ */
305
+ static focusRingColor: string;
306
+ /**
307
+ * The element with the keyboard and gamepad focus, or `undefined` when
308
+ * none has it.
309
+ * @example
310
+ * // give the focus back to the menu if nothing has it
311
+ * if (UIBaseElement.focusOwner === undefined) {
312
+ * playButton.focus();
313
+ * }
314
+ */
315
+ static get focusOwner(): UIBaseElement | undefined;
316
+ /** `true` while this element has the keyboard and gamepad focus */
317
+ get focused(): boolean;
318
+ /**
319
+ * Take the keyboard and gamepad focus, for a game played without a mouse
320
+ * or a touch screen. Call it once the element is in the scene.
321
+ *
322
+ * Nothing has the focus until a game gives it to an element, and until
323
+ * then the arrow keys and the pad are left to the game. From then on:
324
+ * the arrows or the D-pad move the focus to the nearest focusable element
325
+ * that way; Enter, Space or the pad's A button press the focused one as a
326
+ * click does (a slider steps on left and right instead). The focus ring
327
+ * shows, and hides again while the mouse is used. A focused element in a
328
+ * scrolling panel is scrolled into view.
329
+ *
330
+ * Does nothing on an element that is not `focusable`.
331
+ * @example
332
+ * // a menu played with the keyboard or a pad: start on Play
333
+ * app.world.addChild(playButton);
334
+ * app.world.addChild(optionsButton);
335
+ * playButton.focus();
336
+ * @example
337
+ * // a pause menu in a panel: focus its first button when it opens
338
+ * panel.addChild(resumeButton);
339
+ * panel.addChild(quitButton);
340
+ * app.world.addChild(panel);
341
+ * resumeButton.focus();
342
+ */
343
+ focus(): void;
344
+ /**
345
+ * Give up the focus, if this element has it. With nothing focused, the
346
+ * arrow keys and the pad go back to the game. Removing the element from
347
+ * the scene does the same.
348
+ * @example
349
+ * // leaving the menu for the game: the arrows move the player again
350
+ * UIBaseElement.focusOwner?.blur();
351
+ */
352
+ blur(): void;
353
+ /**
354
+ * Called for an arrow key or a D-pad direction while this element has
355
+ * the focus. Return `true` to handle it yourself (the focus stays here),
356
+ * as a slider does to step. Return `false`, the default, to move the
357
+ * focus to the nearest widget that way.
358
+ *
359
+ * Enter, Space and A do not come here: they press the widget through
360
+ * {@link UIBaseElement#focusPress} and {@link UIBaseElement#focusRelease}.
361
+ * @param _action - which way: `"up"`, `"down"`, `"left"` or `"right"`
362
+ * @returns `true` when handled
363
+ * @example
364
+ * // a picker: left and right change the choice, up and down move on
365
+ * class Picker extends UIBaseElement {
366
+ * constructor(x, y, choices) {
367
+ * super(x, y, 160, 32);
368
+ * this.focusable = true;
369
+ * this.choices = choices;
370
+ * this.index = 0;
371
+ * }
372
+ * onNavigate(action) {
373
+ * if (action === "left" || action === "right") {
374
+ * const step = action === "right" ? 1 : -1;
375
+ * const n = this.choices.length;
376
+ * this.index = (this.index + step + n) % n;
377
+ * this.isDirty = true;
378
+ * return true;
379
+ * }
380
+ * return false;
381
+ * }
382
+ * }
383
+ */
384
+ onNavigate(_action: UINavAction): boolean;
385
+ /**
386
+ * Called when Enter, Space or A is pressed with the focus here: the
387
+ * widget goes down, as under the pointer, and `onClick` runs with no
388
+ * event. Override it only to change what accept does.
389
+ * @returns whether it went down: not when disabled, or already held
390
+ */
391
+ focusPress(): boolean;
392
+ /**
393
+ * Called when Enter, Space or A is let go after
394
+ * {@link UIBaseElement#focusPress}: the widget comes back up and
395
+ * `onRelease` runs with no event. The built-in widgets complete their
396
+ * action here, as on a click: a button calls its `onClick` setting, a
397
+ * checkbox toggles.
398
+ */
399
+ focusRelease(): void;
400
+ /**
401
+ * Ease the bounce.
402
+ * @param dt - time since the last frame, in milliseconds
403
+ * @returns whether it needs redrawing
404
+ */
405
+ update(dt: number): boolean;
406
+ /**
407
+ * Apply the bounce, and draw the focus ring, behind the widget.
408
+ *
409
+ * Here and not in `draw`: a container translates to its own position in
410
+ * `draw`, so from `preDraw` on, the widget and the ring share the
411
+ * parent's coordinates, whatever the widget does in its own `draw`.
412
+ * @param renderer - the renderer to draw with
413
+ */
414
+ preDraw(renderer: Renderer): void;
415
+ /**
416
+ * Whether the widget answers input: the switch to turn a widget off.
417
+ *
418
+ * Turning it off clears `isClickable`, calls off a press in progress
419
+ * (see {@link UIBaseElement#cancelPress}), and skips it in keyboard and
420
+ * gamepad navigation. The built-in widgets draw themselves disabled:
421
+ * their `disabled` skin region, or at half opacity. A widget of your own
422
+ * reads `enabled` in its `draw`.
423
+ *
424
+ * `isClickable` is the low-level flag underneath; setting it alone does
425
+ * not change `enabled` or the look.
426
+ * @default true
427
+ * @example
428
+ * // greyed out until a save exists
429
+ * continueButton.enabled = false;
430
+ * // ... later
431
+ * continueButton.enabled = true;
432
+ */
433
+ get enabled(): boolean;
434
+ set enabled(value: boolean);
435
+ /**
436
+ * Call off a press in progress, without calling `onRelease`:
437
+ * {@link UIBaseElement#onCancel} runs instead.
438
+ *
439
+ * The element goes back to its released look, and the pointer-up that
440
+ * follows does nothing. A scrolling {@link UIPanel} calls this when a drag
441
+ * that started on the element turns out to be a scroll, so a button
442
+ * dragged to scroll its list is not clicked. Setting `enabled` to `false`,
443
+ * losing the focus or the window losing focus while Enter or A is held,
444
+ * and removing the element while it is held call it too.
445
+ */
446
+ cancelPress(): void;
447
+ /**
448
+ * Called when a press is called off rather than completed: see
449
+ * {@link UIBaseElement#cancelPress}. Override it to undo what `onClick`
450
+ * started, such as a charge-up effect.
451
+ */
452
+ onCancel(): void;
453
+ /**
454
+ * Called when the element is pressed: the pointer went down on it, or
455
+ * Enter / Space / A with the focus here (then with no event). Override it
456
+ * in a subclass.
457
+ *
458
+ * This is the press, not a completed click: see
459
+ * {@link UIBaseElement#onRelease} for the end of it.
460
+ * @param _event - the pointer event, or `undefined` from the keyboard or
461
+ * the pad
462
+ * @returns `false`, the default, to stop the event here; `true` to let
463
+ * elements below get it too
89
464
  */
90
465
  onClick(_event?: Pointer): boolean;
91
466
  /**
92
- * function called when the pointer is moved over the object
93
- * @param _event - the event object
467
+ * Called on each pointer move while the element is dragged (see
468
+ * {@link UIBaseElement#isDraggable}), after `pos` has followed the
469
+ * pointer. Override it in a subclass.
470
+ * @param _event - the pointer event
94
471
  */
95
472
  onMove(_event?: Pointer): void;
96
473
  /**
97
- * function called when the pointer is over the object.
474
+ * Called when the pointer comes over the element. Override it in a
475
+ * subclass.
98
476
  *
99
477
  * Fires once, on the frame the pointer crosses into the element. To stay
100
- * opaque for as long as the pointer rests on it, an element also wants a
101
- * `"pointermove"` callback registered through
102
- * {@link input.registerPointerEvent} returning `false`, since by then the
103
- * pointer is already inside and this no longer runs.
104
- * @param _event - the event object
105
- * @returns return false if we need to stop propagating the event, so that an
106
- * element covered by this one does not also light up on hover
478
+ * opaque to hover for as long as the pointer rests on it, also register a
479
+ * `"pointermove"` callback through {@link input.registerPointerEvent}
480
+ * that returns `false` (see the class example).
481
+ * @param _event - the pointer event
482
+ * @returns `false` to stop the event here, so an element covered by this
483
+ * one does not also light up
107
484
  */
108
485
  onOver(_event?: Pointer): boolean | void;
109
486
  /**
110
- * function called when the pointer is leaving the object area.
487
+ * Called when the pointer leaves the element. Override it in a subclass.
111
488
  *
112
- * Fires when the pointer leaves the element's bounds, and also when it is
113
- * still inside them but something drawn above has consumed the move, since
114
- * the pointer is then over that instead.
489
+ * Also fires when the pointer is still inside but something drawn above
490
+ * has stopped the move, since the pointer is then over that instead. A
491
+ * press in progress ends first, through `onRelease`.
115
492
  *
116
- * Unlike {@link UIBaseElement#onOver} this one cannot consume the event, on
117
- * purpose: an element that suppressed its own leave would stay in its hover
118
- * state after the pointer had gone.
119
- * @param _event - the event object
493
+ * Unlike {@link UIBaseElement#onOver} it cannot stop the event: an
494
+ * element that skipped its own leave would stay lit after the pointer
495
+ * had gone.
496
+ * @param _event - the pointer event
120
497
  */
121
498
  onOut(_event?: Pointer): void;
122
499
  /**
123
- * function called when the object is pressed and released (to be extended)
124
- * @param _event - the event object
125
- * @returns return false if we need to stop propagating the event
500
+ * Called when a press ends. Override it in a subclass.
501
+ *
502
+ * It runs when the pointer comes up, but also when the pointer leaves the
503
+ * element while held, or the browser cancels the press: it is the end
504
+ * of a press, not proof of a completed click. (For a click that only
505
+ * counts when completed, use a {@link UITextButton} and its `onClick`
506
+ * setting.) A press called off by {@link UIBaseElement#cancelPress} does
507
+ * not come here.
508
+ * @param _event - the pointer event, or `undefined` from the keyboard or
509
+ * the pad
510
+ * @returns `false`, the default, to stop the event here; `true` to let
511
+ * elements below get it too
126
512
  */
127
513
  onRelease(_event?: Pointer): boolean;
128
514
  /**
129
- * function called when the object is pressed and held<br>
130
- * to be extended <br>
515
+ * Called once a press has been held for `holdThreshold` milliseconds,
516
+ * when `isHoldable` is set. Override it in a subclass.
131
517
  */
132
518
  onHold(): void;
133
519
  }
@@ -1 +1 @@
1
- {"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAAS;IACnD;;;;;OAKG;IACM,QAAQ,UAAQ;IAEzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;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;IAEf;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAGlB,WAAW,EAAE,MAAM,CAAC;IAGpB,UAAU,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEjC;;;;;OAKG;gBACS,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;IA+CxD;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAuClC;;;OAGG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAI9B;;;;;;;;;;;OAWG;IAEH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI;IAuBxC;;;;;;;;;;;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;CA4Dd"}
1
+ {"version":3,"file":"uibaseelement.d.ts","sourceRoot":"","sources":["../../../src/renderable/ui/uibaseelement.ts"],"names":[],"mappings":"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"}