Skip to content

Grid table

Introduction

Viewer of grid table, to manipulate game object of each visible cell.

  • Author: Rex
  • Game object

Live demos

Usage

Sample code

Install plugin

Load minify file

  • Load plugin (minify file) in preload stage
    scene.load.plugin('rexgridtableplugin', 'https://raw.githubusercontent.com/rexrainbow/phaser3-rex-notes/master/dist/rexgridtableplugin.min.js', true);
    
  • Add table object
    var table = scene.add.rexGridTable(x, y, width, height, config);
    

Import plugin

  • Install rex plugins from npm
    npm i phaser3-rex-plugins
    
  • Install plugin in configuration of game
    import GridTablePlugin from 'phaser3-rex-plugins/plugins/gridtable-plugin.js';
    var config = {
        // ...
        plugins: {
            global: [{
                key: 'rexGridTablePlugin',
                plugin: GridTablePlugin,
                start: true
            },
            // ...
            ]
        }
        // ...
    };
    var game = new Phaser.Game(config);
    
  • Add table object
    var table = scene.add.rexGridTable(x, y, width, height, config);
    

Import class

  • Install rex plugins from npm
    npm i phaser3-rex-plugins
    
  • Import class
    import GridTable from 'phaser3-rex-plugins/plugins/gridtable.js';
    
  • Add table object
    var table = new GridTable(scene, x, y, width, height, config);
    scene.add.existing(table);
    

Create instance

var table = scene.add.rexGridTable(x, y, width, height, {
    scrollMode: 0,        // 0|'v'|'vertical'|1|'h'|'horizontal'
    cellsCount: 0,
    columns: 1,
    // rows: 1,
    cellHeight: 30,
    cellWidth: 30,

    cellVisibleCallback: null,
    // cellVisibleCallback: function (cell, cellContainer, table) {},
    cellVisibleCallbackScope: undefined,
    reuseCellContainer: false,

    cellInvisibleCallback: null,
    // cellInvisibleCallback: function(cell) {},
    cellInvisibleCallbackScope: undefined,
    clamplTableOXY: true,

    mask: {
        padding: 0, // or {left, right, top, bottom}
        // updateMode: 0,
        // layer: undefined,
    },
    // enableLayer: false
});
  • scrollMode :
    • 0, or 'v', or 'vertical' : Scroll table vertically.
    • 1, or 'h', or 'horizontal' : Scroll table horizontally.
  • cellsCount : Total cells count.
  • columns : Columns count of each row. Can be used in vertical or horizontal scroll mode.
  • rows : Rows count of each column. Can be used in horizontal scroll mode.
  • cellHeight : Default height of each cell.
    • Expand cell height to fit table height : set cellHeight to undefined, and scrollMode is 'horizontal'.
  • cellWidth : Width of each cell.
    • Expand cell width to fit table width : set cellWidth to undefined, and scrollMode is 'vertical'.
  • cellVisibleCallback , cellVisibleCallbackScope : Callback when cell begins visible.
    function (cell, cellContainer, table) {
        if (cellContainer === null) { // No reusable cell container, create a new one
            var scene = cell.scene;
            // cellContainer = scene.add.container();
        }
        // Set child properties of cell container ...
        cell.setContainer(cellContainer); // Assign cell container
    }
    
  • reuseCellContainer : Set true to reuse cell container when cell is visible.
  • cellInvisibleCallback, cellInvisibleCallbackScope: Callback when cell begins invisible
    function (cell) {
        // var container = cell.popContainer();
    }
    
  • clamplTableOXY : Set true to clamp tableOX, tableOY when out-of-bound,
  • mask : A rectangle mask of cells
    • mask.padding :
      • A number : Extra left/right/top/bottom padding spacing of this rectangle mask. Default value is 0.
      • A plain object {left, right, top, bottom}
    • mask.updateMode : When to update cells mask
      • 0, or update : Apply mask to cell container only when table.updateTable() is invoked. Default behavior.
      • 1, or everyTick : Apply mask to cell container every tick. Use this mode if game objects of cell are moved after table.updateTable() and still been masked.
    • mask.layer :
      • undefined, false, null : Disable this feature, default behavior
      • Layer game object : Draw children game object of panel on this layer game object, then apply mask on this layer game object.
    • false : No mask.
  • enableLayer :
    • false : Add cell game objects into scene's display list. Default behavior.
    • true : Add cell game objects into an internal layer game object. See also.

Add grid table from JSON

var table = scene.make.rexGridTable({
    x: 0,
    y: 0,
    width: 256,
    height: 256,

    // cellsCount: 0,   // total cells count
    // ...
    // origin: {x: 0.5, y: 0.5},
});

Custom class

  • Define class
    class MyGridTable extends GridTable {
        constructor(scene, x, y, width, height, config) {
            super(scene, x, y, width, height, config);
            // ...
            scene.add.existing(this);
        }
        // ...
    
        // preUpdate(time, delta) {}
    }
    
    • scene.add.existing(gameObject) : Adds an existing Game Object to this Scene.
      • If the Game Object renders, it will be added to the Display List.
      • If it has a preUpdate method, it will be added to the Update List.
  • Create instance
    var table = new MyGridTable(scene, x, y, width, height, config);
    

Cell begins visible

Add container of cell when it begins visible in event cellvisible.

table.on('cellvisible', function(cell, cellContainer, table){
    if (cellContainer === null) { // No reusable cell container, create a new one
        var scene = cell.scene;
        // cellContainer = scene.add.container();
    }
    // Set child properties of cell container ...
    cell.setContainer(cellContainer); // Assign cell container
})

It is equal to cellVisibleCallback in configuration.

{
    // ...
    cellVisibleCallback: function(cell, cellContainer, table) {
        cell.setContainer(cellContainer); // Assign cell container
    },
    // ...
}
  • cell
    • Scene object of grid table.
      var scene = cell.scene;
      
    • Index of cell.
      var index = cell.index;
      
    • Size of cell.
      var cellWidth = cell.width;
      var cellHeight = cell.height;
      
      • Change size of cell :
        • Change cell height in scoll-vertical mode.
          cell.setHeight(newHeight);
          // cell.height = newHeight;
          
          or
          cell.setDeltaHeight(deltaHeight);
          // cell.deltaHeight = deltaHeight;
          
        • Reset cell height in scoll-vertical mode.
          cell.setDeltaHeight(0);
          // cell.deltaHeight = 0;
          
        • Change cell width in scroll-horizontal mode.
          cell.setWidth(newWidth);
          // cell.width = newWidth;
          
          or
          cell.setDeltaWidth(deltaWidth);
          // cell.deltaWidth = deltaWidth;
          
        • Reset cell height in scroll-horizontal mode.
          cell.setDeltaWidth(0);
          // cell.deltaWidth = 0;
          
    • Assign cell container. Set origin point of this cell container to (0,0).
      cell.setContainer(cellContainer);
      
    • Alignment of cellContainer :
      cell.setCellContainerAlign(align);
      
      • align :
        • undefined : Set position of cellContainer to left-top of cell space. Default behavior.
        • 'center', or Phaser.Display.Align.CENTER : Align game object at center of cell space.
        • 'left', or Phaser.Display.Align.LEFT_CENTER : Align game object at left-center of cell space.
        • 'right', or Phaser.Display.Align.RIGHT_CENTER : Align game object at right-center of cell space.
        • 'top', or Phaser.Display.Align.RIGHT_CENTER : Align game object at top-center of cell space.
        • 'bottom', or Phaser.Display.Align.BOTTOM_CENTER : Align game object at bottom-center of cell space.
  • cellContainer : Cell container picked from object pool for reusing. Set reuseCellContainer to true to enable this feature.
    • null : No cell container available.
    • Game object : Reusable cell container.
  • table : Grid table.

Each cell only has one container gameObject, old container will be destroyed when assigning a new container.

Cell begins invisible

Container of an invisible cell will be destroyed automatically.

To resue container gameObject

  • Set reuseCellContainer to true to put invisible cell container into object pool.
  • Or, pop that container by cell.popContainer() in event cellinvisible.
table.on('cellinvisible', function(cell){
    // var container = cell.popContainer();
})

It is equal to cellInvisibleCallback in configuration.

{
    // ...
    cellInvisibleCallback: function(cell) {
        // var container = cell.popContainer();
    },
    // ...
}

Scroll table content

  • Set
    table.setTableOY(oy).updateTable();
    table.addTableOY(dy).updateTable();
    
    table.setTableOX(ox).updateTable();
    table.addTableOX(dx).updateTable();
    
    table.setTableOXY(ox, oy).updateTable();
    table.addTableOXY(dx, dy).updateTable();
    
    or
    table.tableOY = oy;  // include table.updateTable()
    table.tableOX = ox;
    
    • These will trigger cellvisible, or cellinvisible events.
  • Get
    var tableOY = table.tableOY;
    var tableOX = table.tableOX;
    

Use case

Scroll table by scroller behavior.

Scroll by percentage

  • Set
    table.setTableOYByPercentage(t).updateTable();  // t: 0~1
    
    or
    table.t = t;  // include table.updateTable()
    
  • Get
    var t = table.getTableOYPercentage();
    //var t = table.t;
    

Use case

Scroll table by slider behavior.

Scroll to bottom

table.scrollToBottom();

Scroll to row

  • Scroll to next row
    table.scrollToNextRow();
    
  • Scroll to next n row
    table.scrollToNextRow(n);
    
  • Scroll to row
    table.scrollToRow(rowIndex);
    
  • Get current row index
    var rowIndex = table.startRowIndex;
    

Refresh table content

  • Refresh all visible cells.
    table.updateTable(true);
    
  • Update a visible cell
    table.updateVisibleCell(cellIndex);
    

Table size in cells

  • Set table size
    table.setGridSize(colCount, rowCount).updateTable();
    

Total cells count

  • Get
    var count = table.cellsCount;
    
  • Set
    table.setCellsCount(count).updateTable();
    

Columns count

  • Get
    var columnCount = table.columnCount;
    
  • Set
    table.setColumnCount(count).updateTable();
    

Table size in pixels

  • Table height in pixels
    var tableHeight = table.tableHeight;
    
  • Table width in pixels
    var tableWidth = table.tableWidth;
    

Bounds of tableOX, tableOY

  • Top bound of tableOY
    var topTableOY = table.topTableOY;  // 0
    
  • Bottom bound of tableOY
    var bottomTableOY = table.bottomTableOY; // A negative number
    
  • Left bound of tableOX
    var leftTableOX = table.leftTableOX;  // 0
    
  • Right bound of tableOX
    var rightTableOX = table.rightTableOX; // A negative number
    

Use case

Set bounds of scroller

Resize table

table.resize(width, height);

Cell

Get cell

var cell = table.getCell(cellIndex);

Get cell from position

var cellIndex = table.pointToCellIndex(x, y);
var cell = table.getCell(cellIndex);

Cell height

  • Get
    var height = cell.height;
    
  • Set cell height, only worked in scoll-vertical mode.
    cell.height = height;
    // cell.setHeight(height);
    
    or
    table.setCellHeight(cellIndex, cellHeight);
    
    • Refresh table after the cell size is changed.
      table.updateTable(true);
      
    • Emit 'cellheightchange' event.
      table.on('cellheightchange', function (cell, cellContainer, table) {
      });
      

Cell width

  • Get
    var width = cell.width;
    
  • Set cell width, only worked in scoll-horizontal mode.
    cell.width = width;
    // cell.setWidth(width);
    
    or
    table.setCellWidth(cellIndex, cellWidth);
    
    • Refresh table after the cell size is changed.
      table.updateTable(true);
      
    • Emit 'cellwidthchange' event.
      table.on('cellwidthchange', function (cell, cellContainer, table) {
      });
      

Fore each visible cell

  • For when you absolutely know this Set won't be modified during the iteration
    table.iterateVisibleCell(function(cell){
        // ...
    });
    
  • For when you know this Set will be modified during the iteration.
    table.eachVisibleCell(function(cell){
        // ...
    });
    

Container

  • Get
    var container = cell.getContainer();
    
  • Pop (get and remove)
    var container = cell.popContainer();
    
  • Set
    cell.setContainer(container);
    
  • Remove
    cell.destroyContainer();
    

Properties

var cellIndex = cell.index;

Other properties

See game object