|
1 | 1 | --- |
2 | 2 | name: melonjs-ui-and-text |
3 | | -description: "Use this skill for HUDs, buttons, menus, dialogue panels, progress bars and on-screen text in melonJS. Covers UIBaseElement/UISpriteElement/UITextButton, ProgressBar, UIPanel, Draggable and DropTarget, the floating screen-space container pattern, which of two overlapping panels gets the pointer, Text and BitmapText, web font loading, and NineSliceSprite panels. Triggers on: UI, HUD, button, UIBaseElement, UISpriteElement, UITextButton, ProgressBar, progress bar, health bar, gauge, Draggable, DropTarget, menu, dialogue, overlapping panels, moveToTop, onOver, onClick, bindKey, keyboard shortcut, button keyboard, Tween, easing, animate a label, wavy text, per-glyph effect, glyphEffect, shake text, rainbow text, Text, BitmapText, fillStyle, fillGradient, gradient text, tint, font, fontface, wordWrapWidth, NineSliceSprite, score display, floating., fullscreen, full screen, requestFullscreen, exitFullscreen, isFullscreen, fullscreen button, fullscreen option" |
| 3 | +description: "Use this skill for HUDs, buttons, menus, options screens, dialogue panels, progress bars and on-screen text in melonJS. Covers UIBaseElement/UISpriteElement/UITextButton, UICheckbox, UISlider, ProgressBar, UIPanel (skins, layout, scrolling), Draggable and DropTarget, the floating screen-space container pattern, which of two overlapping panels gets the pointer, Text and BitmapText, web font loading, and NineSliceSprite panels. Triggers on: UI, HUD, button, checkbox, radio button, UICheckbox, slider, UISlider, volume slider, options menu, settings screen, scrolling list, scroll panel, layout, column, grid, UI skin, UIBaseElement, UISpriteElement, UITextButton, ProgressBar, progress bar, health bar, gauge, Draggable, DropTarget, menu, dialogue, overlapping panels, moveToTop, onOver, onClick, bindKey, keyboard shortcut, button keyboard, Tween, easing, animate a label, wavy text, per-glyph effect, glyphEffect, shake text, rainbow text, Text, BitmapText, fillStyle, fillGradient, gradient text, tint, font, fontface, wordWrapWidth, NineSliceSprite, score display, floating., fullscreen, full screen, requestFullscreen, exitFullscreen, isFullscreen, fullscreen button, fullscreen option" |
4 | 4 | license: MIT |
5 | 5 | --- |
6 | 6 |
|
@@ -441,6 +441,79 @@ One consequence worth knowing: `getBounds()` on a bobbing panel answers |
441 | 441 | differently each frame, so do not cache it or compare two children's bounds |
442 | 442 | while a bob is running. |
443 | 443 |
|
| 444 | +### Panel art, title, dragging: `skin`, `title`, `draggable` |
| 445 | + |
| 446 | +```js |
| 447 | +const options = new UIPanel(20, 20, { |
| 448 | + width: 380, height: 460, |
| 449 | + // one atlas region, stretched as a nine-slice to the panel's size |
| 450 | + skin: { atlas, region: "grey_panel", insetx: 10, insety: 10 }, |
| 451 | + title: "OPTIONS", titleFont: "kenpixel", titleFontSize: 20, titleFillStyle: "black", |
| 452 | + draggable: true, // comes to the front when grabbed |
| 453 | +}); |
| 454 | +``` |
| 455 | + |
| 456 | +The title sits at the top and the content starts below it. `insetx` / |
| 457 | +`insety` are the unscaled corners of the art, and also where the frame ends: |
| 458 | +layout `padding` is measured from there. |
| 459 | + |
| 460 | +### Laying a panel out: `layout` |
| 461 | + |
| 462 | +Leave `layout` at `"none"` and children stay where you put them. Otherwise |
| 463 | +the panel places them, below the title and inside the frame: |
| 464 | + |
| 465 | +```js |
| 466 | +const menu = new UIPanel(x, y, { |
| 467 | + width: 360, height: 100, |
| 468 | + layout: "column", // "row", "grid" (with `columns`), or "none" |
| 469 | + padding: 16, // from the frame to the content |
| 470 | + gap: 12, // between children |
| 471 | + align: "stretch", // "start", "center", "end", or "stretch" |
| 472 | + autoSize: true, // grow the panel to fit |
| 473 | +}); |
| 474 | +menu.addChild(new UITextButton(0, 0, { text: "Play", onClick: play })); |
| 475 | +menu.addChild(new UITextButton(0, 0, { text: "Options", onClick: openOptions })); |
| 476 | +``` |
| 477 | + |
| 478 | +Children are laid out in the order they were added. It runs when a child is |
| 479 | +added or removed and when the panel is resized, **not every frame**: a child |
| 480 | +that changes size afterwards, a label whose text grew, needs |
| 481 | +`menu.relayout()`. `"stretch"` resizes children that have a `resize` method, |
| 482 | +which `UITextButton` and other containers do; a `Text` keeps its size. |
| 483 | + |
| 484 | +A row inside a column is a second panel that draws nothing and lets clicks |
| 485 | +through: `new UIPanel(0, 0, { width, height, layout: "row", blocking: false })`. |
| 486 | + |
| 487 | +### Scrolling lists: `scroll` |
| 488 | + |
| 489 | +```js |
| 490 | +const levels = new UIPanel(420, 435, { |
| 491 | + width: 340, height: 150, |
| 492 | + layout: "grid", columns: 5, gap: 8, padding: 10, |
| 493 | + scroll: "vertical", // "horizontal", "both", or "none" |
| 494 | +}); |
| 495 | +``` |
| 496 | + |
| 497 | +The content is cropped to the area inside the frame and below the title, and |
| 498 | +scrolls with the wheel over the panel and by dragging, with momentum when |
| 499 | +flung. A scrollbar shows while it does not fit. `scrollTo(x, y)`, |
| 500 | +`scrollToChild(child)`, `scrollX` / `scrollY`, `maxScrollX` / `maxScrollY` and |
| 501 | +an `onScroll(x, y, panel)` setting are there to drive it from code. |
| 502 | + |
| 503 | +What to know: |
| 504 | + |
| 505 | +- **Scrolling moves the children.** Their `pos` is where they are drawn, so |
| 506 | + it changes as the list scrolls. A child added to a `"none"` layout while |
| 507 | + scrolled is placed in content coordinates and moved into view. |
| 508 | +- **A drag that starts on a button scrolls the list and cancels the press.** |
| 509 | + The button gets `onCancel()` instead of `onRelease()`, and its `onClick` |
| 510 | + SETTING is not called. The `onClick()` METHOD already ran on the press, so |
| 511 | + a button in a list does its work in the setting: see the next section. |
| 512 | +- **A slider in a scrolling panel is dragged, not the panel.** Any widget |
| 513 | + that sets `keepsDrag` keeps its drags. |
| 514 | +- Children scrolled out of view do not get pointer events. Nested scrolling |
| 515 | + panels are not supported yet. |
| 516 | + |
444 | 517 | ### A pause overlay: `updateWhenPaused` cascades |
445 | 518 |
|
446 | 519 | `state.pause()` stops every world child stepping while rendering carries on, so |
@@ -492,6 +565,44 @@ default on a plain `Renderable` — is skipped by the broadphase and receives |
492 | 565 | nothing. `UISpriteElement` and `UIBaseElement` clear it for you; anything else |
493 | 566 | you make clickable has to clear it itself. |
494 | 567 |
|
| 568 | +### A button that does one thing: `UITextButton` |
| 569 | + |
| 570 | +No subclass needed for a single action: |
| 571 | + |
| 572 | +```js |
| 573 | +const play = new UITextButton(100, 200, { |
| 574 | + text: "Play", // a CSS font by default ("sans-serif") |
| 575 | + size: 24, // pixels with a CSS font, a SCALE with a bitmap font |
| 576 | + onClick: () => state.change(state.PLAY), |
| 577 | +}); |
| 578 | +``` |
| 579 | + |
| 580 | +**`onClick` is called on a COMPLETED click**: pressed and released over the |
| 581 | +button, or its `bindKey` pressed and released. A press dragged off the button, |
| 582 | +cancelled, or turned into a scroll does not call it, and neither does a |
| 583 | +disabled button. The `onClick()` method is different: it runs on the press, |
| 584 | +as before, for subclasses. |
| 585 | + |
| 586 | +`font` is a loaded bitmap font's name, drawn with `BitmapText` as before, or |
| 587 | +any other name, drawn as a CSS font with `Text`. The label is |
| 588 | +`button.label` (`bitmapText` is the old name for it). |
| 589 | + |
| 590 | +**Skinned** from an atlas, drawn as a nine-slice so one image makes a button |
| 591 | +of any width: |
| 592 | + |
| 593 | +```js |
| 594 | +new UITextButton(0, 0, { |
| 595 | + font: "kenpixel", size: 12, text: "Accept", borderWidth: 160, |
| 596 | + skin: { atlas, normal: "green_button04", pressed: "green_button05" }, |
| 597 | +}); |
| 598 | +``` |
| 599 | + |
| 600 | +Pressed art is usually shorter than the normal art. The button draws it |
| 601 | +lowered by the difference and moves the label down with it, so it looks |
| 602 | +pushed in. `hover` and `disabled` regions are optional. `enabled = false` |
| 603 | +draws the `disabled` region, or the button at half opacity, and ignores the |
| 604 | +pointer and the key. |
| 605 | + |
495 | 606 | ### Keyboard shortcuts on a button: `bindKey` |
496 | 607 |
|
497 | 608 | A `UITextButton` can be activated from the keyboard as well as the pointer: |
@@ -533,6 +644,60 @@ Three more rules, each with a reason you can feel in a game: |
533 | 644 | Shortcuts live only while the button is activated, and never start dragging or |
534 | 645 | tap-and-hold: those stay pointer gestures. |
535 | 646 |
|
| 647 | +### Checkboxes and radio buttons: `UICheckbox` |
| 648 | + |
| 649 | +```js |
| 650 | +const music = new UICheckbox(40, 60, { |
| 651 | + labelOn: "Music ON", labelOff: "Music OFF", // or one `label` |
| 652 | + checked: settings.music, |
| 653 | + onChange: (on) => { settings.music = on; on ? audio.playTrack("theme") : audio.stopTrack(); }, |
| 654 | +}); |
| 655 | +``` |
| 656 | + |
| 657 | +The label is part of the widget: clicking it toggles the box, and removing |
| 658 | +the checkbox takes the label with it. Drawn with primitives by default, or |
| 659 | +`skin: { atlas, on, off, disabled? }`. |
| 660 | + |
| 661 | +**Setting `checked` from code does NOT call `onChange`**, nor does |
| 662 | +`toggle()`. Only the user does. Restoring saved settings into the widgets |
| 663 | +therefore does not re-run the game logic attached to them, so apply what |
| 664 | +they stand for yourself after restoring: |
| 665 | + |
| 666 | +```js |
| 667 | +music.checked = saved.music; // the look only |
| 668 | +applyMusic(saved.music); // the effect, once |
| 669 | +``` |
| 670 | + |
| 671 | +**Radio buttons** are checkboxes sharing a `group`: exactly one is checked, |
| 672 | +clicking the checked one leaves it checked, and they are drawn round. Only |
| 673 | +the one the user picked gets `onChange`, as in a web page; read the group with |
| 674 | +`UICheckbox.checkedIn("difficulty")`. A checkbox is in its group while it is in |
| 675 | +the scene. |
| 676 | + |
| 677 | +### Sliders: `UISlider` |
| 678 | + |
| 679 | +```js |
| 680 | +const volume = new UISlider(40, 120, { |
| 681 | + label: "Music", showValue: true, |
| 682 | + format: (v) => Math.round(v * 100) + "%", |
| 683 | + min: 0, max: 1, step: 0.01, value: audio.getVolume(), |
| 684 | + length: 300, // orientation: "vertical" too |
| 685 | + onChange: (v) => audio.setVolume(v), // every step of the drag |
| 686 | + onChangeEnd: () => saveSettings(), // once, on release |
| 687 | +}); |
| 688 | +``` |
| 689 | + |
| 690 | +Drag the thumb, or click the track to jump there. The drag follows the |
| 691 | +pointer after it leaves the track, until it is released. The mouse wheel over |
| 692 | +the slider moves it one `step`. `value` snaps to `step` and clamps to the |
| 693 | +range, and setting it does not call `onChange` or `onChangeEnd`: the same rule |
| 694 | +as the checkbox. `skin: { atlas, track, fill?, thumb, thumbHover? }` draws it |
| 695 | +from art: the track and fill as nine-slices along its length, the thumb at its |
| 696 | +own size. |
| 697 | + |
| 698 | +Put work that should not run 60 times a second, such as saving or playing a |
| 699 | +test sound, in `onChangeEnd`. |
| 700 | + |
536 | 701 | ### A fullscreen option |
537 | 702 |
|
538 | 703 | Three methods on the `Application`, not on `device` (they moved there in |
@@ -721,6 +886,17 @@ of the level instead, with the scenery drawing over it. Both shipped idioms are |
721 | 886 | the same rule: afterBurner's HUD sits at `-150`, and the glTF, Billboard, Night |
722 | 887 | City and Instanced Forest examples park a floating sky at `-10000` or `100000`. |
723 | 888 |
|
| 889 | +## When the UI misbehaves |
| 890 | + |
| 891 | +| symptom | cause | fix | |
| 892 | +|---|---|---| |
| 893 | +| loading saved settings plays the music, saves again or fires game logic | the game called its own change handler while restoring | set `checkbox.checked` / `slider.value`, which never call `onChange`, then apply the setting once yourself | |
| 894 | +| `onChange` never fires when settings are restored | by design: only user input calls it | apply the restored value yourself | |
| 895 | +| a button in a scrolling list fires when the user only meant to scroll | the work is in the `onClick()` METHOD, which runs on the press | use the `onClick` SETTING, called on a completed click; a scroll cancels the press | |
| 896 | +| a button scrolled out of a hand-made list still gets clicks | its container does not clip, so the pointer still finds it where it moved to | use `UIPanel`'s `scroll`, or set `clipping` on the container: since 20.13 the pointer skips children outside a clipping container | |
| 897 | +| a layout ignores a label that changed size | layout runs on add, remove and resize only | call `panel.relayout()` | |
| 898 | +| `new UITextButton` with a font name draws in a plain font | the name is not a loaded bitmap font, so it is drawn as a CSS font | load the bitmap font (image and `.fnt`) under that name, or load the web font | |
| 899 | + |
724 | 900 | ## Related skills |
725 | 901 |
|
726 | 902 | - `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this |
|
0 commit comments