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:
The Current Canvas | ||
01 | 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).
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:
Select Canvases One-at-a-Time | ||
01 | var docView = document.windows[0].selection.view | |
02 | canvases.forEach(function(cnvs){ | |
03 | docView.canvas = cnvs | |
04 | console.log(cnvs.name) | |
05 | }) |
or even select a specific canvas by name:
Select a Canvas by Name | ||
01 | var docView = document.windows[0].selection.view | |
02 | var targetName = "Tulip" | |
03 | var flag = true | |
04 | canvases.forEach(function(cnvs){ | |
05 | if(flag && cnvs.name == targetName){ | |
06 | docView.canvas = cnvs | |
07 | flag = false | |
08 | } | |
09 | }) |
Here’s a plug-in that will select the canvas chosen from the presented menu of canvas titles:
Select Chosen Canvas | ||
01 | /*{ | |
02 | "type": "action", | |
03 | "targets": ["omnigraffle"], | |
04 | "author": "Otto Automator", | |
05 | "identifier": "com.omni-automation.og.select-chosen-canvas", | |
06 | "version": "1.0", | |
07 | "description": "Selects the canvas chosen from menu of canvas names.", | |
08 | "label": "Select Chosen Canvas", | |
09 | "shortLabel": "Select Canvas" | |
10 | }*/ | |
11 | (() => { | |
12 | var action = new PlugIn.Action(function(selection, sender){ | |
13 | // action code | |
14 | // selection options: canvas, document, graphics, lines, solids, view | |
15 | ||
16 | var canvasObjects = new Array() | |
17 | var canvasTitles = new Array() | |
18 | var menuIndexes = new Array() | |
19 | canvases.forEach((cnvs, index) => { | |
20 | canvasObjects.push(cnvs) | |
21 | canvasTitles.push(cnvs.name) | |
22 | menuIndexes.push(index) | |
23 | }) | |
24 | ||
25 | var canvasesMenu = new Form.Field.Option( | |
26 | "canvasesMenu", | |
27 | null, | |
28 | menuIndexes, | |
29 | canvasTitles, | |
30 | 0 | |
31 | ) | |
32 | ||
33 | var form = new Form() | |
34 | form.addField(canvasesMenu) | |
35 | var formPrompt = "Choose the canvas to select:" | |
36 | var buttonTitle = "Continue" | |
37 | var formPromise = form.show(formPrompt, buttonTitle) | |
38 | ||
39 | // PROCESS THE FORM RESULTS | |
40 | formPromise.then(function(formObject){ | |
41 | // RETRIEVE CHOSEN VAUES | |
42 | var menuIndex = formObject.values['canvasesMenu'] | |
43 | var chosenCanvas = canvasObjects[menuIndex] | |
44 | var docView = document.windows[0].selection.view | |
45 | docView.canvas = chosenCanvas | |
46 | }) | |
47 | ||
48 | }); | |
49 | ||
50 | action.validate = function(selection, sender){ | |
51 | // validation code | |
52 | // selection options: canvas, document, graphics, lines, solids, view | |
53 | return true | |
54 | }; | |
55 | ||
56 | return action; | |
57 | })(); |
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.
Create a Canvas | ||
01 | cnvs = addCanvas() | |
02 | cnvs.size = new Size(1600, 1200) |
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:
Create a New Canvas | ||
01 | addCanvas().size = new Size(1600, 1200) |
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:
Delete the Current Canvas | ||
01 | if (canvases.length > 1){ | |
02 | cnvs = document.windows[0].selection.canvas | |
03 | cnvs.remove() | |
04 | } |
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:
Delete all Except the Top Canvas | ||
01 | for(var i = canvases.length; i--;) { | |
02 | if(i != 0){canvases[i].remove()} | |
03 | } |
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.
Name Canvas with Base Name | ||
01 | cnvs = addCanvas() | |
02 | baseName = "My Canvas Name" | |
03 | versName = "My Canvas Name" | |
04 | cnvsNames = canvases.map(function(cnvs){return cnvs.name}) | |
05 | counter = 0 | |
06 | while (cnvsNames.includes(versName)){ | |
07 | counter = counter + 1 | |
08 | versName = baseName + "-v" + String(counter) | |
09 | } | |
10 | cnvs.name = versName |
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.
Move the Current Canvas to the Top | ||
01 | if (canvases.length > 1){ | |
02 | var cnvs = document.windows[0].selection.canvas | |
03 | if(cnvs.id != canvases[0].id){ | |
04 | cnvs.orderBefore(canvases[0]) | |
05 | } | |
06 | } |
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 Current Canvas to the Bottom | ||
01 | if (canvases.length > 1){ | |
02 | var cnvs = document.windows[0].selection.canvas | |
03 | if(cnvs.id != canvases[canvases.length-1].id){ | |
04 | cnvs.orderAfter(canvases[canvases.length-1]) | |
05 | } | |
06 | } |
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.
Delete All Canvases Except the Current Canvas | ||
01 | if (canvases.length > 1){ | |
02 | var cnvs = document.windows[0].selection.canvas | |
03 | if(cnvs.id != canvases[0].id){ | |
04 | cnvs.orderBefore(canvases[0]) | |
05 | } | |
06 | for(var i = canvases.length; i--;) { | |
07 | if(i != 0){canvases[i].remove()} | |
08 | } | |
09 | } |
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.
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.