Dialog

Introduction

A container with a title, content, buttons and background.

  • Author: Rex
  • Game object

Live demos

Usage

Sample code

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 dialog object
    var dialog = scene.rexUI.add.dialog(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 dialog object
    var dialog = scene.rexUI.add.dialog(config);
    

Import class

  • Install rex plugins from npm
    npm i phaser3-rex-plugins
    
  • Import class
    import { Dialog } from 'phaser3-rex-plugins/templates/ui/ui-components.js';
    
  • Add dialog object
    var dialog = new Dialog(scene, config);
    sscene.add.existing(dialog);
    

Add dialog object

var dialog = scene.rexUI.add.dialog({
    // x: 0,
    // y: 0,
    // anchor: undefined,
    // width: undefined,
    // height: undefined,

    // Elements
    background: backgroundGameObject,

    title: titleGameObject,

    toolbar: [
        buttonGameObject,
        buttonGameObject,
        // ...
    ],
    toolbarBackground: toolbarBackgroundGameObject,

    leftToolbar: [
        buttonGameObject,
        buttonGameObject,
        // ...
    ],
    leftToolbarBackground: leftToolbarBackgroundGameObject,

    content: contentGameObject,

    description: descriptionGameObject,

    choices: [
        buttonGameObject,
        buttonGameObject,
        // ...
    ],
    choicesBackground: choicesBackgroundGameObject,

    actions: [
        buttonGameObject,
        buttonGameObject,
        // ...
    ],
    actionsBackground: actionsBackgroundGameObject,

    // Space
    space: {
        left: 0,
        right: 0,
        top: 0,
        bottom: 0,

        title: 0,
        titleLeft: 0,
        titleRight: 0,
        content: 0,
        contentLeft: 0,
        contentRight: 0,
        description: 0,
        descriptionLeft: 0,
        descriptionRight: 0
        choices: 0,
        choicesLeft: 0,
        choicesRight: 0,
        actionsLeft: 0,
        actionsRight: 0,

        toolbarItem: 0,
        leftToolbarItem: 0,
        choice: 0,
        action: 0,
    },

    expand: {
        title: true,
        content: true,
        description: true,
        choices: true,
        actions: false,
    },

    align: {
        title: 'center',
        content: 'center',
        description: 'center',
        choices: 'center',
        actions: 'center',
    },

    click: {
        mode: 'pointerup',
        clickInterval: 100
    }

    // 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'.
  • width, height : Minimum width, minimum height.
  • background : Game object of background, optional. This background game object will be resized to fit the size of dialog.
  • title : Game object of title, optional.
  • toolbar : Array of Game objects for toolbar-buttons group which arranged from left to right, optional.
    • [] : Assign an empty array if user will add button later.
  • toolbarBackground : Game object of toolbar buttons background, optional. This background game object will be resized to fit the size of dialog.
  • leftToolbar : Array of Game objects for left-toolbar-buttons group which arranged from left to right, optional.
    • [] : Assign an empty array if user will add button later.
  • leftToolbarBackground : Game object of leftToolbar buttons background, optional. This background game object will be resized to fit the size of dialog.
  • content : Game object of content, optional.
  • description : Game object of description, optional.
  • choices : Array of Game objects for choice-buttons group which arranged from top to bottom, optional.
    • [] : Assign an empty array if user will add button later.
  • choicesBackground : Game object of choices buttons background, optional. This background game object will be resized to fit the size of dialog.
  • choicesType : Type/behavior of choice buttons.
    • undefined : No extra behavior, default value.
    • 'checkboxes' : Set these buttons to checkboxes.
    • 'radio' : Set these buttons to radio.
  • actions : Array of Game objects for action-buttons group which arranged from left to right, optional.
    • [] : Assign an empty array if user will add button later.
  • choicesBackground : Game object of choices buttons background, optional. This background game object will be resized to fit the size of dialog.
  • space : Pads spaces
    • space.left, space.right, space.top, space.bottom : Space of bounds.
    • space.title : Space between title game object and below game object.
    • space.titleLeft, space.titleRight : Extra left/right padding of title game object.
    • space.content : Space between content game object and below game object.
    • space.contentLeft, space.contentRight : Extra left/right padding of content game object.
    • space.description : Space between description game object and below game object.
    • space.descriptionLeft, space.descriptionRight : Extra left/right padding of description game object.
    • space.choices : Space between last choice-button and below game object.
    • space.choicesLeft, space.choicesRight : Extra left/right padding of choice buttons.
    • space.actionsLeft, space.actionsRight : Extra left/right padding of actions buttons.
    • space.toolbarItem : Space between each toolbar item game objects.
    • space.leftToolbarItem : Space between each left-toolbar item game objects.
    • space.choice : Space between each choice-button game objects.
    • space.action : Space between each action-button game objects.
  • expand : Expand width of element
    • expand.title : Set true to expand width of title game object. Default is true.
    • expand.content : Set true to expand width of content game object. Default is true.
    • expand.description : Set true to expand width of description game object. Default is true.
    • expand.choices : Set true to expand width of choices game object. Default is true.
    • expand.actions : Set true to expand width of actions game object. Default is false.
  • align : Align element
    • align.title
      • 'center', or Phaser.Display.Align.CENTER : Align game object at center. Default value.
      • 'left', or Phaser.Display.Align.LEFT_CENTER : Align game object at left-center.
      • 'right', or Phaser.Display.Align.RIGHT_CENTER : Align game object at right-center.
    • align.content : Align content game object to 'left'/'center'/'right', if expand.title is false.
    • align.description : Align description game object to 'left'/'center'/'right', if expand.description is false.
    • align.choices : Align choices game object to 'left'/'center'/'right', if expand.choices is false.
    • align.actions : Align action game objects to 'left'/'center'/'right', if expand.actions is false.
  • click: Configuration of button clicking.
    • click.mode :
      • 'pointerdown', 'press', or 0 : Fire 'click' event when touch pressed.
      • 'pointerup', 'release', or 1 : Fire 'click' event when touch released after pressed.
    • click.clickInterval : Interval between 2 'click' events, in ms.
  • name : Set name of this dialog.

Custom class

  • Define class
    class MyDialog extends RexPlugins.UI.Dialog {
        constructor(scene, config) {
            super(scene, config);
            // ...
            scene.add.existing(this);
        }
        // ...
    }
    
  • Create instance
    var dialog = new MyDialog(scene, config);
    

Layout children

Arrange position of all elements.

dialog.layout();

See also - dirty

Other properties

See sizer object, base sizer object.

Events

  • Click button
    dialog.on('button.click', function(button, groupName, index, pointer, event) {
        // ...
    }, scope);
    
    • button : Triggered button game object.
    • groupName : 'choices', 'actions', or 'toolbar'.
    • index : Index of triggered button game object.
    • pointer : Pointer object.
    • Cancel remaining touched events : event.stopPropagation()
  • Pointer-over button
    dialog.on('button.over', function(button, groupName, index, pointer, event) {
        // ...
    }, scope);
    
    • button : Triggered button game object
    • groupName : 'choices', 'actions', 'toolbar', or 'leftToolbar'.
    • index : Index of triggered button game object.
    • pointer : Pointer object.
    • Cancel remaining touched events : event.stopPropagation()
  • Pointer-out button
    dialog.on('button.out', function(button, groupName, index, pointer, event) {
        // ...
    }, scope);
    
    • button : Triggered button game object.
    • groupName : 'choices', 'actions', 'toolbar', or 'leftToolbar'
    • index : Index of triggered button game object.
    • pointer : Pointer object.
    • Cancel remaining touched events : event.stopPropagation()
  • Enable button's input
    dialog.on('button.enable', function(button, groupName, index) {
        // ...
    }, scope);
    
    • button : Triggered button game object.
    • groupName : 'choices', 'actions', 'toolbar', or 'leftToolbar'
    • index : Index of triggered button game object.
  • Disable button's input
    dialog.on('button.disalbe', function(button, groupName, index) {
        // ...
    }, scope);
    
    • button : Triggered button game object.
    • groupName : 'choices', 'actions', 'toolbar', or 'leftToolbar'
    • index : Index of triggered button game object.

Emit button click event

  • Emit choice/action/toolbar/left-toolbar button's click event
    dialog.emitChoiceClick(index);
    dialog.emitActionClick(index);
    dialog.emitToolbarClick(index);
    dialog.emitLeftToolbarClick(index);
    
    • index : A number index, or a button game object.

Enable/disable input of button

  • Enable choice/action/toolbar/left-toolbar button
    dialog.setChoiceEnable(index);
    dialog.setActionEnable(index);
    dialog.setToolbarEnable(index);
    dialog.setLeftToolbarEnable(index);
    
    • index : A number index, or a button game object.
  • Disable choice/action/toolbar/left-toolbar button's input
    dialog.setChoiceEnable(index, false);
    dialog.setActionEnable(index, false);
    dialog.setToolbarEnable(index, false);
    dialog.setLeftToolbarEnable(index, false);
    
    • index : A number index, or a button game object.
  • Toggle choice/action/toolbar/left-toolbar button's input
    dialog.toggleChoiceEnable(index);
    dialog.toggleActionEnable(index);
    dialog.toggleToolbarEnable(index);
    dialog.toggleLeftToolbarEnable(index);
    
    • index : A number index, or a button game object.
  • Get choice/action/toolbar/left-toolbar button's input enable
    var enabled = dialog.getChoiceEnable(index);
    var enabled = dialog.getActionEnable(index);
    var enabled = dialog.getToolbarEnable(index);
    var enabled = dialog.getLeftToolbarEnable(index);
    
    • index : A number index, or a button game object.

Get element

  • Get element
    • Background game object
      var background = dialog.getElement('background');
      
    • Title game object
      var title = dialog.getElement('title');
      
    • Content game object
      var content = dialog.getElement('content');
      
    • Description game object
      var description = dialog.getElement('description');
      
    • Choice button game object
      var buttons = dialog.getElement('choices');
      
      or
      var button = dialog.getChoice(index);
      
      or
      var button = dialog.getElement('choices[' + index + ']');
      
    • Acrion button game object
      var buttons = dialog.getElement('actions');
      
      or
      var button = dialog.getAction(index);
      
      or
      var button = dialog.getElement('actions[' + index + ']');
      
    • Toolbar button game object
      var buttons = dialog.getElement('toolbar');
      
      or
      var button = dialog.getToolbar(index);
      
      or
      var button = dialog.getElement('toolbar[' + index + ']');
      
    • Left-toolbar button game object
      var buttons = dialog.getElement('leftToolbar');
      
      or
      var button = dialog.getLeftToolbar(index);
      
      or
      var button = dialog.getElement('leftToolbar[' + index + ']');
      
  • Get by name
    var gameObject = dialog.getElement('#' + name);
    // var gameObject = dialog.getElement('#' + name, recursive);
    
    or
    var gameObject = dialog.getByName('#' + name);
    // var gameObject = dialog.getByName('#' + name, recursive);
    
    • recursive : Set true to search all children recursively.

Add button

Add choice/action/toolbar/left-toolbar button

dialog.addChoice(gameObject);
dialog.addAction(gameObject);
dialog.addToolbar(gameObject);
dialog.addLeftToolbar(gameObject);
  • gameObject : A game object, or an array of game objects.

Remove button

  • Remove a choice/action/toolbar/left-toolbar button
    dialog.removeChoice(index, destroyChild);
    dialog.removeAction(index, destroyChild);
    dialog.removeToolbar(index, destroyChild);
    dialog.removeLeftToolbar(index, destroyChild);
    
    • index : A number index, a string name, or a button game object.
    • destroyChild : Set true to destroy button game object.
  • Remove all choice/action/toolbar/left-toolbar buttons
    dialog.clearChoices(destroyChild);
    dialog.clearActions(destroyChild);
    dialog.clearToolbar(destroyChild);
    dialog.clearLeftToolbar(destroyChild);
    
    • destroyChild : Set true to destroy button game object.

Show/hide button

Hidden elements won't be counted when layouting. Call dialog.layout(), or topSizer.layout() after show/hide any button.

  • Show choice/action/toolbar/left-toolbar button
    dialog.showChoice(index);
    dialog.showAction(index);
    dialog.showToolbar(index);
    dialog.showLeftToolbar(index);
    
    • index : A number index, a string name, or a button game object.
  • Hide choice/action/toolbar/left-toolbar button.
    dialog.hideChoice(index);
    dialog.hideAction(index);
    dialog.hideToolbar(index);
    dialog.hideLeftToolbar(index);
    
    • index : A number index, a string name, or a button game object.

For each button

dialog.forEachChoice(callback, scope);
dialog.forEachAction(callback, scope);
dialog.forEachToolbar(callback, scope);
dialog.forEachLeftToolbar(callback, scope);
  • callback :
    function(button, index, buttons) {
        // ...
    }