PreViewDoc.tioga
Written by: Ken Pier, September 4, 1985
Last Edited By: Ken Pier, May 15, 1986 11:29:59 am PDT
PREVIEW TOOL DOCUMENTATION
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
PreView Tool
Ken Pier
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: PreView is a Cedar tool which allows users to open a viewer on any one of five file types: Interpress, Press, PD, Griffin, and AIS. There is also an option to use three color separation AIS files to get a full color picture. The user may scroll horizontally and vertically on any file page, and may flip through pages of a multi-page file. The user interface is the same for all the file types. PreView also provides interactive scaling, rotation, and cropping of file pages on display, with the option to either write a new Interpress file with the selected contents or to stuff the selected contents directly into a Tioga document in the form of a TiogaArtwork node.
Created by: Ken Pier
Maintained by: Ken Pier <Pier.PA>
Keywords: display, viewer, Interpress, Press, PD, AIS, Griffin, TiogaArtwork
XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304
For Internal Xerox Use Only
1. Introduction
PreView is a Cedar tool which allows users to open a viewer on any one of five file types: Interpress, Press, PD, Griffin, and AIS. There is also an option to use three color separation AIS files to get a full color picture. The user may scroll horizontally and vertically on any file page, and may flip through pages of a multi-page file. The user interface is the same for all the file types. PreView also provides interactive scaling, rotation, and cropping of file pages on display, with the option to either write a new Interpress file with the selected contents or to stuff the selected contents directly into a Tioga document in the form of a TiogaArtwork node.
2. Getting Started
Bringover
To get started, Bringover -p /Cedar/CedarChest@/Top/PreView.df.
Getting a new PreView Tool
Type "Preview [-switches] FileList" to the appropriate CommandTool, where [-switches] is an optional set of switches and FileList is a series of file names. Star expansion is permitted. PreView.load will be executed if this is the first use of PreView in the current session. File names with extension (e.g. /User/UserName/SubD/Foo.press, or ///Foo.Interpress) or short file names with or without extension (e.g. Bar, or Bar.AIS) may be in the FileList. If the short file name exists in the local context, it will be used. If it does not exist, and has no extension, PreView will attempt to find a local file by attempting the following default file extensions:
IP, Interpress, Press, PD, AIS, Griffin
(The user may modify this list of file extensions via a UserProfile option).
PreView uses the text of the file extension only as a hint to determine what file type is in the file; it looks within the file to determine its type. If the file exists and has a compatible type, a new PreView Tool will be opened (left column, iconic) on the file.
UserProfile Options and Switches
Profile Options
The user may modify the list of file extensions via the UserProfile option "PreView.Extensions". For example:
PreView.Extensions: "MyExtension YourExtension InterP Press".
Defaults are PreView.Extensions: "ip interpress press pd ais griffin".
The user may specify that, should file searching on the extensions fail, PreView then attempt to open the file specified in the command line using a "Tioga" Open. For example:
PreView.TryTiogaOpen: TRUE
Default is PreView.TryTiogaOpen: FALSE
Switches
Switches must be the first argument:
-f => Full Scale. Only applies to PD files, and specifies that a PD file should not be scaled for display on the screen, but should instead be displayed at a resolution of one screen pixel to one printing device pixel. For example:
PreView -f /Server/User/PD/BigFile.PD.
-c => Full Color. Only applies to AIS files, and specifies that the following three file names are to be treated as a triple of color separations in Red, Green, Blue order. Tokens after the three file names will be ignored. The file names must be complete and have no extension; ".ais" will be used. For example:
PreView -c /Server/User/AIS/My-red /Server/User/AIS/My-green /Server/User/AIS/My-blue.
The name displayed at the top of the preViewer will be "/Server/User/AIS/My-*.ais".
-v => Versatec. Only should be used for files which were destined for the large color Versatec plotter. PreView will assume a page size of 40" square, instead of the default size of 8.5"x11". For example:
PreView -v /Server/User/IP/BigColorFile.IP.
-m => No ImagerMemory. Preview uses a package called ImagerMemory to memorize Imager calls for fast repainting. ImagerMemory is used for Interpress and Griffin files only. If -m is given, painting will not use ImagerMemory but will be done from scratch each time. For example:
PreView -m /Server/User/Griffin/OddGriffin.Griffin.
Aliases
PreView.load defines two convenient aliases for use with the -c switch:
alias CPreView1 (Arg1) PreView -c Arg1-red Arg1-green Arg1-blue
alias CPreView2 (Arg1) PreView -c Arg1-red Arg1-grn Arg1-blu
For example:
"CPreView1 MyAIS" if your files are named MyAIS.red, MyAIS.green, MyAIS.blue
"CPreView2 MyAIS" if your files are named MyAIS.red, MyAIS.grn, MyAIS.blu
3. User Interface
The user interface consists of scrolling, transformation, paging, and output control functions. Scrolling and transformation are provided by the BiScrollers package, while paging and output control are implemented in the tool itself. All functions are nearly self-documenting if you experiment a bit with a PreView Tool.
Scrolling and Transformation Controls
Scrolling and image transformation are provided by the BiScrollers package, which displays two scroll bars in the image viewer and a transformation menu at the top of a PreView Tool.
Scrolling Controls
The BiScrollers vertical scroll bar is at the left of the viewer, and the horizontal scroll bar is at the bottom. They work in a manner analogous to a Tioga scroll bar. Move the cursor into the left edge of the viewer and the vertical scroll bar will appear. Scroll Up, Thumb, and Scroll Down are invoked as usual with left, middle and right mouse buttons respectively, and the scroll bar pattern indicates the percentage of the page that is actually displayed in the viewer. Similarly, move the cursor to the bottom of the viewer to invoke the horizontal scroll bar, which provides Scroll Left, Thumb, and Scroll Right.
Transformation Controls
The transformation menu at the top of the viewer is:
Scale Rotate Fit ResetAndCenter Center Vanilla Left Right Top Bottom Selection
The transformation menu buttons change the display when invoked by mouse buttons as outlined below. In addition, some of the buttons use the Tioga current selection as argument:
Scale:
left- scale image by (current selection);
middle- reset scale to 1.0;
right- scale image by 1.0/(current selection).
If current selection is not a number, the value 2.0 is used and a message may be flashed in the MessageWindow.
Rotate:
left- rotate image ccw by (current selection) degrees.
middle- reset rotation to 0 degrees;
right- rotate image cw by (current selection) degrees.
If (current selection) is not a number, the value 90.0 is used and a message may be flashed in the MessageWindow..
Fit:
any- scale and translate the image so as to maximize magnification while fitting the entire image in the viewer. Aspect ratio is preserved.
ResetAndCenter:
any- reset all scrolling transformations to their nominal values and center the image in the viewer.
Center:
any- center the image in the center of the viewer, preserving transformations.
Vanilla:
any- like ResetAndCenter, except moves the image so the upper left corner is in the upper left corner of the viewer. Handy for images containing text.
Left:
any- moves the image so the left extreme of the image is at the left of the viewer.
Right:
any- moves the image so the right image of the contents is at the right of the viewer.
Top:
any- moves the image so the top extreme of the image is at the top of the viewer.
Bottom:
any- moves the image so the bottom extreme of the image is at the bottom of the viewer.
Selection:
left- moves the image so the center of the PreView selection rectangle is in the center of the viewer. Requires a valid PreView selection. See "Making a PreView Selection", below.
middle- moves the image so the center of the PreView selection rectangle is in the center of the viewer, then fits the image so as to maximize magnification while fitting the entire image in the viewer. Aspect ratio is preserved. Requires a valid PreView selection. See "Making a PreView Selection", below.
right- cancels the current selection and selects the entire page. Useful for finding page boundaries before a ToIP command.
See /Cedar/CedarChest@/Documentation/BiScrollersDoc.tioga for detailed information.
Paging and Output Controls
Beneath the scrolling menu is a second menu:
Stuff ToIP FirstPage TurnPage LastPage Page
These menu buttons control paging through a multi-page file and creating output from PreView.
Paging Controls
To the right of the Page button is a small Tioga viewer in which the current page number is displayed. The user may edit the number and then use the Page button to cause that number to be the currently displayed page number. To the right of the current page number viewer is a slider; put the cursor in the slider and hold the left mouse button down to "thumb" through the pages of the document. The current page number viewer will change dynamically to indicate the page number that will become the currently displayed page if you release the left button.
The scrolling menu buttons change the display when invoked by the mouse buttons outlined below.
FirstPage:
any- causes the first page of the document to become the currently displayed page.
TurnPage:
left- causes the next page of the document to become the currently displayed page;
middle or right- causes the previous page of the document to become the currently displayed page.
LastPage:
any- causes the last page of the document to become the currently displayed page.
Page:
any- causes the page in the page number viewer to become the currently displayed page.
Output Controls
Making a PreView Selection:
Output is controlled by the Stuff and the ToIP buttons, and by the selection rectangle. The user sweeps out a selection by moving the cursor over the viewer (note the crosshairs cursor pattern). When the left mouse button is depressed, PreView will fix one corner of the selection rectangle at the mouse point. A rectangle is then swept out by holding down the left button continuously and rolling the mouse to the other selection rectangle corner; note the rubberbanding rectangle as feedback. When the button is let up, the opposite corner is fixed. The user may at any time cancel the selection by a middle button click in the viewer. The user may modify the second corner of an existing selection by again holding down the left button, resuming sweeping, and releasing at the new corner.
After selection, any transformations (e.g. Scale, Rotate, ...) invoked will also be reflected in the selection. It is possible but somewhat counterintuitive to modify the selection after invoking transformations. After setting the desired selection, the output control menu buttons may be invoked.
Stuff:
left or middle- causes the image in the (possibly transformed) selection to be converted to a Tioga Artwork node (of type Interpress) and then "stuffed" at the current selection. To see the image in the Artwork node, execute "artwork on" in a CommandTool.
right- causes the image in the (possibly transformed) selection to be converted to a Tioga Artwork node (of type Interpress) and then "stuffed" at the current selection. To see the image in the Artwork node, execute "ArtworkInterpress on" in a CommandTool.
ToIP:
left or middle- causes the image in the (possibly transformed) selection to be written to an Interpress Master whose filename is the current selection. The working directory of the CommandTool when PreView was invoked will be prepended to the selection.
right- ignores the selection and causes the entire (possibly transformed) page to be written to an Interpress Master whose filename is the current selection. The working directory of the CommandTool when PreView was invoked will be prepended to the selection.
N.B. The current implementations of clipping in the imaging contexts used by Stuff and ToIP do no culling or filtering. That means that even though a small selection is made to be copied, the entire page plus the clipping commands will appear in the output node or IP Master. This will be remedied as soon as culling or filtering contexts are implemented by the Imager.
The ScratchPad
THE SCRATCH PAD HAS BEEN DEIMPLEMENTED AND NO LONGER APPEAR.
A small text prompt viewer under the paging menu is provided for the user's convenience. Left clicking the label (ScratchPad: ) will move the current selection into the prompt window and make the prompt window contents "pending-delete." The caret may not appear, but it's there. The scratchpad is intended as a handy place to type scale factors, rotation factors, and file names which may then be selected as arguments for the PreView menu buttons.
PVSTOP! button
A button labeled PVSTOP! will appear in the static viewer column (near the MessageWindow) when PreView is first loaded. Clicking PVSTOP! will make an attempt to abort painting of ALL currently repainting PreViewers.
4. Programmers Interface
PreViewClient.Mesa has a single public procedure:
CreatePreViewer: PROC [fileNames: NameList, switches: Switches] RETURNS [preViewer: ViewerClasses.Viewer];
which returns a container which includes all the Viewers and BiScrollers outlined above. PreView.mesa should be considered private to the implementation.
5. Helpful hints
Scrolling transformations are not affected by page turning; if you turn a page and it doesn't display to your liking, try the Vanilla button and go from there.
Once you have invoked a time consuming operation, don't pass the mouse through a BiScrollers scroll bar. Since those bars are themselves implemented as viewers, that will result in locking the cursor and the viewer columns for the duration of the painting of that preViewer.
The first time a PreViewer is painted may go slowly due to remote file access, setting up internal data structures, building pixel maps, font cache filling, and imager memorizing. Scaling and rotating will also cause font caching activity the first time they are invoked. Subsequent paintings will be faster.
Painting a PD image is invariably slow if the PD file has small bands, because the processing is done one band at a time.
PVSTOP! doesn't work on Press files, but they paint fast anyway.
Patience is a virtue.