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,
    // fixedCellSize: false,

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

    cellInvisibleCallback: null,
    // cellInvisibleCallback: function(cell) {},
    // cellInvisibleCallbackScope: undefined,
    // clampTableOXY: true,
    // startFromBottom: false,

    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'.
fixedCellSize : Assign columns according to cellWidth (if scrollMode is 0) or cellHeight (if scrollMode is 1) , when initialize and resizing. 　　- false : Ignore this parameter. Default behavior.
- true : Set columns according to cellWidth/cellHeight.

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();
}
```
clampTableOXY :
- true : Clamp tableOX, tableOY when out-of-bound,
- false : No clamping, default behavior.
startFromBottom :
- false : Start from top. Default behavior.
- true : If cells' height is less then a page, align cells to bottom.
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(true);

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

Reset size of all cells¶

table.resetAllCellsSize(width, height);

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