Document

A document object. Each document maintains a list of layers, selection state, and set of alignment guides. Several functions are available for exporting various types of data.
 
The document object is also the constructor for new Color, Gradient, Image, and Path attribute objects.
 
Layers

• layers
• activeLayer
• addLayer

Selections

• selection
• selectedShapes
• selectedLayers

Creating Attributes

• addColor
• addColorWithRed: green: blue: alpha:
• addGradient
• addImage:
• addPath

Canvas

• canvasSize

Alignment Guides

• alignmentGuides
• addAlignmentGuide

Exporting

• exportImage:
• exportPDF:
• exportSVG:
• exportImage: forShapes:
• exportPDF: forShapes:
• exportSVG: forShapes:

activeLayer

returns Layer

Gets the currently active layer. The active layer is the selected layer with the highest index. This is also the layer used by the drawing tools when drawing new shapes.
 

Example: move the active layer to the bottom of the layers list

var layer = [[app activeDocument] activeLayer]
[layer moveToIndex:0]

addAlignmentGuide

returns AlignmentGuide

Gets the array of the document's alignment guides.
 

Example: create a new vertical alignment guide

var guide = [[app activeDocument] addAlignmentGuide]
guide.orientation = "vertical"
guide.location = 40

addColor

returns Color

Creates and returns a new color object.
 

Example: set the stroke color and width of the selected shapes

var doc = [app activeDocument]
var shapes = [doc selectedShapes]
var color = [doc addColor]

color.red = 255
color.green = 64
color.blue = 64
color.alpha = 0.75

for(var i = 0; i < [shapes count]; i++)
{
    var stroke = [(shapes[i]) stroke]   
    stroke.color = color
    stroke.width = 8
}

addColorWithRed: green: blue: alpha:

returns Color; input Integer; input Integer; input Integer; input Float

Creates and returns a new color object with the given RGB and alpha values. Each RGB component is an integer value between 0-255 and alpha is a float value between 0-1.
 

Example: set the stroke color and width of the selected shapes

var doc = [app activeDocument]
var shapes = [doc selectedShapes]
var color = [doc addColorWithRed:255 green:64 blue:64 alpha:0.75]

for(var i = 0; i < [shapes count]; i++)
{
    var stroke = [(shapes[i]) stroke]   
    stroke.color = color
    stroke.width = 8
}

addGradient

returns Gradient

Creates and returns a new gradient object. The gradient is initialized with two color stops, white at location 0 and black at location 1.
 

Example: create a new gradient and set it as the fill of the frontmost selected object

var doc = [app activeDocument]
var shape = [[doc selectedShapes] lastObject]

if(shape)
{    
    var gradient = [doc addGradient]
    var colorStops = [gradient stops]

    var clr1 = [doc addColorWithRed:0 green:128 blue:255 alpha:0.25]
    var clr2 = [doc addColorWithRed:0 green:128 blue:255 alpha:1]
    colorStops[0].color = clr1
    colorStops[1].color = clr2

    [shape fill].gradient = gradient
}

addImage:

returns Image; input CGImage

Creates and returns a new image object based on the passed-in CGImage. Imports the image data from the CGImage and saves it in the document.

Note: this function should not be used for real-time image previews or called continuously with updated image data. The image data is directly added to the document and saved to disk.
 

Example: display the Open Panel to import an image file, and set the imported image as the frontmost shape's fill

var doc = [app activeDocument]
var shape = [[doc selectedShapes] lastObject]
var openPanel = [NSOpenPanel openPanel]
openPanel.allowedFileTypes = ["png", "jpg"]

if(shape && [openPanel runModal])
{
    var fileURL = [openPanel URL]
    var imgSrc = CGImageSourceCreateWithURL(fileURL, nil)

    if(imgSrc)
    {
        var cgImg = CGImageSourceCreateImageAtIndex(imgSrc, 0, nil);

        if(cgImg)
            [shape fill].image = [doc addImage:cgImg]

        CGImageRelease(cgImg)
        CFRelease(imgSrc);
    }
}

addLayer

returns Layer

Creates and returns a new layer object. The new layer becomes the active selected layer.
 

Example: create a new layer and move the selected objects to the layer

var doc = [app activeDocument]
var shapes =  [doc selectedShapes]
var newLayer = [doc addLayer]

for(var i = 0; i < [shapes count]; i++)
{
    var shape = shapes[i]
    [shape moveToParent:newLayer]
}

addPath

returns Path

Creates and returns a new path object.
 

Example: create a triangle path and use it create a new path shape

var doc = [app activeDocument]
var path = [doc addPath]

[path addMoveTo:CGPointMake(25, 150)]
[path addLineTo:CGPointMake(75, 50)]
[path addLineTo:CGPointMake(125, 150)]
[path addClose]

[[doc activeLayer] addPathShape:path]

alignmentGuides

returns Array

Gets the array of the document's alignment guides.
 

Example: offset each alignment guide's location by 10 pixels

var guides = [[app activeDocument] alignmentGuides]

for(var i = 0; i < [guides count]; i++)
{
    var guide = guides[i]
    guide.location = [guide location] + 10
}

[[app view] redraw]

exportImage:

returns CGImage; input NSDictionary

Creates and returns an exported CGImage representation of the entire design.

The input dictionary is optional and can be nil; Optional input keys and values:

"scale": Float; the export scale factor
"includeBackground": Boolean; option to include the canvas background and grid

exportPDF:

returns NSData; input NSDictionary

Creates and returns an NSData object containing a PDF data representation of the entire design.

The input dictionary is optional and can be nil; Optional input keys and values:

"scale": Float; the export scale factor
"rasterScale": Float; the scale factor of embedded images
"includeBackground": Boolean; option to include the canvas background and grid

exportSVG:

returns String; input NSDictionary

Creates and returns a String object containing an SVG representation of the entire design.

The input dictionary is optional and can be nil; Optional input keys and values:

"scale": Float; the export scale factor
"rasterScale": Float; the scale factor of embedded images
"convertToSRGB": Boolean; option to convert colors to sRGB
"includeBackground": Boolean; option to include the canvas background and grid

exportImage: forShapes:

returns CGImage; input NSDictionary; input Array

Creates and returns an exported CGImage representation of the passed-in shapes array.

The input dictionary is optional and can be nil; Optional input key and value:

"scale": Float; the export scale factor
 

Example: create a new document containing an exported image of the current selection

var shapes = [[app activeDocument] selectedShapes]
var img = [[app activeDocument] exportImage:nil forShapes:shapes]

if(img)
{
    var doc = [app addDocument]
    var newImage = [doc addImage:img]
    var size = CGSizeMake(CGImageGetWidth(img), CGImageGetHeight(img))

    // create a new path with the image bounds
    var path = [doc addPath]
    [path addMoveTo:CGPointMake(0, 0)]
    [path addLineTo:CGPointMake(size.width, 0)]
    [path addLineTo:CGPointMake(size.width, size.height)]
    [path addLineTo:CGPointMake(0, size.height)]
    [path addClose]

    // create a new path shape and set the image fill 
    var shape = [[doc activeLayer] addPathShape:path]
    [shape fill].image = newImage
    [shape stroke].width = 0

    doc.canvasSize = size
    [[app view] resetZoom]
}

exportPDF: forShapes:

returns NSData; input NSDictionary; input Array

Creates and returns an NSData object containing a PDF data representation of the passed-in shapes array.

The input dictionary is optional and can be nil; Optional input keys and values:

"scale": Float; the export scale factor
"rasterScale": Float; the scale factor of embedded images
 

Example: copies the selected shapes as PDF data to the clipboard, embedding image fills at 300 DPI

var doc = [app activeDocument]
var shapes = [doc selectedShapes]

if([shapes count] > 0)
{
    var options = [NSDictionary dictionaryWithObject:(300.0/72) forKey:"rasterScale"]
    var pdfData = [doc exportPDF:options forShapes:shapes]
    var pboard = [NSPasteboard generalPasteboard]
    [pboard declareTypes:[NSArray arrayWithObject:NSPasteboardTypePDF] owner:nil];
    [pboard setData:pdfData forType:NSPasteboardTypePDF]
}

exportSVG: forShapes:

returns String; input NSDictionary; input Array

Creates and returns a String object containing an SVG representation of the passed-in shapes array.

The input dictionary is optional and can be nil; Optional input keys and values:

"scale": Float; the export scale factor
"rasterScale": Float; the scale factor of embedded images
"convertToSRGB": Boolean; option to convert colors to sRGB
 

Example: copies the selected shapes as an SVG string to the clipboard at 2x scale

var doc = [app activeDocument]
var shapes = [doc selectedShapes]

if([shapes count] > 0)
{
    var options = [NSDictionary dictionaryWithObject:2 forKey:"scale"]
    var svgStr = [doc exportSVG:options forShapes:shapes]
    var pboard = [NSPasteboard generalPasteboard]
    [pboard clearContents]
    [pboard writeObjects:[NSArray arrayWithObject:svgStr]]
}

canvasSize

returns CGSize; settable

Gets / Sets the size of the document's canvas.
 

Example: create a new document with the same canvas size as the current document

var doc = [app activeDocument]
var size = [doc canvasSize]
var newDoc = [app addDocument]

newDoc.canvasSize = size
[[app view] resetZoom]

layers

returns Array

Gets the array of the document's layers.
 

Example: renames all of the current document's layers

var doc = [app activeDocument]
var layers =  [doc layers]

for(var i = 0; i < [layers count]; i++)
    layers[i].name = "Layer " + (i + 1)

selectedLayers

returns Array

Gets the array of selected layers.
 

Example: duplicate the currently selected layers

var doc = [app activeDocument]
var layers =  [doc selectedLayers]
var newLayers = [NSMutableArray array]

for(var i = 0; i < [layers count]; i++)
{
    var layer = layers[i]
    [newLayers addObject:[layer duplicate]]
}

// select the newly created layers
for(var i = 0; i < [newLayers count]; i++)
    newLayers[i].selected = true

selectedShapes

returns Array

Gets the array of selected shapes. This will include the selected shapes across all selected layers.
 

Example: create a new layer and move the selected objects to the layer

var doc = [app activeDocument]
var shapes =  [doc selectedShapes]
var newLayer = [doc addLayer]

for(var i = 0; i < [shapes count]; i++)
{
    var shape = shapes[i]
    [shape moveToParent:newLayer]
}

selection

returns Selection

Gets the document's selection object. This object can be used to apply transforms on the current shape selection.
 

Example: rotate the current selection by 45 degrees.

var doc = [app activeDocument]
var selection = [doc selection]
[selection rotate:45]

AlignmentGuide

An alignment guide object. New alignment guides can be created using the Document's addAlignmentGuide function. Alignment guides can be removed using each object's remove function.

Settings

• location
• orientation

Remove

• remove

location

returns Float; settable

Gets / Sets the location of the alignment guide.
 

Example: create six horizontal alignment guides spaced every 100 pixels

for(var i = 1; i <= 6; i++)
{ 
    var guide = [[app activeDocument] addAlignmentGuide]
    guide.orientation = "horizontal"
    guide.location = i * 100
}

orientation

returns String; settable

Gets / Sets the orientation of the alignment guide. Possible values are "horizontal" or "vertical".
 

Example: create an alignment guide on each side of the selection's bounding box

var doc = [app activeDocument]
var selection = [doc selection]

if([[selection shapes] count] > 0)
{
    var bounds = [selection bounds]
    var guide = [doc addAlignmentGuide]
    guide.orientation = "vertical"
    guide.location = bounds.origin.x

    guide = [doc addAlignmentGuide]
    guide.orientation = "vertical"
    guide.location = bounds.origin.x + bounds.size.width

    guide = [doc addAlignmentGuide]
    guide.orientation = "horizontal"
    guide.location = bounds.origin.y

    guide = [doc addAlignmentGuide]
    guide.orientation = "horizontal"
    guide.location = bounds.origin.y + bounds.size.height
}

remove

Removes the alignment guide from the document.
 

Example: remove all of the alignment guides in the current document

var guides = [[app activeDocument] alignmentGuides]

for(var i = 0; i < [guides count]; i++)
    [(guides[i]) remove]

Next: Selection