OmniGraffle: Document
A Document is the top-level object in Omni Automation. For security reasons, scripts can only address the frontmost document, they cannot query for or address other documents that may be open. Unlike other classes of objects, such as graphics, that can be addressed by index, the “current document” is simply referenced as document instead of app.documents[0] in your scripts.
The following documentation describes how open, create, save, and close documents, as well as how to access a document’s properties.
Open Document
To open an OmniGraffle file, a file URL is passed to the openDocument application method. This handler attempts to open the specified document and to return a reference to it asynchronously. If the document is already open, the reference to the open document is passed along.
Note that due to platform sandboxing restrictions, opening the document may fail if the application doesn’t have currently permission to access the given file URL. The document, if any, that is associated with the calling script can be passed along to help grant permission to open the new document.
The passed in function will return two arguments: the first (result) will be either either the Document reference or an Error. On success, the second argument (wasOpen) is a Boolean value specifying whether the document was already open.
Open Document | ||
01 | app.openDocument(document,fileURL,function(result,wasOpen){}) |
A an example, here is a script that uses the choose() method of the URL class to prompt the user to locate and select an OmniGraffle document (in either file or package format) and then open the chosen document:
Choose and Open Document | ||
01 | fileURL = URL.choose(["com.omnigroup.omnigraffle.graffle", "com.omnigroup.omnigraffle.graffle-package"]) | |
02 | if (fileURL == null){ | |
03 | throw new Error('user cancelled') | |
04 | } else { | |
05 | app.openDocument(document,fileURL,function(result,wasOpen){ | |
06 | if(result instanceof Document){ | |
07 | // processing code goes here | |
08 | cnvs = result.windows[0].selection.canvas | |
09 | console.log(cnvs.graphics.length) | |
10 | } else { | |
11 | throw new Error(result) | |
12 | } | |
13 | }) | |
14 | } |
New Document
The makeNewAndShow() method is called on the Document class to create and setup an OmniGraffle document. This method includes as its parameter, a function that is called once the new document is created. A reference to the new document is passed into the function, and can be used to set the properties of the default canvas as well as be used to create new elements. Note the use of the canvasSizingMode property to indicate the method used to size the default canvas.
Create a New Document | ||
01 | Document.makeNewAndShow(function(doc){ | |
02 | cnvs = doc.windows[0].selection.canvas | |
03 | cnvs.canvasSizingMode = CanvasSizingMode.Fixed | |
04 | cnvs.size = new Size(612,792) | |
05 | cnvs.name = "Letter to Sally" | |
06 | }) |
Document Properties
The document class has a small set of properties:
canRedo (boolean r/o) • Whether there are currently any actions that can be redone.
canUndo (boolean r/o) • Whether there are currently any actions that can be undone.
name (String r/o) • Name of the document.
writableTypes (Array of Strings r/o) • A list of the identifiers for all of the possible document types for writing the document to file.
fileType (String r/o) • The file type identifier the document uses when saving, if set.
Name
The read-only name property has a value that is the name of the OmniGraffle document as it appears in the title bar of the document window. On macOS, this value will reflect the value of the Finder’s file extension visibility setting, set in the file’s Information window.
01 | document.name | |
02 | --> Construction Design |
Writable Types
The value of the writableTypes property of the document class is an array (list) of all of the file types that this document can be written as.
Document Undo
If the value of the document’s canUndo property is true, then the undo() method can be used to undo the previous user or script action.
Document Undo | ||
01 | if(document.canUndo){document.undo()} |
Document Redo
If the value of the document’s canRedo property is true, then the redo() method can be used to re-apply the previous user or script action.
Document Redo | ||
01 | if(document.canRedo){document.redo()} |
Document Close
Close this document. This is not currently allowed if the current scripting environment is owned by the Document (you can close other documents, but not your own).
Document Close | ||
01 | document.close() | |
02 | // Error: Cannot determine environment owner for Document |
New Document Closing Current Document | ||
01 | var oldDoc = document | |
02 | Document.makeNewAndShow(function(newDoc){ | |
03 | oldDoc.close() | |
04 | }) |
Document Save
The save() method performs the standard save action with the document.
Document Save | ||
01 | document.save() |
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.