Custom graphics functions

Definition

As of Hypergrid v1.3.0 you can add custom methods to the 2d graphics context to customize certain graphics operations at a low level.

Depending on this approach is not necessarily recommended, and usually shouldn't be necessary with proper planning. But it is a way for cell renderer authors to provide hooks for possible unanticipated future needs. Cell renderers can be written using specially named custom methods that default to native methods. Future applications can override these defaults with their own methods and thereby avoid forking the entire cell renderer just to change one minor aspect of rendering.

We have tested this capability in Chrome, FireFox, Safari, and Internet Explorer.

Advantages

• Such methods are naturally visible to cell renderers through their 1st parameter (gc).
• Calling such methods is more performant than calling a local function and passing the graphics context in with Function.prototype.call.
• Graphics code reads cleanly.

Installation

Custom graphics context methods can be "installed" (assinged) declaratively or programmatically.

Consider for example the included SimpleCell renderer. Instead of calling gc.fillText it calls a custom method gc.simpleText. The default for gc.simpleText is preset to gc.fillText on grid instantiation; if you don't override it, you get the default fillText functionality. (See Defining alias defaults below.)

Declarative installation

Declarative installation is made before grid instantiation. Use this type of installation when you know which custom method implementation to use for a custom method.

To assign an implementation to simpleText declaratively, add it to the graphics object.

var graphics = fin.Hypergrid.lib.graphics; // if using build file
var graphics = require('fin-hypergrid/src/lib/graphics'); // if using npm module
graphics.simpleText = myCustomFillTextMethod;

All members of this object are automatically assigned to each grid's graphics context objects (grid.canvas.gc and grid.canvas.bs) on instantiation.

Programmatic installation

Programmatic installation is made to a running grid (after instantiation). Use this type of installation when you need to assign or reassign custom methods on the fly based on logic only known at run-time.

To override an aliased method with a custom implementation programmatically:

var grid = new Hypergrid;
grid.canvas.gc.simpleText = grid.canvas.bc.simpleText = myCustomFillTextMethod;

Defining alias defaults

The default graphics context aliases (method synonyms) are defined in src/lib/Canvas.js:

var Canvas = fin.Hypergrid.lib.Canvas; // if using build file
var Canvas = require('fin-hypergrid/src/lib/Canvas'); // if using npm module
Canvas.graphicsContextAliases = {
    simpleText: 'fillText'
};

For example, to register altFont as an alias for gc.font, do the following before instantiating any grid objects:

Canvas.graphicsContextAliases.altFont = 'font';

In general, all cell renderers that use custom methods should set their defaults as shown above in case no implementation is assigned before the method is called. If you don't set a default, you must assign an implementation declaratively before it is needed.

To summarize: On instantiation, each grid gets a Canvas object with a gc (graphics context) object (and a similar bc object) with all aliases pre-assigned as synonyms for their named methods. After instantiation, grid.canvas.gc.simpleText will hold a reference to grid.canvas.gc.fillText. Unless overridden, calls to the former are exactly equivalent to calls to the latter in terms of performance (and in every other way).