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:

Using the background property to change the fill color of the current canvas:

graphic = document.windows[0].selection.canvas.background graphic.fillColor = Color.gray
omnigraffle:///omnijs-run?script=graphic%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%2Ebackground%0Agraphic%2EfillColor%20%3D%20Color%2Egray
 

CanvasSizingMode Properties

The CanvasSizingMode properties are the value for the canvasSizingMode property (note lowercase c) of the Canvas class:

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.

autosizecontrols

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:

cnvs = document.windows[0].selection.canvas cnvs.canvasSizingMode = CanvasSizingMode.Fit cnvs.autosizesDown = true cnvs.autosizesLeft = true cnvs.autosizesRight = false cnvs.autosizesUp = false
omnigraffle:///omnijs-run?script=cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0Acnvs%2EcanvasSizingMode%20%3D%20CanvasSizingMode%2EFit%0Acnvs%2EautosizesDown%20%3D%20true%0Acnvs%2EautosizesLeft%20%3D%20true%0Acnvs%2EautosizesRight%20%3D%20false%0Acnvs%2EautosizesUp%20%3D%20false

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:

cnvs = document.windows[0].selection.canvas cnvs.autosizesUp = cnvs.autosizesDown = cnvs.autosizesLeft = cnvs.autosizesRight = false
omnigraffle:///omnijs-run?script=cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0Acnvs%2EautosizesUp%20%3D%20cnvs%2EautosizesDown%20%3D%20cnvs%2EautosizesLeft%20%3D%20cnvs%2EautosizesRight%20%3D%20false

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

cnvs = document.windows[0].selection.canvas cnvs.canvasSizingMode = CanvasSizingMode.Fixed cnvs.size = new Size(cnvs.pageSize.width, cnvs.pageSize.height)
omnigraffle:///omnijs-run?script=cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0Acnvs%2EcanvasSizingMode%20%3D%20CanvasSizingMode%2EFixed%0Acnvs%2Esize%20%3D%20new%20Size%28cnvs%2EpageSize%2Ewidth%2C%20cnvs%2EpageSize%2Eheight%29
page setup sheet

And a version for sizing every canvas:

canvases.forEach(function(cnvs){ cnvs.canvasSizingMode = CanvasSizingMode.Fixed cnvs.size = new Size(cnvs.pageSize.width, cnvs.pageSize.height) })
omnigraffle://localhost/omnijs-run?script=canvases%2EforEach%28function%28cnvs%29%7B%0A%09cnvs%2EcanvasSizingMode%20%3D%20CanvasSizingMode%2EFixed%0A%09cnvs%2Esize%20%3D%20new%20Size%28cnvs%2EpageSize%2Ewidth%2C%20cnvs%2EpageSize%2Eheight%29%0A%7D%29

And for those times when you’re designing interfaces for specific devices, having the ability to quickly create templates is very useful:

[a, b] = [2048, 1536].slice() addCanvas().size = new Size(a, b) addCanvas().size = new Size(b, a)
omnigraffle:///omnijs-run?script=%5Ba%2C%20b%5D%20%3D%20%5B2048%2C%201536%5D%2Eslice%28%29%0AaddCanvas%28%29%2Esize%20%3D%20new%20Size%28a%2C%20b%29%0AaddCanvas%28%29%2Esize%20%3D%20new%20Size%28b%2C%20a%29

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.

var currentCanvas = document.windows[0].selection.canvas currentCanvas.name = currentCanvas.name + ' DRAFT'
omnigraffle://localhost/omnijs-run?script=var%20currentCanvas%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0AcurrentCanvas%2Ename%20%3D%20currentCanvas%2Ename%20%2B%20%27%20DRAFT%27

To get a list of the names of the canvases in a document, use the JavaScript map() method:

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:

canvasNames = canvases.map(function(cnvs){return cnvs.name}) canvasNames.includes('name to compare')

And here is a script showing how to name the current canvas a unique name:

canvasName = "Name for Canvas" currentCanvas = document.windows[0].selection.canvas canvasNames = canvases.map(function(cnvs){return cnvs.name}) if (canvasNames.includes(canvasName)){ alertMsg = "There is already a canvas named: " + canvasName new Alert('Naming Error',alertMsg).show(function(result){}) } else { currentCanvas.name = canvasName }

And a script that creates a new canvas and names it an incrementation of a specific name:

cnvs = addCanvas() baseName = "My Canvas Name" versName = "My Canvas Name" cnvsNames = canvases.map(function(cnvs){return cnvs.name}) counter = 0 while (cnvsNames.includes(versName)){ counter = counter + 1 versName = baseName + "-v" + String(counter) } 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:

cvss = canvases.reverse() for(i = 0; i < cvss.length; i++){ nmeNum = i + 1 canvases[i].name = 'Canvas ' + nmeNum }
omnigraffle:///omnijs-run?script=cvss%20%3D%20canvases%2Ereverse%28%29%0Afor%28i%20%3D%200%3B%20i%20%3C%20cvss%2Elength%3B%20i%2B%2B%29%7B%0A%09nmeNum%20%3D%20i%20%2B%201%0A%09canvases%5Bi%5D%2Ename%20%3D%20%27Canvas%20%27%20%2B%20nmeNum%0A%7D

Here is a script function for returning a reference to a canvas specified by its name:

function getCanvasNamed(canvasName){ for (let cnvs of canvases){ if (cnvs.name.localeCompare(canvasName) === 0){return cnvs} } errorString = "There is no canvas named: " + canvasName new Alert('ERROR', errorString).show(function(result){}) throw new Error(errorString) } getNamedCanvas('iPad Horizontal')

And here is a script that creates and names a canvas for each month of the year:

function addCanvasForEveryMonth(){ locale = "en-us" curYearStr = String(new Date().getFullYear()) mths = new Array() for (i = 1; i < 12; i++) { var date = new Date(i + "/1/" + curYearStr), month = date.toLocaleString(locale, { month: "long" }) mths.push(month) } sze = document.windows[0].selection.canvas.size canvasNames = canvases.map(function(cnvs){ return cnvs.name }) mths.forEach(function(mth){ if(canvasNames.indexOf(mth) === -1){ cnvs = addCanvas() cnvs.name = mth cnvs.size = sze } }) } addCanvasForEveryMonth()
omnigraffle:///omnijs-run?script=function%20addCanvasForEveryMonth%28%29%7B%0A%09locale%20%3D%20%22en-us%22%0A%09mths%20%3D%20new%20Array%28%29%0A%09for%20%28i%20%3D%201%3B%20i%20%3C%2012%3B%20i%2B%2B%29%20%7B%20%0A%09%09var%20date%20%3D%20new%20Date%28i%20%2B%20%22%2F1%2F2017%22%29%2C%0A%09%09month%20%3D%20date%2EtoLocaleString%28locale%2C%20%7B%20month%3A%20%22long%22%20%7D%29%0A%09%09mths%2Epush%28month%29%0A%09%7D%0A%09sze%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%2Esize%0A%09canvasNames%20%3D%20new%20Array%28%29%0A%09canvases%2EforEach%28function%28canvas%29%7B%0A%09%09canvasNames%2Epush%28canvas%2Ename%29%0A%09%7D%29%0A%09mths%2EforEach%28function%28mth%29%7B%0A%09%09if%28canvasNames%2EindexOf%28mth%29%20%3D%3D%3D%20-1%29%7B%0A%09%09%09cnvs%20%3D%20addCanvas%28%29%0A%09%09%09cnvs%2Ename%20%3D%20mth%0A%09%09%09cnvs%2Esize%20%3D%20sze%0A%09%09%7D%0A%09%7D%29%0A%7D%0AaddCanvasForEveryMonth%28%29
 

CanvasSizingMode Properties

The VerticalAlignment properties are the value for the columnAlignment property of the Canvas class:

 

HorizontalAlignment Properties

The HorizontalAlignment properties are the value for the rowAlignment property of the Canvas class:

 

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.

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