Scripting JPEGView

Although JPEGView by itself is a useful tool for image viewing and rudimentary conversions, it becomes even more powerful when used in conjunction with AppleScript.  This is because JPEGView is ÒscriptableÓ, meaning that you can write scripts in AppleScript that can perform any operation you can do with the keyboard or mouse in JPEGView.  JPEGView is also ÒrecordableÓ, meaning that you can use the Script Editor application to record your actions while running JPEGView, and then play them back later.

JPEGView includes with its original distribution package four potentially useful ÒdropletsÓ, or drag-and-drop script applications, which also serve as basic examples of how to write JPEGView scripts.  The function of each script is described briefly below.

JPEGView Convert to PICT:  dropping a bunch of files on this icon will fire up JPEGView and convert each JPEG-compressed image in the bunch to JPEG-compressed PICT format with previews, custom icons, and reduced color sets.

JPEGView Preview & Icons:  by dropping files onto this application, you can get JPEGView to create previews and icons for all valid images.

JPEGView Image Summary:  using drag and drop with this application, JPEGView will open each image and add a summary line to a new untitled window in the Scriptable Text Editor.

JPEGView Slide Show:  dragging and dropping onto this icon will start up a JPEGView slide show of the dropped folders and files.

Of course, you can easily modify these scripts using the Script Editor to make them do more precisely what you want.  This is probably the best way to get your feet wet in working with the AppleScript-JPEGView combination.

This chapter explains how AppleScript and JPEGView work together to give you scripting capabilities.  It does not tell you how to use AppleScript; rather, it assumes some basic understanding of how AppleScript works and of how scripts are written.  If you donÕt have AppleScript, you can find out how to get it in the JPEGView Questions and Answers chapter.


The JPEGView Object Hierarchy

In order to write scripts for JPEGView, it is important to understand how JPEGView organizes the objects it manipulates.  Here is a crude graphical representation of the JPEGView object hierarchy:

         +------- application
         |            |
         |            |
         v            v
      window ----> document ------+
         |            |           |
         |            |           |
         v            v           v
  drawing area ---> image <---- file
                      |
                      |
                      v
                  pixel map

At the top of the hierarchy is the application, which serves as the ÒcontainerÓ for all the other objects in JPEGView.  Inside the application there can be any number of windows and documents.  Be careful not to confuse image objects with document objects, however!  A document is some abstract object that is being viewed or edited in the application; an image is what the document contains, i.e., the graphic image inside the document.

Window objects in general fall into two categories: those that are displaying a document, and those that are not. Windows that are displaying documents contain exactly one document object (since only one document can appear at a time in a given window) and one drawing area object.  Windows that are not displaying a document have no documents and no drawing areas associated with them.

Aside from the application object, which can contain many documents and windows, most of JPEGViewÕs objects only contain a single element.  That is, windows can only contain one drawing area (if any at all); drawing areas, documents, and files can contain only one image; documents can contain only one file; and images can only contain zero or one pixel map.  Although it may have seemed more logical to combine everything into a single object, the current setup fits more smoothly into AppleÕs definitions for the standard AppleEvent suites.

The best way to see what commands and objects JPEGView supports is to open its dictionary using the Script Editor.  This will produce a list of four suites, or groups, of objects and commands: the Required Suite, the Standard Suite, the QuickDraw Graphics Suite, and the JPEGView Suite.  The Required and Standard suites are common to all AppleScript-aware applications, and wonÕt be described here apart from the extensions and limitations imposed by JPEGView.

The QuickDraw Graphics Suite provides definitions for pixel maps and drawing areas, two objects used in JPEGView.  However, JPEGView only implements a subset of the full definition of these classes, so be careful if youÕve seen them in other applications.  Finally, the JPEGView Suite contains two events for reducing images to a particular number of colors and for running the slide show; only the latter event is interesting for scripting purposes.

Once youÕve glanced over the classes, try recording some random actions in JPEGView.  This will help you get a feel for how JPEGView handles and manipulates objects.  Almost everything you do in JPEGView will appear as a script command in the Script EditorÕs window.

Finally, note that JPEGView only supports the Òsimple grammarÓ at this time; that is, you can only refer to objects by number or by name.  ÒWhoseÓ clauses and conditionals are not supported, although the generic selectors such as every, any, first, last, etc., are supported.


Commands in the Required Suite

JPEGView supports all four events defined in AppleÕs Required Suite; these are the open, print, quit, and run commands.

open: Open the specified object(s).  This command is used in JPEGView to open image files.  The object it expects is a list of aliases to the files you want to open.  If you leave the remaining parameters alone, the image will be opened according to the current preferences settings; however, you can control almost every aspect of the opening procedure through the use of the parameters specified below.  Any omitted parameters will take on the values from the preferences settings.

    on deepest color/deepest grayscale/largest color/largest grayscale/main Ñ allows you to specify which monitor to open the image on 
    using full screen always/always if large/on request if large/never Ñ allows you to specify how JPEGView handles the use of full screen windows
    expansion true/false Ñ controls whether small images are expanded to maximum size
    visible true/false Ñ controls whether the image window is initially visible
    with colors image or reduced or system/reduced or image or system/image or system/reduced or system/system Ñ controls the initial colors used for image drawing, in order of preference; that is, Òimage or reduced or systemÓ means that image colors are preferred, followed by reduced colors, and then standard system colors
    with quality very high/high/normal Ñ specifies the quality to be used in drawing the opened images
    bitmaps true/false Ñ controls whether bitmaps are required for the images
    comments true/false Ñ specifies whether the Comments floating window is automatically displayed for images that have comments
    type fixing true/false Ñ controls whether file types are automatically fixed
    changing creators true/false Ñ controls whether creators are changed along with file types
    no errors true/false Ñ tells JPEGView whether or not it should display error messages; defaults to false

Note that since JPEGView only accepts lists of aliases as parameters to the open command, you must manually coerce files or filenames to aliases before passing them to the open command.  So, be careful to use Òopen {file as alias}Ó and not just Òopen {file}Ó.

print: Print the specified object(s) or file(s).  Specifying either files or document objects instructs JPEGView to start printing the appropriate images.

quit: Quit application.  Quits JPEGView.

run: Sent to an application when it is double-clicked.  This function performs the startup action specified in the preferences; normally only used by the Finder when it launches JPEGView.


Commands in the Standard Suite

The Standard Suite provides the basic commands for manipulating objects in JPEGView, and JPEGView supports all of AppleÕs recommended functions in this suite.

close: Close an object.  In JPEGView, only windows and documents can be closed.  Closing a document also closes its corresponding window.  The only additional non-standard parameter is:

    restore colors true/false Ñ controls whether colors are automatically restored after the last image is closed

count: Return the number of elements of a particular class within an object.  This function is applicable in the standard way to every object in the JPEGView object hierarchy.

data size:  Return the size in bytes of an object.  This function is supported in the standard way for every object and for every property of every object in the JPEGView object hierarchy.

delete:  Delete an element from an object.  This command only works for windows, documents, and pixel maps.  For windows and documents, it provides the same functionality as the close command; for pixel maps, it disposes of any offscreen bitmap associated with an image.

duplicate:  Duplicate object(s).  In JPEGView, only documents and windows can be duplicated, and in the case of windows, only windows that contain documents can do it.  In addition, the duplicate command supports a visible parameter, whose function is identical to the visible parameter in the open command from the Required Suite.

exists:  Verify if an object exists.  This is supported in the standard way for all objects in the JPEGView object hierarchy.

get:  Get the data for an object.  This function is supported in the standard way for all objects and for all properties of objects in the JPEGView object hierarchy.

make:  Make a new element.  Only windows can be made in JPEGView, and then only static windows, which include the three floating windows, the About box, the Help window, and the Preferences and Slide Show Options dialog.  To create a given new window, simply specify its contents property in the with properties parameter.

move:  Move object(s) to a new location.  Both documents and windows can be moved in JPEGView.  This allows you to move windows (document windows in the case of documents) in front of or behind other windows in the application.

save:  Save an object.  In JPEGView, only documents and windows containing documents can be saved.  In addition to the standard parameters, JPEGView adds the following three optional parameters:

    preview true/false Ñ specifies whether to create a preview of the document
    reduced colors true/false Ñ specifies whether to save a reduced color set with the document
    icons true/false Ñ specifies whether to create custom icons for the document

set:  Set an objectÕs data.  This command works in JPEGView only for data contained in the properties of an object.  The data of an actual object cannot be directly set.


Objects classes in the Standard Suite

application:  the JPEGView application.  This object sits at the top of the object hierarchy and always exists.  It can contain any number of windows and any number of documents.  The application properties supported by JPEGView are as follows:

    clipboard (list of anything) Ñ non-modifiable Ñ since JPEGView does not support copying and pasting, this property always returns an empty list
    frontmost (boolean) Ñ non-modifiable Ñ this property is true if JPEGView is the frontmost application
    name (string) Ñ non-modifiable Ñ the name of the application, i.e., ÒJPEGViewÓ
    version (integer) Ñ non-modifiable Ñ the version number, specified as (major version x 256) + (minor version); for example, version 3.0 is (3 x 256 + 0) = 768

document:  a document.  This object serves as the container for all images that are manipulated in JPEGView.  Documents always contain exactly one file and one image.  The supported document properties are:

    modified (boolean) Ñ non-modifiable Ñ this property is true if the image has been modified; in JPEGView, this property always returns false
    name (boolean) Ñ modifiable Ñ this is the name of the document
    selection (boolean) Ñ non-modifiable Ñ this property points to a selection object whose bounds property describes the current selection in this document

file:  a file.  This object specifies information about the file used to store a document.  File objects always contain exactly one image in JPEGView.  Supported file properties include:

    stationery (boolean) Ñ non-modifiable Ñ this property is true if the file is a stationery pad document; since JPEGView does not support stantionery pad documents, this will always return false
    name (boolean) Ñ modifiable Ñ this contains the name of the file, specified as a full pathname; for example, a file named ÒExample.PICTÓ in the folder ÒTemporaryÓ on the volume ÒMy Hard DriveÓ would have a pathname of ÒMy Hard Drive:Temporary:Example.PICTÓ

window:  a window.  Window objects describe properties of the visible (and invisible) windows on the screen.  Windows that contain a document will contain exactly one document object and one drawing area object.  All other windows will contain no elements.  The window properties supported in JPEGView are:

    bounds (bounding rectangle) Ñ modifiable Ñ this property describes the position and size of the window on the screen; if you want to change the size of a window that contains an image, change the bounds property of the drawing area instead
    closeable (boolean) Ñ non-modifiable Ñ this property is true if the window has a close box; only the Preferences and Slide Show Options dialogs are missing a close box
    titled (boolean) Ñ non-modifiable Ñ this property is true if the window has a title bar; this is true of all of JPEGViewÕs windows
    index (integer) Ñ non-modifiable Ñ this is the position of the window in the list; for instance, the frontmost window would return 1, the second window would return 2, etc.
    floating (boolean) Ñ non-modifiable Ñ this property is true if the window is a floating window; JPEGViewÕs Statistics, Comments, and Colors windows all qualify as floating
    modal (boolean) Ñ non-modifiable Ñ this property is true if the window is a modal window; only JPEGViewÕs Preferences and Slide Show Options dialogs are modal
    resizable (boolean) Ñ non-modifiable Ñ this property is true if the window is resizable; in JPEGView, only image windows are resizable
    zoomable (boolean) Ñ non-modifiable Ñ this property is true if the window can be zoomed; image windows and the Statistics floating window can be zoomed in JPEGView
    zoomed (boolean) Ñ modifiable Ñ this property is true if the window is zoomed to a non-standard state
    name (boolean) Ñ modifiable Ñ this is the title of the window
    selection (boolean) Ñ non-modifiable Ñ this property points to a selection object whose bounds property describes the current selection in this window
    visible (boolean) Ñ modifiable Ñ this property is true if the window is currently visible on the desktop
    full screen (boolean) Ñ modifiable Ñ this property is true if the window is a full-screen window
    contents (image/full screen image/image statistics/image comments/screen colors/help text/slide show options/preferences/	about box/slide show controls/about help) Ñ non-modifiable Ñ this property describes briefly what the image is displaying


Object classes in the QuickDraw Graphics Suite

drawing area:  a drawing area in a window.  This class serves to represent the area of a window inside which images are drawn.  In JPEGView, members of the drawing area class always contain exactly one image.  The supported properties of the drawing area object include:

    bounds (bounding rectangle) Ñ modifiable Ñ this property describes the area inside of which the image is drawn; for normal windows, this coincides with the bounds of the window itself; for full-screen windows, this represents the area that the image is drawn in; set this property if you wish to change the size of the displayed image
    colors (system colors/grayscales/image colors/two pass color reduction) Ñ modifiable Ñ this property specifies the current color set used for drawing the image; if two pass color reduction is requested and the color reduction algorithm has not yet been applied to the image, it will be done immediately
    color table (color table) Ñ modifiable Ñ this property contains the current full color table of the image; in most cases, it is easier to work with the colors property instead
    scale (fixed) Ñ modifiable Ñ this property describes the current scaling factor used in drawing the image; set this as an alternative to manipulating the bounds property directly
    quality (very high/high/normal) Ñ modifiable Ñ this property specifies the current drawing quality applied to the image
    transfer mode (no dithering/dithering) Ñ modifiable Ñ this property specifies how the image is drawn, either with dithering or without

pixel map:  a pixel map.  This object is used to describe the offscreen buffer that JPEGView uses for fast window updating.  The two pixel map properties that are supported are:

    bounds (bounding rectangle) Ñ non-modifiable Ñ this is the size of the offscreen buffer
    pixel depth (small integer) Ñ non-modifiable Ñ this is the depth, or number of colors specified as n, where 2^n is the number of colors available


Commands in the JPEGView Suite

The commands in the JPEGView suite provide access to two of JPEGViewÕs more important features: two-pass color reduction, and slide shows.

reduce:  Reduce an image to a given number of colors.  This command, which applies to image objects only, allows you to calculate an optimal color set reduced to a specified number of colors.  The result is a color table object which can be used to set the color table property of a drawing area object.  If you want to set an imageÕs colors to the standard reduced color set in JPEGView, set the colors property of the drawing area instead.  Normally, this command is not used in scripts.

slide show:  Set up and begin a JPEGView slide show.  This powerful function allows you to specify a folder or a set of files to view in a JPEGView slide show, along with a number of options that control how the images are to be displayed.  The options parameters are, naturally, optional, with their values taken from the last set of user preferences if not specified by the command.  These options are:

    with delay seconds Ñ specifies the delay between successive images, in seconds
    filenames true/false Ñ controls whether filenames are displayed along with each image
    images from disk true/false Ñ specifies whether the slide show is disk-based or memory-based
    no errors true/false Ñ specifies whether error messages are suppressed during the slide show
    importing true/false Ñ controls whether all files found are tried, or whether only files whose file types are correct according to the Finder are opened for display
    shuffling true/false Ñ controls whether the slides are shuffled before each repetitition of the slide show
    looping true/false Ñ specifies whether the slide show repeats indefinitely (loops)
    recursive scan true/false Ñ controls whether a disk-based scan for files scans subfolders recursively
    user control true/false Ñ specifies whether the slide show is user-controlled or automatic
    offscreen drawing true/false Ñ controls whether the next slide is prepared offscreen
    auto comments true/false Ñ controls whether the Comments floating window appears automatically when comments are found in an image
    hidden windoids true/false Ñ controls whether floating windows (windoids) are automatically hidden at the start of the slide show
    hidden controls true/false Ñ controls whether the Slide Show Controls floating window is hidden at the start the slide show
    screen saver true/false Ñ specifies whether to run in screen saver mode; in this mode, JPEGView ensures that it is always the frontmost application, and immediately aborts the slide show and quits whenever the mouse is moved or clicked, or a key is pressed


Object classes in the JPEGView Suite

image:  an image graphic.  Image objects in JPEGView describe the fundamental information about the image itself, not about the way in which the image is drawn on your screen.  Images can contain zero or one pixel maps, depending on whether the image has an associated offscreen buffer.  The properties supported by the image class are:

    bounds (bounding rectangle) Ñ modifiable Ñ this property specifies the current bounding rectangle of the image; to crop an image, set this property to a rectangle smaller than the originalÊbounds property
    comments (string) Ñ non-modifiable Ñ this property contains the comments field, if any, found with the image
    display time (integer) Ñ non-modifiable Ñ this property specifies the amount of time needed to decompress and draw the full image, in milliseconds; it is only set after the image has been decompressed and drawn the first time
    format (type class) Ñ non-modifiable Ñ this property tells you which format the image is in, according to the file type codes described in the File Formats and File Types chapter, i.e., PICT, JPEG, or GIFf.
    compression (type class) Ñ non-modifiable Ñ this property specifies a code indicating the type of compression used on the image
    has image colors (boolean) Ñ non-modifiable Ñ this property is true if the image has its own internally-defined color table
    has reduced colors (boolean) Ñ non-modifiable Ñ this property is true if the image has a color set produced by two-pass color reduction
    image colors (color table) Ñ non-modifiable Ñ this property contains the full image color set
    compressed (boolean) Ñ non-modifiable Ñ this property is true if the image is compressed
    aborted (boolean) Ñ non-modifiable Ñ this property is true if the last decompression of the image was interrupted in some way
    banded (boolean) Ñ non-modifiable Ñ this property is true if the full image is actually several smaller horizontal strips connected together
    corrupt (boolean) Ñ non-modifiable Ñ this property is true if the image data has been found to be invalid in some way
    cropped (boolean) Ñ non-modifiable Ñ this property is true if the image has been cropped in any way
    original bounds (bounding rectangle) Ñ non-modifiable Ñ this property contains the full-size original bounds of the image
    pixel depth (small integer) Ñ non-modifiable Ñ this property specifies the number of colors in the image as n, where 2^n is the total number of colors in the image
    reduced colors (color table) Ñ non-modifiable Ñ this property contains the full reduced color set
    length (integer) Ñ non-modifiable Ñ this property contains the length of the image, in bytes

The following classes are not really members of the JPEGView object hierarchy; rather, they are really just placeholders for the appropriate file format that you can specify with the save command.

picture:  an image in PICT format.
JFIF:  an image in JFIF format.
startup screen:  an image in Startup Screen format.
GIF:  an image in GIF format.
TIFF:  an image in TIFF format.
BMP:  an image in BMP format.
MacPaint:  an image in MacPaint format.