Scroll-able panel
Introduction¶
A container with a panel, slider, and scroller.
- Author: Rex
- Game object
Live demos¶
Usage¶
Install plugin¶
Load minify file¶
- Load plugin (minify file) in preload stage
scene.load.scenePlugin('rexuiplugin', 'https://raw.githubusercontent.com/rexrainbow/phaser3-rex-notes/master/dist/rexuiplugin.min.js', 'rexUI', 'rexUI');
- Add scrollable-panel object
var panel = scene.rexUI.add.scrollablePanel(config);
Import plugin¶
- Install rex plugins from npm
npm i phaser3-rex-plugins
- Install plugin in configuration of game
import UIPlugin from 'phaser3-rex-plugins/templates/ui/ui-plugin.js'; var config = { // ... plugins: { scene: [{ key: 'rexUI', plugin: UIPlugin, mapping: 'rexUI' }, // ... ] } // ... }; var game = new Phaser.Game(config);
- Add scrollable-panel object
var panel = scene.rexUI.add.scrollablePanel(config);
Import class¶
- Install rex plugins from npm
npm i phaser3-rex-plugins
- Import class
import { ScrollablePanel } from 'phaser3-rex-plugins/templates/ui/ui-components.js';
- Add scrollable-panel object
var panel = new ScrollablePanel(scene, config); sscene.add.existing(panel);
Add scroll-able panel object¶
var panel = scene.rexUI.add.scrollablePanel({
// x: 0,
// y: 0,
// anchor: undefined,
// width: undefined,
// height: undefined,
scrollMode: 0,
// Elements
background: backgroundGameObject,
panel: {
child: panelGameObject,
mask: {
padding: 0,
updateMode: 0
}
}.
slider: {
track: trackGameObject,
thumb: thumbGameObject,
position: 0,
},
scroller: {
threshold: 10,
slidingDeceleration: 5000,
backDeceleration: 2000,
},
clamplChildOY: false,
header: headerGameObject,
footer: footerGameObject,
space: {
left: 0,
right: 0,
top: 0,
bottom: 0,
panel: 0,
// panel: {
// top: 0,
// bottom: 0,
// left: 0,
// right: 0,
//},
header: 0,
footer: 0,
},
expand: {
header: true,
footer: true,
},
align: {
header: 'center',
footer: 'center',
},
// name: '',
// draggable: false
});
x
,y
: Position of this object, it is valid when this object is the top object.anchor
: See anchor.left
,right
,centerX
,x
,top
,bottom
,centerY
,y
: Position based on visible window, which composed of- Percentage of visible width/height :
'p%'
, p:0
~100
.'left'
(=0%),'center'
(=50%),'right'
(=100%)'top'
(=0%),'center'
(=50%),'bottom'
(=100%)
- Offset :
'+n'
, or'-n'
.
- Percentage of visible width/height :
width
,height
: Minimum width, minimum height.scrollMode
: Scroll panel vertically, or horizontally.0
,'vertical'
, or'v'
: Scroll panel vertically. Default value.1
,'horizontal'
, or'h'
: Scroll panel horizontally.
background
: Game object of background, optional. This background game object will be resized to fit the size of scroll-able panel.panel
: Configuration of panel game object.panel.child
: Panel game object.panel.mask
: Configuration of panel's mask.panel.mask.padding
: Extra left/right/top/bottom padding spacing of this rectangle mask. Default value is0
.panel.mask.updateMode
: When to update mask0
, orupdate
: Apply mask only when scrolling. Default behavior.1
, oreveryTick
: Apply mask every tick. Use this mode if children game objects of panel are moved after scrolling and still been masked.
false
: No mask.
panel.mask.padding
: Extend mask with padding. Default value is0
.
slider
: Componments of slider, optional.slider.background
: Game object of slider background, optional.slider.track
: Game object of track.slider.thumb
: Game object of thumb.slider.input
:'drag'
: Control slider by dragging thumb game object. Default setting.'click'
: Control slider by touching track game object.'none'
: Disable sider controlling.
slider.position
: Position of this sldier.0
,'right'
,'bottom'
: Sldier at right/bottom side. Default value.1
,'left'
,'top'
: Sldier at left/top side.
- Set to
false
to skip creating slider.
scroller
: Configuration of scroller behavior.scroller.threshold
: Minimal movement to scroll. Set0
to scroll immediately.scroller.slidingDeceleration
: Deceleration of slow down when dragging released.- Set
false
to disable it.
- Set
scroller.backDeceleration
: Deceleration of pull back when out of bounds.- Set
false
to disable it.
- Set
- Set to
false
to skip creating scroller.
clamplChildOY
: Settrue
to clamp scrolling.header
: Game object of header, optional.footer
: Game object of footer, optional.space
: Pads spacesspace.left
,space.right
,space.top
,space.bottom
: Space of bounds.space.panel
:- A number: Space between panel object and slider object.
- An object: Padding of panel object.
- If
scrollMode
is0
(vertical) :space.panel.top
,space.panel.bottom
: Top, bottom padding space of panel object.space.panel.right
: Space between panel object and slider object.
- If
scrollMode
is1
(horizontal) :space.panel.left
,space.panel.right
: Left, right padding space of panel object.space.panel.bottom
: Space between panel object and slider object.
- If
space.header
: Space between header and panel.space.footer
: Space between footer and panel.
expand
: Expand width or height of elementexpand.header
: Settrue
to expand width or height of header game object.expand.footer
align
: Align elementalign.header
'center'
, orPhaser.Display.Align.CENTER
: Align game object at center. Default value.'left'
, orPhaser.Display.Align.LEFT_CENTER
: Align game object at left-center.'right'
, orPhaser.Display.Align.RIGHT_CENTER
: Align game object at right-center.
align.footer
name
: Set name of this panel.
Custom class¶
- Define class
class MyPanel extends RexPlugins.UI.ScrollablePanel { constructor(scene, config) { super(scene, config); // ... scene.add.existing(this); } // ... }
- Create instance
var panel = new MyPanel(scene, config);
Layout children¶
Arrange position of all elements.
panel.layout();
See also - dirty
Scroll content¶
- Set
or
panel.setChildOY(oy);
panel.childOY = oy;
- Get
var childOY = panel.childOY;
Scroll by percentage¶
- Set
or
panel.setT(t); // t: 0~1
panel.t = t;
- Get
var t = panel.t;
- Top OY
var topOY = panel.topChildOY;
- Bottom OY
var bottomOY = panel.bottomChildOY;
Scroll to top/bottom¶
- Scroll to top
panel.scrollToTop();
- Equal to
panel.t = 0;
- Equal to
- Scroll to bottom
panel.scrollToBottom();
- Equal to
panel.t = 1;
- Equal to
Enable/disable scrolling¶
- Slider
- Set enable state
or
panel.setSliderEnable(enabled);
panel.sliderEnable = enabled;
- Get enable state
var enable = panel.sliderEnable;
- Set enable state
- Scroller
- Set enable state
or
panel.setScrollerEnable(enabled);
panel.scrollerEnable = enabled;
- Get enable state
var enable = panel.scrollerEnable;
- Set enable state
Event¶
- On scroll
panel.on('scroll', function(panel) { // ... })
Other properties¶
See sizer object, base sizer object.
Get element¶
- Get element
- Background game object
var background = panel.getElement('background');
- Panel game object
var panel = panel.getElement('panel');
- Slider
- Track
var track = panel.getElement('slider.track');
- Thumb
var thumb = panel.getElement('slider.thumb');
- Track
- Scroller
var scroller = panel.getElement('scroller');
- Background game object
- Get by name
or
var gameObject = panel.getElement('#' + name); // var gameObject = panel.getElement('#' + name, recursive);
var gameObject = panel.getByName('#' + name); // var gameObject = panel.getByName('#' + name, recursive);
recursive
: Settrue
to search all children recursively.
Input events¶
When scene.input.topOnly
is true
(default value), input events of children elememts will block the drag-scrolling of scrollable panel. (Assmue that the children elememts are above scrollable panel)
- Set
scene.input.topOnly
tofalse
to enable drag-scrolling and input events of children elememts both. - Test if pointer is under panel via
panel.isInTouching()
, during input events' callback. - To recognize pointer-down and dragging-start, use press's
pressstart
event.