Skip to content

Home

Jump to bottom
edurocher edited this page Jan 29, 2014 · 9 revisions

This repository contains a prototype implementation of GFX, the portable 2D JavaScript graphics library, based on Dojo 2.0. The starting point of this code is the dojox/gfx module from Dojo 1.9, and it will evolve until the Dojo 2.0 release. This wiki will describe the updates as they are implemented.

Dependencies and Installation

GFX uses the following modules:

  • The GFX library code uses the Dojo core and also (for now) some Dojox legacy modules.
  • All GFX classes are based on the uhop/dcl OOP library.
  • Surface and Shape classes use delite/Stateful.js, so you muse also clone the ibm-js/delite repository.
  • The tests and demos use Dijit widgets and the DOH framework.

So the directory structure should look like the following:

parentDir
    dcl                      The DCL OOP library (a clone of https://github.com/uhop/dcl)
    delite                   The delite widget framework (a clone of https://github.com/ibm-js/delite)
    dijit                    Dojo widgets, clone of https://github.com/dojo/dijit (for tests and demos)
    dojo                     Dojo core, clone of https://github.com/dojo/dojo
    dojox                    Clone of https://github.com/dojo/dojox (see below)
    gfx                      This repository (https://github.com/ibm_dojo/gfx)
    util                     Clone of https://github.com/dojo/util
        doh                  DOH test framework (for tests and demos)

Uses of legacy DojoX Modules

The GFX library code has the following dependencies:

  • gfx/_bidi requires dojox/string/BidiEngine

So, applications not using Bidi support are already completely independent of legacy dojox code.

In addition, some performance tests require dojox/charting (and, indirectly, the legacy dojox/gfx) to display results.

Current Status

Namespace

  • The dojox.gfx namespace is changed to the toplevel gfx namespace.

Renderers

  • As of Dojo 2.0, only the SVG and Canvas renderers are officially supported. Both are supported on all targeted browsers, so there no automatic detection any more. By default, the SVG renderer is used, except if has("gfx-renderer") is set to "canvas".
  • The VML, and Silverlight renderers have been removed, as well as the SVGWeb support in the SVG renderer.
  • The canvasWithEvents has been moved to gfx-experimental (see below).

Full AMD-fication

  • All demos and tests have been converted to AMD loader syntax and HTML5 compliant attributes (data-dojo-*).
  • Each shape class is now in its own AMD module in the shape/ directory, for example, gfx/shape/Shape.js, gfx/shape/Rect.js etc.
  • Each renderer has its own subdirectory containing the shape subclasses, for example gfx/svg/Shape.js, gfx/svg/Rect.js, etc.
  • The shape.js, svg.js, canvas.js and canvasWithEvents.js modules are still here for compatibility, now they simply require all the corresponding shape classes.

No Globals / Using several renderers

  • Up to Dojo 1.9, the mechanism to use a given renderer is based on setting class and function pointers as properties of the dojox/gfx module object, for example the gfx.createSurface function, the gfx.Rect class, etc. It was possible to switch from a renderer to another using gfx.switchTo(), but this would be a global change since there is only one instance of the dojox/gfx module loaded in a given JavaScript context.
  • This is now changed as follows.
    • Each renderer defines a Surface class, which can be instantiated without using a global function. For example:
        require(["gfx/svg/Surface"], function(Surface) {
            new Surface("surface_div", 500, 400);
        });
  • The renderer-specific Surface classes can then be used to create shapes using the existing createRect etc. functions, thus allowing an application to cleanly use several renderers in parallel. See tests/test_multi.html for an example.
  • There is also a new generic gfx/Surface class available, which requires the renderer-specific Surface class specified by the "gfx-renderer" has flag (see below). For example:
    <script type="text/javascript" src="../dojo/dojo.js" data-dojo-config="has:{'gfx-renderer':'canvas'}">
    </script>
    ...
        require(["gfx/Surface"], function(Surface) {
            new Surface("surface_div", 500, 400);
        });

If `gfx-renderer` was set to `svg` for instance, then the `gfx/Surface` module will actually return the `gfx/svg/Surface` class.

Using shapes

Each shape class is now defined in its own AMD module, so an application can choose to require only the shapes it actually uses. For convenience, a shapes module that loads all the classes is available for each renderer (for example, gfx/svg/shapes loads all SVG shapes). In addition, the gfx/shapes module loads all the shapes for the renderer specified by the "gfx-renderer" has flag.

Config/has flags

The dojoConfig.gfxRenderer flag is replaced by the "has" flag gfx-renderer. For example:

    <script type="text/javascript" src="../dojo/dojo.js" data-dojo-config="gfxRenderer: 'canvas'">
    </script>

should be replaced by:

    <script type="text/javascript" src="../dojo/dojo.js" data-dojo-config="has:{'gfx-renderer':'canvas'}>
    </script>

Other `dojoConfig` flags do not have any effect any more due to the new renderer selectino mechanism. The `dojoConfig/gfxRenderer` flag can still be used for now, they it be removed before 2.0 is released.

Dojo 1.9 Compatibility

The gfx/compat module ensures a level of compatibility with the 1.9 API by doing the following:

  • add the createSurface function to the toplevel gfx module value
  • define the switchTo function
  • require all shape classes

For now, this compatibility module is automatically required by gfx/gfx.js, causing all 1.9 tests and apps that just require gfx/gfx to run with this 2.0 version. In the future, when all tests and demos are migrated, this will probably not be the case any more and gfx/compat should be removed altogether.

Some modules moved to gfx-experimental

Some Dojo GFX modules that existed in Dojo 1.X but were never completely finished or that we think are not worth the maintenance effort have been moved to a separate gfx-experimental repository. These modules are currently:

  • The canvasWithEvents renderer: the reasoning is that if you need event handling on individual shapes, you can always use the SVG renderer. So, given the amount of tricky code in the canvasWithEvents renderer, we prefer to avoid maintaining it in future releases.
  • The svg_attach module: we realize this could be useful to import an existing SVG scene and manipulate it using the simpler GFX APIs. Unfortunately it would be a big effort to support this completely (the current implementation is far from complete). So again we prefer not to maintain this.

Migration to DCL

All GFX classes are now defined using the uhop/dcl OOP library, instead of the Dojo 1.X dojo/_base/declare module. This does not change the GFX APIs, except if you need to subclass a GFX class. In that case, you should also use dcl.

ECMAScript 5 Getters and Setters

All shape properties are converted to ES5 properties with getters and setters, so for example myShape.setShape(newShape) is replaced by myShape.shape = newShape. Thew new properties include stroke, fill, font, clip, and textDir when Bidi support is enabled.

Bidi support

The Dojo 1.X _gfxBidiSupport module is replaced by the same mechanism used in other Dojo modules: Bidi support is now enabled by setting the dojo-bidi has flag. When has("dojo-bidi") is truthy, some GFX classes are automatically extended by Bidi mixins to support bidi languages correctly, and the textDir property is added to all shapes to be able to control text direction individually on each shape.

Clone this wiki locally