Canvas

The canvas is the big white area in the center of OmniGraffle’s interface where you draw and create things. An OmniGraffle project (document) always contains at least one canvas and one layer.

An OmniGraffle document can contain many canvases, of varying sizes and with a variety of properties and settings. For example, an OmniGraffle document may contain a canvas that is 1600 points by 1200 points, a canvas that is 768 points by 1024 points, a canvas that is 400 points by 400 points, and even a canvas that adjusts its size to fit the objects drawn upon it.

In the document window’s sidebar (on the left), canvases are displayed as a list with the topmost canvas in the list having the lowest numeric position, which is the first cavas, but in JavaScript terms, has a 0 index. In the image below, the OmniGraffle document has four canvases, with the canvas named “Canvas 1” at the top of the list of canvases. In JavaScript, it would be identified as: canvases[0]

The last canvas in the list of canvases, the one named “Canvas 4” is identified in JavaScript as canvases[3]

Also, as an aide for precision, a canvas can display a grid that optionally may cause drawn or imported objects to snap to its lines.

Canvases in OmniGraffle are totally flexible in their implementation and abilities. This section examines how to script canvases in OmniGraffle.

DO THIS ► Install the  Canvas Tools  plug-in, a collection of actions for manipulating canvases in OmniGraffle.

The Current Canvas

Many of your scripts will probably be designed to work with objects selected by the user. If a document has five canvases, your script cannot assume that the canvas currently being worked on by the user, is the topmost canvas. Scripts need to know what is the “current canvas.”

In the image above, the current canvas is named “Canvas 3.” However, since scripts can’t “see” the application interface, they have to derive the current canvas by asking for the canvas object that is the value of the canvas property of the document window’s selection. In scripting the “current canvas” can be derived with this script statement:

Canvas Reference

Canvases are an element of the Portfolio class, an invisible representation of the current document, and therefore do not need to referenced by their position in the document hierarchy within scripts. In other words, instead of entering:

app.documents[0].canvases[0]

to indicate the topmost canvas, you simply enter:

canvases[0]

(TIP: see the Big Picture page for more details).

Selecting Canvases

An instance of the canvas class can be assigned as the value for the canvas property of the document selection object. In that way, you can select each of the existing canvases one-at-a-time:

or even select a specific canvas by name:

Here’s a plug-in that will select the canvas chosen from the presented menu of canvas titles:

Add a Canvas

And because canvases are an element of the Portfolio, you use the addCanvas() method of the Portfolio class to create a new canvas. The result of that method is a reference to the newly created canvas, which can be stored in a variable to reference the canvas later in the script.

In the example script above the value of the canvas’ size property is set by creating a new Size object using the desired canvas width and canvas height, in points. Scripts always use points when getting and setting the size of a canvas.

If storing a reference to the created canvas is not essential, you can combine the creation and setting of canvas dimensions into a single-line script, as shown in the example below:

Delete a Canvas

To delete a canvas from the document, use the remove() method on an instance of a canvas. The following example script deletes the current canvas after checking that there are multiple canvases in the document:

To delete a contiguous series of canvases, start with the last and iterate to the topmost canvas, as shown in this script that removes all canvases except the top one:

Name a New Canvas

The name property of a canvas can be read and changed. The following scrpt is an example of creating a new canvas whose name is, or an incrementation of, a specific name. More naming examples are on this page.

Move a Canvas

Canvases can be reordered within the stack of canvases. To change the stack position of a canvas, use the orderBefore() and orderAfter() methods. These instance methods take a direct parameter that is an object reference to canvas that the moved canvas is placed before or after.

In the following example, the current canvas is moved to the top of the stack of canvases. Note the conditional statement (line 3) that compares the value of the id property of the current canvas with the value of the id property of the top canvas, to ensure that the current canvas is not already the topmost canvas.

And the example below uses the orderAfter() method to move the current canvas to the bottom of the stack of canvases. This script also performs a compariosn using the canvas id property (line 3) to ensure that the canvas to be moved is not already the bottom canvas.

Move and Delete

In this example script, the orderBefore() and the remove() methods from the Canvas class are used to essentially delete every canvas except the one that is the current canvas.

This task is accomplished by first moving the current canvas to the top, and then deleting the remaining canvases starting at the bottom and iterating to the top. Note the conditional statement (line 3) that compares the value of the id property of the current canvas with the value of the id property of the top canvas, to ensure that the current canvas is not already the topmost canvas.

Other Canvas Instance Methods

The following instance methods of the Canvas class are covered in other sections of this website. Click|Tap on the method name to go the related page.

• addText(textString, graphicOrigin) (Solid) • Create a new shape containing text (with no stroke or shadow) and place it on the first visible layer.

• addShape(shapeNameString, boundsRect) (Shape) • Create a new graphic of a given shape and place it on the first visible layer.

• newShape() (Shape) • Create a zero-sized rectangle (presumably to be modified further) and place it on the first visible layer.

• newLayer() (Layer) • Create a new (top-most) layer.

• connect(fromGraphic, toGraphic) (Line) • Create a zero-sized rectangle (presumably to be modified further) and place it on the first visible layer.

• addLine(startPoint, endPoint) (Line) • Create a new line between two points and place it on the first visible layer.

• newLine() (Line) • Create a new zero-length line (presumably to be modified further) and place it on the first visible layer.

• duplicate(arrayOfGraphics) (Graphics) • Duplicate existing graphics onto new graphics placed upon this canvas. The original graphics may be from elsewhere - such as from another canvas, a stencil, or another document.

• graphicWithId(idNumber) (Graphic) • Get the graphic with the given id, if it exists on this canvas.

• graphicWithName(nameString) (Graphic) • Get the first graphic with the given name, if any.

• allGraphicsWithUserDataForKey(dataString, keyString) (Graphics) • Get all graphics with the given data string for the user data key.

• graphicWithUserDataForKey(dataString, keyString)(Graphic) • Get the first graphic with the given data string for the user data key, if any.