Skip to content

Latest commit

 

History

History
339 lines (275 loc) · 14.7 KB

api.md

File metadata and controls

339 lines (275 loc) · 14.7 KB
Raw

Classes

RegularTableElement ⇐ HTMLElement

The <regular-table> custom element.

This module has no exports, but importing it has a side effect: the RegularTableElement class is registered as a custom element, after which it can be used as a standard DOM element.

The documentation in this module defines the instance structure of a <regular-table> DOM object instantiated typically, through HTML or any relevent DOM method e.g. document.createElement("perspective-viewer") or document.getElementsByTagName("perspective-viewer").

Typedefs

Performance : object

An object with performance statistics about calls to draw() from some time interval (captured in milliseconds by the elapsed proprty).

MetaData : object

An object describing virtual rendering metadata about an HTMLTableCellElement, use this object to map rendered <th> or <td> elements back to your data, row_headers or column_headers within listener functions for addStyleListener() and addEventListener().

DataResponse : object

The DataResponse object describes a rectangular region of a virtual data set, and some associated metadata. <regular-table> will use this object to render the <table>, though it may make multiple requests for different regions to achieve a compelte render as it must estimate certain dimensions. You must construct a DataResponse object to implement a DataListener.

DataListener ⇒ Promise.<DataResponse>

The DataListener is similar to a normal event listener function. Unlike a normal event listener, it takes regular arguments (not an Event); and returns a Promise for a DataResponse object for this region (as opposed to returning void as a standard event listener).

RegularTableElement ⇐ HTMLElement

The <regular-table> custom element.

This module has no exports, but importing it has a side effect: the RegularTableElement class is registered as a custom element, after which it can be used as a standard DOM element.

The documentation in this module defines the instance structure of a <regular-table> DOM object instantiated typically, through HTML or any relevent DOM method e.g. document.createElement("perspective-viewer") or document.getElementsByTagName("perspective-viewer").

Kind: global class
Extends: HTMLElement
Access: public

regularTableElement.addStyleListener(styleListener) ⇒ number

Adds a style listener callback. The style listeners are called whenever the

is re-rendered, such as through API invocations of draw() and user-initiated events such as scrolling. Within this optionally async callback, you can select
, , etc. elements via regular DOM API methods like querySelectorAll().

Kind: instance method of RegularTableElement
Returns: number - The index of the added listener.
Access: public

Param Type Description
styleListener function A (possibly async) function that styles the inner .

Example

table.addStyleListener(() => {
    for (const td of table.querySelectorAll("td")) {
        td.setAttribute("contenteditable", true);
    }
});

regularTableElement.getMeta(element) ⇒ MetaData

Returns the MetaData object associated with a <td> or <th>. When your StyleListener is invoked, use this method to look up additional MetaData about any HTMLTableCellElement in the rendered <table>.

Kind: instance method of RegularTableElement
Returns: MetaData - The metadata associated with the element.
Access: public

Param Type Description
element HTMLTableCellElement | Partial.<MetaData> The child element of this <regular-table> for which to look up metadata, or a coordinates-like object to refer to metadata by logical position.

Example

const elems = document.querySelector("td:last-child td:last_child");
const metadata = table.getMeta(elems);
console.log(`Viewport corner is ${metadata.x}, ${metadata.y}`);

Example

const header = table.getMeta({row_header_x: 1, y: 3}).row_header;

regularTableElement.getDrawFPS() ⇒ Performance

Get performance statistics about this <regular-table>. Calling this method resets the internal state, which makes it convenient to measure performance at regular intervals (see example).

Kind: instance method of RegularTableElement
Returns: Performance - Performance data aggregated since the last call to getDrawFPS().
Access: public
Example

const table = document.getElementById("my_regular_table");
setInterval(() => {
    const {real_fps} = table.getDrawFPS();
    console.log(`Measured ${fps} fps`)
});

regularTableElement.scrollToCell(x, y, ncols, nrows)

Call this method to set the scrollLeft and scrollTop for this <regular-table> by calculating the position of this scrollLeft and scrollTop relative to the underlying widths of its columns and heights of its rows.

Kind: instance method of RegularTableElement
Access: public

Param Type Description
x number The left most x index column to scroll into view.
y number The top most y index row to scroll into view.
ncols number Total number of columns in the data model.
nrows number Total number of rows in the data model.

Example

table.scrollToCell(1, 3, 10, 30);

regularTableElement.setDataListener(dataListener)

Call this method to set DataListener for this <regular-table>, which will be called whenever a new data slice is needed to render. Calls to draw() will fail if no DataListener has been set

Kind: instance method of RegularTableElement
Access: public

Param Type Description
dataListener DataListener dataListener is called by to request a rectangular section of data for a virtual viewport, (x0, y0, x1, y1), and returns a DataReponse object.

Example

table.setDataListener((x0, y0, x1, y1) => {
    return {
        num_rows: num_rows = DATA[0].length,
        num_columns: DATA.length,
        data: DATA.slice(x0, x1).map(col => col.slice(y0, y1))
    };
})

Performance : object

An object with performance statistics about calls to draw() from some time interval (captured in milliseconds by the elapsed proprty).

Kind: global typedef
Properties

Name Type Description
avg number Avergage milliseconds per call.
real_fps number num_frames / elapsed
virtual_fps number elapsed / avg
num_frames number Number of frames rendered.
elapsed number Number of milliseconds since last call to getDrawFPS().

MetaData : object

An object describing virtual rendering metadata about an HTMLTableCellElement, use this object to map rendered <th> or <td> elements back to your data, row_headers or column_headers within listener functions for addStyleListener() and addEventListener().

Kind: global typedef
Properties

Name Type Description
[x] number The x index in your virtual data model. property is only generated for <td>, <th> from row_headers.
[y] number The y index in your virtual data model. property is only generated for <td>, <th> from row_headers.
[x0] number The x index of the viewport origin in your data model, e.g. what was passed to x0 when your dataListener was invoked.
[y0] number The y index of the viewport origin in your data model, e.g. what was passed to y0 when your dataListener was invoked.
[x1] number The x index of the viewport corner in your data model, e.g. what was passed to x1 when your dataListener was invoked.
[y1] number The y index of the viewport origin in your data model, e.g. what was passed to y1 when your dataListener was invoked.
[dx] number The x index in DataResponse.data, this property is only generated for <td>, and <th> from column_headers.
[dy] number The y index in DataResponse.data, this property is only generated for <td>, <th> from row_headers.
[column_header_y] number The y index in DataResponse.column_headers[x], this property is only generated for <th> from column_headers.
[column_header_x] number The x index in DataResponse.row_headers[y], this property is only generated for <th> from row_headers.
size_key number The unique index of this column in a full <table>, which is x + (Total Row Header Columns).
[row_header] Array.<object> The Array for this y in DataResponse.row_headers, if it was provided.
[column_header] Array.<object> The Array for this x in DataResponse.column_headers, if it was provided.

Example

MetaData                     (x = 0, column_header_y = 0))
                             *-------------------------------------+
                             |                                     |
                             |                                     |
                             +-------------------------------------+
(row_header_x = 0, y = 0)    (x = 0, y = 0)
*------------------------+   *-------------------------------------+
|                        |   |                                     |
|                        |   |      (x0, y0)                       |
|                        |   |      *---------------*              |
|                        |   |      |               |              |
|                        |   |      |     * (x, y)  |              |
|                        |   |      |               |              |
|                        |   |      *---------------* (x1, y1)     |
|                        |   |                                     |
+------------------------+   +-------------------------------------+

DataResponse : object

The DataResponse object describes a rectangular region of a virtual data set, and some associated metadata. <regular-table> will use this object to render the <table>, though it may make multiple requests for different regions to achieve a compelte render as it must estimate certain dimensions. You must construct a DataResponse object to implement a DataListener.

Kind: global typedef
Properties

Name Type Description
[column_headers] Array.<Array.<object>> A two dimensional Array of column group headers, in specificity order. No <thead> will be generated if this property is not provided.
[row_headers] Array.<Array.<object>> A two dimensional Array of row group headers, in specificity order. No <th> elements within <tbody> will be generated if this property is not provided.
data Array.<Array.<object>> A two dimensional Array representing a rectangular section of the underlying data set from (x0, y0) to (x1, y1), arranged in columnar fashion such that data[x][y] returns the yth row of the xth column of the slice.
num_rows number Total number of rows in the underlying data set.
num_columns number Total number of columns in the underlying data set.

Example

{
    "num_rows": 26,
    "num_columns": 3,
    "data": [
        [0, 1],
        ["A", "B"]
    ],
    "row_headers": [
        ["Rowgroup 1", "Row 1"],
        ["Rowgroup 1", "Row 2"]
    ],
    "column_headers": [
        ["Colgroup 1", "Column 1"],
        ["Colgroup 1", "Column 2"]
    ]
}

DataListener ⇒ Promise.<DataResponse>

The DataListener is similar to a normal event listener function. Unlike a normal event listener, it takes regular arguments (not an Event); and returns a Promise for a DataResponse object for this region (as opposed to returning void as a standard event listener).

Kind: global typedef
Returns: Promise.<DataResponse> - The resulting DataResponse. Make sure to resolve or reject the Promise, or your <regular-table> will never render!

Param Type Description
x0 number The origin x index (column).
y0 number The origin y index (row).
x1 number The corner x index (column).
y1 number The corner y index (row).