Canvas Properties
A OmniGraffle canvas, like most scriptable objects, has properties that define its characteristics and abilities. In the previous section, the canvas properties of id and size were used in script examples to create and move canvases within an OmniGraffle document. This section further examines the canvas properties of name, size, and autosize, and how they are used in common scripting scenarios.
Here’s the complete list of canvas properties:
autosizesDown (boolean) • Should the canvas automatically grow when graphics are added below the current bounds.
autosizesLeft (boolean) • Should the canvas automatically grow when graphics are added to the left of the current bounds.
autosizesRight (boolean) • Should the canvas automatically grow when graphics are added to the right of the current bounds.
autosizesUp (boolean) • Should the canvas automatically grow when graphics are added above the current bounds.
background (Solid r/o) • A solid graphic representing the canvas background. Its fill and image properties determine the canvas background appearance.
canvasSizingMode (CanvasSizingMode) • The method used to determine how the canvas is sized and displayed.
columnAlignment (VerticalAlignment) • Setting for how graphics ought to be aligned vertically.
columnSpacing (Number) • Setting for how graphics ought to be spaced out vertically.
graphics (array of Graphics r/o) • All graphics upon this canvas.
grid (Grid r/o) • Settings for the major and minor grids, if any.
horizontalPages (Number) • Number of printer pages wide.
id (Number r/o) • A unique (within this document) identifying number for this canvas.
layers (array of Layers r/o) • All layers of this canvas.
layoutInfo (Layout r/o) • The automatic layout information describing how graphics should be arranged.
name (String) • The title of this canvas.
outlineRoot (OGOutlineNode r/o) • Builds a model of all shapes in the canvas as a hierarchical outline (as in hierarchical auto layout) and returns the root of that outline.
pageSize (Size r/o) • Size of each page in points.
rowAlignment (HorizontalAlignment) • Setting for how graphics ought to be aligned horizontally.
rowSpacing (Number) • Setting for how graphics ought to be spaced out horizontally.
size (Size) • Overall size in points.
verticalPages (Number) • Number of printer pages tall.
Using the background property to change the fill color of the current canvas:
Set Canvas Fill Color | ||
01 | graphic = document.windows[0].selection.canvas.background | |
02 | graphic.fillColor = Color.gray |
CanvasSizingMode Properties
The CanvasSizingMode properties are the value for the canvasSizingMode property (note lowercase c) of the Canvas class:
Fit • (Flexible) Resizes to fit its contents.
Fixed • Specific size in pages or in points.
Infinite • No specific size and no canvas edges.
Auto-Size
In an OmniGraffle document, the size (width/height) of canvases may vary. They all may have the same dimensions or not, it’s up to you.
And for those situations where you want the canvas to tightly wrap the graphics it contains, there are autosize options to have one or more of the dimension directions automatically size itself to snug the outermost graphic in that direction.
NOTE: the value of the canvas canvasSizingMode property must be set to Fit for these properties to be effective.
In the illustration above, autosizing is active for the left and downward directions. In terms of scripting, there are four canvas autosizing properties: autosizesDown, autosizesLeft, autosizesRight, and autosizesUp. Each property has a boolean value of either true or false indicating whether the autosize property is active or not.
In the script example below, four script statements are used to set the values of the four autosizing properties:
Set Auto-Sizing Controls of Current Canvas | ||
01 | cnvs = document.windows[0].selection.canvas | |
02 | cnvs.canvasSizingMode = CanvasSizingMode.Fit | |
03 | cnvs.autosizesDown = true | |
04 | cnvs.autosizesLeft = true | |
05 | cnvs.autosizesRight = false | |
06 | cnvs.autosizesUp = false |
However, if you want to set all four autosizing properties to the same boolean value, you can use the following JavaScript construct to do it with one script statement:
Set All Auto-Sizing Controls of Current Canvas to the Same Value | ||
01 | cnvs = document.windows[0].selection.canvas | |
02 | cnvs.autosizesUp = cnvs.autosizesDown = cnvs.autosizesLeft = cnvs.autosizesRight = false |
IMPORTANT: if an auto-sizing property has been enabled, and then disabled, the size of the canvas prior to applying auto-sizing, will not be automatically restored.
Size
Setting the dimensions of a canvas can be very useful, especially if the canvas is to be printed or exported for use with specific sized displays.
Here is a script example of how to size a canvas to match the current settings in the Page Setup dialog (macOS).
Set Size of Current Canvas to Match Page Setup | ||
01 | cnvs = document.windows[0].selection.canvas | |
02 | cnvs.canvasSizingMode = CanvasSizingMode.Fixed | |
03 | cnvs.size = new Size(cnvs.pageSize.width, cnvs.pageSize.height) |
And a version for sizing every canvas:
Size Every Canvas to Match Page Setup | ||
01 | canvases.forEach(function(cnvs){ | |
02 | cnvs.canvasSizingMode = CanvasSizingMode.Fixed | |
03 | cnvs.size = new Size(cnvs.pageSize.width, cnvs.pageSize.height) | |
04 | }) |
And for those times when you’re designing interfaces for specific devices, having the ability to quickly create templates is very useful:
Add Canvases for iPad | ||
01 | [a, b] = [2048, 1536].slice() | |
02 | addCanvas().size = new Size(a, b) | |
03 | addCanvas().size = new Size(b, a) |
Name
In complex documents, canvas names can provide clarity, navigation, and the structure for exporting content. The value of the name property of a canvas is a text string that can be both read and changed.
For example, the following script both gets the name of the current canvas, and changes its name by appending the word “DRAFT” to the end of the name.
Appending to a Canvas Name | ||
01 | var currentCanvas = document.windows[0].selection.canvas | |
02 | currentCanvas.name = currentCanvas.name + ' DRAFT' |
To get a list of the names of the canvases in a document, use the JavaScript map() method:
Get Canvas Names | ||
01 | canvases.map(function(cnvs){return cnvs.name}) |
And to check if a canvas with a specific name is in the document, use the JavaScript includes() method, which has a result that is either true or false:
Exist Canvas Named… | ||
01 | canvasNames = canvases.map(function(cnvs){return cnvs.name}) | |
02 | canvasNames.includes('name to compare') |
And here is a script showing how to name the current canvas a unique name:
Name Canvas with Unique Name | ||
01 | canvasName = "Name for Canvas" | |
02 | currentCanvas = document.windows[0].selection.canvas | |
03 | canvasNames = canvases.map(function(cnvs){return cnvs.name}) | |
04 | if (canvasNames.includes(canvasName)){ | |
05 | alertMsg = "There is already a canvas named: " + canvasName | |
06 | new Alert('Naming Error',alertMsg).show(function(result){}) | |
07 | } else { | |
08 | currentCanvas.name = canvasName | |
09 | } |
And a script that creates a new canvas and names it an incrementation of a specific name:
Name New Canvas with Base Name or Incremented Variation | ||
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 |
If you re-order the canvases in a document but want the new order to be reflected in the canvas names, here the script:
Rename Canvases to Match Order | ||
01 | cvss = canvases.reverse() | |
02 | for(i = 0; i < cvss.length; i++){ | |
03 | nmeNum = i + 1 | |
04 | canvases[i].name = 'Canvas ' + nmeNum | |
05 | } |
Here is a script function for returning a reference to a canvas specified by its name:
Get Canvas by Name | ||
01 | function getCanvasNamed(canvasName){ | |
02 | for (let cnvs of canvases){ | |
03 | if (cnvs.name.localeCompare(canvasName) === 0){return cnvs} | |
04 | } | |
05 | errorString = "There is no canvas named: " + canvasName | |
06 | new Alert('ERROR', errorString).show(function(result){}) | |
07 | throw new Error(errorString) | |
08 | } | |
09 | getCanvasNamed('iPad Horizontal') |
And here is a script that creates and names a canvas for each month of the year:
Add Canvas for Every Month | ||
01 | function addCanvasForEveryMonth(){ | |
02 | locale = "en-us" | |
03 | curYearStr = String(new Date().getFullYear()) | |
04 | mths = new Array() | |
05 | for (i = 1; i < 12; i++) { | |
06 | var date = new Date(i + "/1/" + curYearStr), | |
07 | month = date.toLocaleString(locale, { month: "long" }) | |
08 | mths.push(month) | |
09 | } | |
10 | sze = document.windows[0].selection.canvas.size | |
11 | canvasNames = canvases.map(function(cnvs){ | |
12 | return cnvs.name | |
13 | }) | |
14 | mths.forEach(function(mth){ | |
15 | if(canvasNames.indexOf(mth) === -1){ | |
16 | cnvs = addCanvas() | |
17 | cnvs.name = mth | |
18 | cnvs.size = sze | |
19 | } | |
20 | }) | |
21 | } | |
22 | addCanvasForEveryMonth() |
CanvasSizingMode Properties
The VerticalAlignment properties are the value for the columnAlignment property of the Canvas class:
Bottom • Align to bottom edges.
Center • Align to vertical centers.
Top • Align to top edges.
HorizontalAlignment Properties
The HorizontalAlignment properties are the value for the rowAlignment property of the Canvas class:
Center • Align to horizontal centers.
Left • Align to left edges.
Right • Align to right edges.
OGOutlineNode
An outline node is one element of a hierarchical organization of the canvas’s graphics. Each node represents a single shape, with the lines between shapes determining parent-child relationships. The outline structure is visualized in the Mac applications ‘Outline’ sidebar tab.
children (Array of OGOutlineNode r/o) • Child nodes of this node.
graphic (Graphic or nil r/o) • Graphic that this outline node represents.
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.