Layers

A canvas contains one or more layers, upon which are located the canvas’ elements, such as graphics or images.

Layers are created using the newLayer() instance method of the Canvas class.

Add a New Layer
Copy Try It!

cnvs = document.windows[0].selection.canvas
layer = cnvs.newLayer()
layer.name = "NEW LAYER"

By default, new layers are created at the top of the stack of existing layers.

Here’s a script that demonstrates the creation of a canvas, layers, and shapes:

Create Canvas with Layers and Shapes
Copy Try It!

cnvs = addCanvas()
cnvs.canvasSizingMode = CanvasSizingMode.Fixed
cnvs.size = new Size(288, 288)

layr = cnvs.layers[0]
graphk = layr.addShape('Rectangle', new Rect(0, 0, 144, 144))
graphk.fillColor = Color.RGB(0.5, 0.5, 1, 1)
graphk.shadowColor = null
graphk.name = 'blue'

layr = cnvs.newLayer()
graphk = layr.addShape('Rectangle', new Rect(144, 0, 144, 144))
graphk.fillColor = Color.RGB(1, 0.5, 0.5, 1)
graphk.shadowColor = null
graphk.name = 'red'

layr = cnvs.newLayer()
graphk = layr.addShape('Rectangle', new Rect(144, 144, 144, 144))
graphk.fillColor = Color.RGB(1, 0.5, 1, 1)
graphk.shadowColor = null
graphk.name = 'magenta'

layr = cnvs.newLayer()
graphk = layr.addShape('Rectangle', new Rect(0, 144, 144, 144))
graphk.fillColor = Color.RGB(0.5, 1, 0.5, 1)
graphk.shadowColor = null
graphk.name = 'green'

Note the use of the variable names: cnvs, layr, graphk, and graphx that represent a Canvas object, a Layer object, a Graphic object, and multiple Graphic objects.. This variable naming convention is used throughout this website.

Names of Canvas Layers
Copy

cnvs = document.windows[0].selection.canvas
layerNames = cnvs.layers.map(layr => layr.name)

And here’s a script that will hide all layers of the current canvas that do not contain at least one selected graphic:

Show Only Layers with Selected Graphics
Copy Try It! Download Plug-In Install Plug-In

sel = document.windows[0].selection
graphx = sel.graphics
if (graphx.length > 0){
	cnvs = sel.canvas
	// hide all layers
	cnvs.layers.forEach(layr => {layr.visible = false})
	// show layers that contain a selected graphic
	graphx.forEach(graphk => {graphk.layer.visible = true})
}

And here’s a script for making sure that all layers of the current canvas are visible:

Show All Layers
Copy Try It! Download Plug-In Install Plug-In

cnvs = document.windows[0].selection.canvas
cnvs.layers.forEach(layr => {layr.visible = true})

Instance Functions

The instance functions for a layer object include the ability to reorder or delete layers:

• orderAbove(Layer) → Reorder this layer so that it is just above the given layer.

• orderBelow(Layer) → Reorder this layer so that it is just below the given layer.

• remove() → Remove this layer from its canvas, deleting it.

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

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

Performing Tasks with Layers

Here are script outlines for performing operations with each of the layers of the current canvas:

Using for…of Loop
Copy Try It!

cnvs = document.windows[0].selection.canvas
for (layr of cnvs.layers){
	//processing code
	console.log(layr.name)
}

Using forEach() Function
Copy Try It!

cnvs = document.windows[0].selection.canvas
cnvs.layers.forEach(layr => {
	//processing code
	console.log(layr.name)
})

Using the script outline above to create a script that shows hidden layers of the current canvas:

Show Hidden Layers
Copy Try It!

cnvs = document.windows[0].selection.canvas
for (layr of cnvs.layers){
	if (layr.visible === false){layr.visible = true}
}

Here’s a script that deletes the hidden layers of the current canvas. NOTE: The remove() function deletes layers regardless of the status of their locked property.

Delete Hidden Layers
Copy Try It!

cnvs = document.windows[0].selection.canvas
for (layr of cnvs.layers){
	if (layr.visible === false){layr.remove()}
}

Getting the object reference to a layer by using the layer’s name:

Get Layer Reference by Name
Copy

function getLayerObjectOfCurrentCanvasByName(layerName){
	var targetLayer
	cnvs = document.windows[0].selection.canvas
	for (layr of cnvs.layers){
		if (layr.name.localeCompare(layerName) === 0){
			targetLayer = layr
			break
		}
	}
	if (targetLayer){
		return targetLayer
	} else {
		errStr = `There is no layer named “${layerName}” in the current canvas.`
		new Alert('MISSING OBJECT', errStr).show()
		return null
	}
}
getLayerObjectOfCurrentCanvasByName(layerName)

This script reorders the layers by name:

Reorder Layers by Name
Copy Try It!

cnvs = document.windows[0].selection.canvas
layrz = cnvs.layers
layrz.sort((a, b) => {
  var x = a.name;
  var y = b.name;
  if (x < y) {return -1;}
  if (x > y) {return 1;}
  return 0;
})
layrz.reverse().forEach(layr => {
	topLayr = cnvs.layers[0]
	if(layr !== topLayr){
		layr.orderAbove(topLayr) 
	}
})

NOTE: the document window view may need to be refreshed in order to display the reordered canvases correctly.

Moving Objects to Other Layers

Currently, the scripting implementation in OmniGraffle does not offer commands for merging layers or for moving objects between layers. However, because references ot objects are based on the unique value of their id property, you can use the orderAbove() and orderBelow() methods from the Graphic class to move objects between the layers of a canvas.

For example, in the OmniGraffle document pictured below, there are three objects, each on its own layer. You can use the orderAbove() method to move them to the top layer while maintaining their stacking relationship.

Moving Objects Between Layers: orderAbove()
Copy

cnvs = document.windows[0].selection.canvas
g0 = cnvs.layers[0].graphics[0] // diamond
g1 = cnvs.layers[1].graphics[0] // circle
g2 = cnvs.layers[2].graphics[0] // square
g2.orderAbove(g0) // move square above diamond
g1.orderAbove(g2) // move circle above square
g0.orderAbove(g1) // move diamond above circle

Alternatively, you can use the orderBelow() method to move the three objects to the bottom layer while maintaining their stacking relationship.

Moving Objects Between Layers: orderBelow()
Copy

cnvs = document.windows[0].selection.canvas
g0 = cnvs.layers[0].graphics[0] // diamond
g1 = cnvs.layers[1].graphics[0] // circle
g2 = cnvs.layers[2].graphics[0] // square
g1.orderBelow(g2) // move circle below square
g0.orderBelow(g2) // move diamond below sqaure
g2.orderBelow(g1) // move square below circle