Typings for dojox/gfx

dojox/gfx is Dojo 1.x’s vector graphics library, with support for SVG, Canvas, and other legacy rendering environments through a drawing API based on the semantics of SVG. This API also provides the foundation for dojox/charting. Often the biggest challenge in working with vector graphics is the large number of possible configuration settings and permutations.

TypeScript makes it easier to leverage auto-complete within an editor. We’ve been working for a while to add and maintain typings for Dojo 1.x. One of SitePen’s support clients kindly suggested that it would be very valuable to put gfx and TypeScript together, and happily sponsored our efforts in making this happen!

dojox/gfx

dojox/gfx is one of the largest APIs in Dojo 1.x. The initial commit to add type definitions for dojox/gfx was nearly 1700 lines!

With this addition, it’s now much easier to remember all of the options for various features including shapes, gradients, curves, text, events, filters, matrix operations, paths, and more.

VectorText

For example, suppose you want to remember the options for drawing text along a vector path.

Consider the TypeScript interface definition for VectorText:

declare namespace dojox {
	namespace gfx {
		interface VectorFont {
			family: string;
			size: string;
			type: string;
		}

		interface VectorText {
			align: string;
			decoration: string;
			fitting: number;
			height: number;
			leading: number;
			text: string;
			type: string;
			width: number;
			x: number;
			y: number;

			draw(
				group: dojox.gfx.shape.Container,
				text: Text,
				font: Font,
				fill: Fill,
				stroke: Stroke
			): Group;
			getBaseLine(scale?: number): number;
			getCenterLine(scale?: number): number;
			getLineHeight(scale?: number): number;
			getWidth(text: string, scale?: number): number;
			initialized(): boolean;
			load(url: string): this;
			onLoad(font: VectorText): void;
			onLoadBegin(url: string): void;
		}

		interface VectorTextConstructor extends dojo._base.DeclareConstructor<VectorText> {
			new(url?: string): VectorText;
			prototype: VectorText;
		}
	}
}

declare module 'dojox/gfx/VectorText' {
	type VectorText = dojox.gfx.VectorText;
	const VectorText: dojox.gfx.VectorTextConstructor;
	export = VectorText;
}

There are obviously quite a few details to remember with the above definition! Now, with a modern editor such as VS Code, Atom, WebStorm, vim, or emacs, you will receive auto-complete for these details when creating a new VectorText object with TypeScript.

When an API is necessarily complex, which is the case when providing a general purpose drawing API, TypeScript really shines in making it easier to understand the code and remember the various methods and properties that are available within each API.