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 config = {
    cellsCount: 0,
    columns: 1,
    cellHeight: 30,
    cellWidth: 30,

    cellVisibleCallback: null,
    cellVisibleCallbackScope: undefined,
    reuseCellContainer: false,

    cellInvisibleCallback: null,
    cellInvisibleCallbackScope: undefined,

    clamplTableOXY: true,
    scrollMode: 0,        // 0|'v'|'vertical'|1|'h'|'horizontal'
    mask: {
        padding: 0,
        updateMode: 0
    }
}
var table = scene.add.rexGridTable(x, y, width, height, config);
  • cellsCount : Total cells count.
  • columns : Columns count of each row.
  • 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.
  • reuseCellContainer : Set true to reuse cell container when cell is visible.
  • cellInvisibleCallback, cellInvisibleCallbackScope: Callback when cell begins invisible.
  • clamplTableOXY : Set true to clamp tableOX, tableOY when out-of-bound,
  • scrollMode :
    • 0, or 'v', or 'vertical' : Scroll table vertically.
    • 1, or 'h', or 'horizontal' : Scroll table horizontally.
  • mask : A rectangle mask of cells
    • mask.padding : Extra left/right/top/bottom padding spacing of this rectangle mask. Default value is 0.
    • 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.
    • false : No mask.

Add grid table from JSON

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

    // cellsCount: 0,   // total cells count
    // ...
});

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);
      
  • 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.

Refresh table content

Refresh all visible cells.

table.updateTable(true);

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);
      

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);
      

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;