lib-gwt-svg tries to reach the following goals:
- Provide a clean, GWT-friendly API
- Hide the idiosyncrasies of vendor SVG implementations
- Reuse existing GWT features wherever possible to eliminate code duplication and impedance mismatch
- Stick to the W3C standard, unless it duplicates an existing GWT feature or the GWT feature is too incomplete
Compatibility with SVG, W3C standards and exitsing GWT APIs
The SVG 1.1 specification is built on top of several other specifications. The following table lists each specification, explains whether GWT already has an API addressing it, and whether lib-gwt-svg chooses to reuse it or not. The following subsections provide a more elaborate view of each table row.
|W3C Standard||Goal||Pre-existing GWT APIs||Reuse in lib-gwt-svg|
|DOM Level 2||Define the base model to access the documents displayed by a browser||com.google.gwt.dom.client defines overlay classes for low-level DOM programming. com.google.gwt.user.client also has an Element overlay class. com.google.gwt.user.client.ui defines fundamental user-interface classes.||Mostly.|
|DOM Level 2 views||Provide support for multiple views on the same document||No API||Not supported currently|
|DOM Level 2 events||Define the events occurring as one interacts with a browser document.||GWT already has one low-level event model (com.google.gwt.user.client.DOM) and two high-level models: com.google.gwt.user.client (deprecated) and com.google.gwt.event.dom.client||Mostly.|
|SMIL||Provide support for animation and integration of multimedia content in DOM document||GWT offers com.google.gwt.animation.client.||No.|
|CSS||Define the graphical styles used to render elements||com.google.gwt.dom.client.Style provides Css style support.||Mostly.|
|XLink||Defines linking between documents||GWT provides a com.google.gwt.user.client.ui.Hyperlink which provides integration with History.||Not yet. Planned History integration|
DOM Level 2
GWT has two hierarchies. The low-level class hierarchy in com.google.gwt.dom.client consists mostly in overlay types for HTML elements. The high-level class hierarchy in com.google.gwt.user.client.ui consists in higher level widgets classes which wrap types of the first hierarchy.
lib-gwt-svg uses a similar architecture. The types in org.vectomatic.dom.svg.impl forms the low-level implementation based on overlay types. You should never have to use these types directly. The types in org.vectomatic.dom.svg form the high level implementation which end-users manipulate.
End-users only need to care about DOM Level 2 in the following scenarios:
- when they need to insert their DOM tree in the HTML tree: lib-gwt-svg automatically imports the node in the main document and OMElement.getElement() will return a GWT compatible class
- when they need to manipulate the DOM structure: the wrapper types provide DOM-like methods to manipulate the DOM tree (appendChild, removeChild, insertBefore, …). Users should be careful when they use methods to navigate the DOM tree (getNextSibling, getElementById, …). These methods automatically build a wrapper type from the underlying overlay type. While convenient, these method build a new wrapper every time they are called. Thus end-users should either store the returned reference for later use, or do their navigation on the overlay types and convert to wrapper types when needed using OMNode.convert
DOM Level 2 events
The GWT event model is roughly structured like this: a low-level model registers handlers and channels events through a central dispatcher. The dispatcher sends events to a new and extensible event model. The new event level is capable of emulating the deprecated event model. lib-gwt-svg cannot reuse low-level model: it is indeed not extensible and SVG has several events which are specific (onzoom, onrepeat, onfocusin…). Thus this part is re-developed, and you should not try to use event-related methods of com.google.gwt.user.client.DOM. lib-gwt-svg channels events to a central disptacher. The dispatcher sends events to the GWT new event model. This provides compatibilty with existing GWT APIs (notably, mouse event handlers are the same). lib-gwt-svg extends the GWT event model with new classes corresponding to new event types. No effort is made towards compatibility with the deprecated GWT event model.
GWT offers com.google.gwt.animation.client. It consists mostly in timer management and is orthogonal to SMIL. Indeed, SVG SMIL provides support for declarative animation, using animation elements derived from ElementTimeControl. lib-gwt-svg integrates SMIL by providing animation specific events integrated in the GWT event model. However currently only Opera seems to implement them. lib-gwt-svg does not preclude using com.google.gwt.animation.client to update an SVG scene at periodic intervals. Actually, this seems like the only approach to SVG animation today given the limitations of current SVG implementations, Opera excepted.
SVG low-level class hierarchy in com.google.gwt.dom.client provide support for manipulating both the ‘style’ and the ‘className’ CSS attributes. These mechanisms can be reused, but only up to a certain point. Bug 374216 is Firefox breaks the Style.getProperty() and Style.setProperty() on SVG elements. The SVG model itself makes the className an OMSVGAnimatedString instead of a mere String. lib-gwt-svg defines an OMSVGStyle overlay type derived from Style. It provides a pair of getSVGProperty() and setSVGProperty() to bypass Bug 374216. lib-gwt-svg also defines a IStylable interface, which provides methods equivalent to GWT for classname manipulation, but adapted to the constraints of an OMSVGAnimatedString.
GWT provides a com.google.gwt.user.client.ui.Hyperlink which provides integration with History. This class cannot be reused, but the same principles will be implemented in a future version to provide integration between OMSVGAlement and com.google.gwt.user.client.History.