AppleScript

From SkimWiki

Skim has extensive support for scripting, such as AppleScript.

Contents 1 Adding Scripts for Skim 2 AppleScript Support in Skim 2.1 Saving 2.2 Colors 2.3 Selections 2.4 Creating New Notes and Highlights 2.5 PDF View Settings 2.6 Document Attributes 3 Example Scripts 4 User-Contributed Scripts

Adding Scripts for Skim

To add an Applescript to the menu, put it in Library/Scripts/Applications/Skim/, either in your home folder or on your computer (if you want the script to be available for all users). You may have to create those directories if they do not exist. The scripts appear in the Scripts on the right side of the menu bar whenever Skim is the active application. You may have to enable the Scripts menu using AppleScript Utility, which you can find in /Applications/AppleScript/. See Example Scripts for some scripts you could add there.

AppleScript Support in Skim

To see what is supported for scripting, open the Skim scripting dictionary in Script Editor (File > Open Dictionary..., or Window > Library).

Due to bugs in Script Editor (at least on Tiger), some information is not (fully) displayed in the scripting dictionary. There are several dictionary types (such as "PDF view settings" and "document attributes") that are not included in the outline at the top view. But they are displayed in the lower pane when you select the Skim Suite. Several enumerated properties, such as color names (see below), are not displayed at all.

Skim's scripting supports access to the following classes:

application, window, document, page, note

A large number of properties for these classes are supported. The following actions are supported:

open, close, save, quit, count, delete, duplicate, exist, make, move
revert, go, find, join, get bounds for, get text for, get index for, get pages for

Saving

You can save and export a PDF document directly from AppleScript. When you supply a file name argument (in) to the save command, this works like Save As (and changes the file name of the document). You can then also supply a file type argument (as), in which case it works like Export (i.e. it does not change the file name of the document). The file type must be one of the following strings.

"PDF", "PDF Bundle", "PDF Without Notes", "PDF With Embedded Notes", 
"Skim Notes", "Notes as Text", "Notes as RTF", "Notes as RTFD", "Notes as FDF"

Colors

Skim scripting allows full control over the colors of notes and highlights. Colors are represented according to the RGBA (Red-Green-Blue-Alpha) model as a list of four integers, each one ranging from 0 to 65535 (= 2¹⁶ - 1). For example, {65535, 0, 0, 65535} represents the color red. You can also enter a color with less integers, in which case the integers are interpreted according to the RGB (Red-Green-Blue), GA (Grayscale-Alpha) or G (Grayscale) model. There are also many standard colors that can be entered by their name. Currently, the following colors are supported.

red, green, blue, yellow, magenta, cyan, dark red, dark green, dark blue, 
banana, turquoise, violet, orange, deep pink, spring green, aqua, lime, dark violet, 
purple, teal, olive, brown, black, white, gray, light gray, dark gray, clear

Selections

Skim also has scripting support for selections. This can either be the selection shown by the document, but also selections handled by the script, for example as a result of a find command to search for text, or to create a new highlight. Selections are modeled as a list of ranges of characters for the text on a page. For example,

{characters 1 thru 100 of text of page 1 of document 1 of application "Skim"}

If you enter this in a tell block for the document, you can leave out the refercene to the document and the application. Also, you can leave out the reference to the text. Selections are supposed to be references, rather than a list of characters. Therefore you may have to explicitly tell the script to keep a reference, to avoid the script from evaluating the expression. This is in particular important when you want to assign a selection to a variable.

tell document 1 of application "Skim"
    set aSelection to {a reference to characters 1 thru 100 of page 1}
end tell

To ease life a bit, AppleScript allows you to type 'ref' as a shorthand for 'a reference to'. Instead of character ranges, you can also enter selections using other types of text references. The standard Text Suite in the scripting dictionary for Skim describes ways to refer to components of a text. You can freely mix different reference forms inside a list describing a selection, as in the example below (As above, you should enter the following examples inside a tell block and you may have to add references).

{character 1 of page 1, words 6 thru -1 of page 2, paragraph 1 thru 2 of page 4, every attribute run of page 5}

You may also enter a single range by itself, without wrapping it in a list. You can manipulate selections using the join command, which joins two selections to a single one. If the optional continuous selection argument is true, the resulting selection will be a continuous range. The following returns a selection for the first three pages:

join first character of page 1 to last character of page 3 with continuous selection

You can also use the join command with a single selection argument (so without the to), to make a selection continuous or to normalize it.

As selections are not really objects, they cannot have properties. Still, there is some useful information to obtain from them. For that purpose, three commands have been added to simulate 'properties' of the selection.

get bounds for, get text for, get index for, get pages for

There are synonyms defined like 'bounds for', to simulate the analogous behavior of the get command. However currently, in Tiger, the Apple frameworks ignore synonyms. These commands also accept a document, page, or note as its argument, where they basically get the corresponding property.

Creating New Notes and Highlights

You can use AppleScript to add new notes to a document. You use the make command to accomplish this. It is important to note that notes, other than markups (highlight, underline, and strike out) need to be added to a page. you can do this either by adding the note inside a tell block for the page, or by supplying the end of notes of the page in the at argument. Also to create a note, you have to supply the type of the note. You can supply the type in the standard with properties arguments of the make command. Here are two examples.

tell page 1
    make note with properties {type:text note}
end tell

make note with properties {type:anchored note} at end of notes of page 2

New markups (highlight, underline, and strike out notes) require in addition to the type also a selection to be initialized. As notes are added to a single page, the markup is only added for the selection on the first page (just as for adding a markup from the Notes menu). As the selection already knows about the page, you do not need to explicitly mention the page (though you may). A highlight can be added as below, assuming the aSelection contains a selection.

make note with properties {type:highlight note, selection:aSelection}

PDF View Settings

You can access the view settings for the PDF document from AppleScript through the 'view settings' property of a document. View settings are packaged in a record, and can have the following properties.

scale factor, auto scales, display mode, displays page breaks, displays as book, display box

The 'display mode' property can have one of the following values.

single page, single page continuous, two up, two up continuous

The 'display box' property can have one of the following values.

media box, crop box

When you set the view settings, only the settings you provide in the record are changed. For example the script below only changes the display mode, showing one page at a time.

set view settings of document 1 of application "Skim" to {display mode:single page}

Document Attributes

You can also access the document attributes of a PDF document (as displayed when you use Get Info) through the info property of a document. Document attributes are packaged in a record, and can have the following properties.

file name, title, author, subject, creator, publisher, 
version, creation date, modification date, page count, 
file size, physical size, logical size, page size, 
encrypted, allows printing, allows copying, 
keywords, keywords string

Example Scripts

Here are a few example scripts to get you started (right-click on linked name to save, or option-click for download in most browsers).

• New Notes for Selection Adds multiple highlights for selections spanning multiple pages.
• Highlight Occurences of Text Highlights every occurrence of a given text.
• Join Highlights Joins all highlights of the same type that are on the same page into a single highlight note.
• Update Default Colors of Notes Sets the colors of all notes of selected types to the current default values. Useful after changing the default colors for some note types.
• Set Color of Notes Sets the colors of all notes of selected types to a chosen color.
• Set Interior Color of Notes Sets the fill colors of all circle and/or box notes to a chosen color.
• Toggle Actual Size - Auto Scales Allows you to quickly switch between displaying the PDF on its actual size and automatically zooming to the window.
• Display As Book Quickly switch to a side-by-side view in book mode.
• Display Single Page Continuous Quickly switch to a continuous single page display.
• Set Default Note Icon Choose the default icon for anchored notes.
• Set Default Text Note Font Color Choose the default font color for text notes.
• Crop Even Pages Crop the even pages to the current selection from the selection tool.
• Crop Odd Pages Crop the odd pages to the current selection from the selection tool.
• Show man Show the man page for a shell command in Skim.
• Mail Archive Email an archive of the front document as an attachment using Mail.

User-Contributed Scripts

• DocInfo (from Skim) View many details about current PDF, including word count, line count, character count, and much more. Also gives that information for highlighted text. Shockley 21:28, 30 March 2008 (PDT)

• Your scripts here?