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]

document sidebar canvas list

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:

cnvs = document.windows[0].selection.canvas

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).

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.

cnvs = addCanvas() cnvs.size = new Size(1600, 1200)
omnigraffle:///omnijs-run?script=addCanvas%28%29%0Acnvs%2Esize%20%3D%20new%20Size%281600%2C%201200%29

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:

addCanvas().size = new Size(1600, 1200)
omnigraffle:///omnijs-run?script=cnvs%20%3D%20addCanvas%28%29%2Esize%20%3D%20new%20Size%281600%2C%201200%29

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:

if (canvases.length > 1){ cnvs = document.windows[0].selection.canvas cnvs.remove() }
omnigraffle:///omnijs-run?script=if%20%28canvases%2Elength%20%3E%201%29%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09cnvs%2Eremove%28%29%0A%7D

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:

for(var i = canvases.length; i--;) { if(i != 0){canvases[i].remove()} }
omnigraffle:///omnijs-run?script=for%28var%20i%20%3D%20canvases%2Elength%3B%20i--%3B%29%20%7B%20%0A%09if%28i%20%21%3D%200%29%7Bcanvases%5Bi%5D%2Eremove%28%29%7D%0A%7D

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.

if (canvases.length > 1){ var cnvs = document.windows[0].selection.canvas if(cnvs.id != canvases[0].id){ cnvs.orderBefore(canvases[0]) } }
omnigraffle:///omnijs-run?script=if%20%28canvases%2Elength%20%3E%201%29%7B%0A%09var%20cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09if%28cnvs%2Eid%20%21%3D%20canvases%5B0%5D%2Eid%29%7B%0A%09%09cnvs%2EorderBefore%28canvases%5B0%5D%29%0A%09%7D%0A%7D

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.

if (canvases.length > 1){ var cnvs = document.windows[0].selection.canvas if(cnvs.id != canvases[canvases.length-1].id){ cnvs.orderAfter(canvases[canvases.length-1]) } }
omnigraffle:///omnijs-run?script=if%20%28canvases%2Elength%20%3E%201%29%7B%0A%09var%20cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09if%28cnvs%2Eid%20%21%3D%20canvases%5Bcanvases%2Elength-1%5D%2Eid%29%7B%0A%09%09cnvs%2EorderAfter%28canvases%5Bcanvases%2Elength-1%5D%29%0A%09%7D%0A%7D

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.

if (canvases.length > 1){ var cnvs = document.windows[0].selection.canvas if(cnvs.id != canvases[0].id){ cnvs.orderBefore(canvases[0]) } for(var i = canvases.length; i--;) { if(i != 0){canvases[i].remove()} } }
omnigraffle:///omnijs-run?script=if%20%28canvases%2Elength%20%3E%201%29%7B%0A%09var%20cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09if%28cnvs%2Eid%20%21%3D%20canvases%5B0%5D%2Eid%29%7B%0A%09%09cnvs%2EorderBefore%28canvases%5B0%5D%29%0A%20%20%20%20%7D%0A%09for%28var%20i%20%3D%20canvases%2Elength%3B%20i--%3B%29%20%7B%20%0A%09%09if%28i%20%21%3D%200%29%7Bcanvases%5Bi%5D%2Eremove%28%29%7D%0A%09%7D%0A%7D

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.

UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER