TweetFollow Us on Twitter

WorldViewer
Volume Number:12
Issue Number:4
Column Tag:Macapp Adventures

Documentation Viewer Lite

Help save a tree today!

By Matthew Clark, WorldView Information Technology

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

Introduction

This article documents the creation of an ad hoc application using MacApp. Our goal was simple: build a documentation viewer for our manual, presentation slides, scripting dictionary, and product screen-shots. A quick survey of the existing viewer tools had led us to the conclusion: “What? They want how much money? Hey, we don’t need all those features!” (Of course, this all happened back before Adobe dropped its per-reader fee for Acrobat from $25 to zero.) So we decided to do it ourselves.

The requirements for this application are straightforward. The screen must display an exact duplicate of the original printed pages. Access to the pre-formatted documentation source is denied, but the user can copy and print the displayed pages. Simple page navigation is needed, but not content-based searching. The last requirement is the name: we’re working at WorldView, so it is natural to title the application WorldViewer.

Approach

The first hurdle is to create the on-line documents from a variety of publishing applications. If a bitmapped picture approach is used, the documentation files will be huge, printed pages cannot rescale text for maximal printer resolution, and zooming will show “jaggies”. On the other hand, if a picture ('PICT') file or resource is used, then the image will scale correctly. An added benefit is that the Mac toolbox routine DrawPicture substitutes fonts if the original fonts are not present. Our solution is to use the shareware utility Print2Pict, by Baudouin Raoult. It is placed into the Extensions Folder and activated by using the Chooser to select it as the “printer”. When you “print”, Print2Pict records each output page as a 'PICT' resource in a scrapbook file.

The WorldViewer application itself is based on MacApp 3.3 (actually, it was originally done with MacApp 3.1, and source code for both versions is provided). As many Macintosh programmers already know, MacApp is an object-oriented framework for writing applications. The main advantage is that the developer can leverage tens of programmer-years of work and have instant support for AppleEvents, the Scrap Manager, window management, event handling, printing, and other modules required of almost all Macintosh programs. Our application was written in only a few days and contains less than a thousand lines of source code.

Figure 1. A sample document in WorldViewer

Human Interface

Figure 1 illustrates the final screen interface. It evolved during development (as so often happens), but let’s pretend the design was fully completed first.

Separate tools are needed for navigating forward and backward, scrolling the page within the window, and zooming. The navigation operation should be context-dependent: the next-page cursor icon is displayed when the cursor is on the right-hand side of the screen and clicking goes to the next page; whereas, clicking the left side of the view goes to the previous page. Important information is to be displayed: the document name (in the window title), the page number (in lower-left), and the selected tool (hilited at bottom, also in the cursor icon). Modifier keys must switch between tool types, for power users; for example, holding the shift-key down changes from zoom-in to zoom-out, and depressing the option-key activates the hand (scrolling) tool. Dialogs are needed for selecting specific pages to jump to, and exact zoom amounts. A mechanism to navigate by sections or chapters instead of pages would be helpful for large documents.

Figure 2 shows the menu interface, without command-key equivalents. The menu titled Section should change to reflect the make-up of the document file in the frontmost window.

Figure 2. Menu structure for WorldViewer

Implementation

The object-oriented design of MacApp is ideal for our project. The document class can be used to identify each open documentation file. A view class can be used to draw a page of the documentation file. The control classes can be used as bases for writing both the page number control and the tools palette.

In all, eight classes were needed to implement WorldViewer. The following is a listing of the class declarations from the interface source file. MacApp-required source lines such as MA_DECLARE_CLASS; have been removed to reduce clutter (see the complete source code online).

TWVApplication class

class TWVApplication : public TApplication {
 public:
 void IWVApplication(void);
 virtual TFile* DoMakeFile(CommandNumber aCommandNumber);
 virtual TDocument* DoMakeDocument(
 CommandNumber itsCommandNumber, TFile* itsFile);
 virtual void DoMenuCommand(CommandNumber aCommandNumber);
};

The TWVApplication is descended from TApplication, the base application class of MacApp. The DoMakeFile method overrides the default method so that the document file’s resource fork remains open. If each documentation file stays on disk and 'PICT' files are loaded only when needed, the application memory partition is minimal. The only purpose of the DoMenuCommand method is to intercept calls to the About menu command.

TWVDocument

class TWVDocument : public TFileBasedDocument {
 public:
 void IWVDocument(TFile* itsFile, OSType itsCreator);
 void SetupFile(void);
 virtual void Close(void);
 virtual void DoMakeViews(Boolean forPrinting);
 virtual void DoSetupMenus(void);
 virtual void DoMenuCommand(CommandNumber aCommandNumber);
 virtual long GetChangeCount(void);
};

The TWVDocument class is responsible for interacting with the documentation file. The SetupFile method is used to set the documentation file as frontmost in the resource chain. Without this method, the viewer may load in incorrect 'PICT' resources from documentation files with identical resource numbers. The DoMakeViews method specifies which 'View' resource to use to display the document. A 'View' resource specifies the placement of dialog items, like a 'DITL' resource souped up to handle more versatile display objects.

The purpose of overriding the DoSetupMenus and DoMenuCommand methods is to have the ability to create multiple windows to view the same document. It’s easy using MacApp - only a few lines of code are needed!

TPageView

class TPageView : public TView {
 public:
 short  fMaxPages, //     max. number of pages
 fPage, //    page number
 fZoom; //    zoom amount
 void SetupFile(void);
 virtual void DoPostCreate(TDocument* itsDocument);
 void SetPage(short newPage);
 void SetZoom(short newZoom, VPoint center);
 void SetTool(short newTool);
 virtual void DoSetupMenus(void);
 virtual void DoMenuCommand(CommandNumber aCommandNumber);
 virtual void DoEvent(EventNumber eventNumber,
 TEventHandler* source, TEvent* event);
 virtual void DoKeyEvent(TToolboxEvent* event);
 virtual void Draw(const VRect& area);
};

The documentation page, scrollbars, and controls are displayed within the TPageView class. The method SetupFile operates identically to the same-named method of TWVDocument. In DoPostCreate, the default view and window sizes are set to the size of the first 'PICT' stored in the document file. The DoSetupMenus and DoMenuCommand methods are for implementing the zooming and navigation menu commands. The Draw method first makes a call to SetupFile before drawing the containing view objects. This assures that the correct 'PICT' resource is drawn by the picture object.

TPagePicture

class TPagePicture : public TPicture {
 public:
 short fTool;    //    [arrow,hand,zoom]
 CCrsrHandle fCursor;//      color cursor
 TPagePicture(); //    constructor
 virtual void Activate(Boolean entering);
 virtual void DoSetCursor(const VPoint& localPoint,
 RgnHandle cursorRegion);
 virtual void DoMouseCommand(VPoint& theMouse,
 TToolboxEvent* event, CPoint hysteresis);
};

The TPagePicture class displays the 'PICT' resource from the documentation file. The field fTool stores the tools status, either navigation arrow, hand, or zoom. The fCursor field caches the color cursor, reducing the number of times a color cursor must be created from a resource.

The Activate method instructs the application to always track the cursor; this provides instantaneous change in the cursor icon when a modifier key is pressed. The method DoSetCursor sets the cursor to reflect the appropriate tool, based on the fTool field, keyboard modifiers, and page number; see Figure 3 for the cursor icon set. In DoMouseCommand, the appropriate command is dispatched given the tool and keyboard modifier states.

Figure 3. Color cursors

TScrollCmd

class TScrollCmd : public TTracker {
 public:
 CCrsrHandle fCursor;//      closed hand cursor
 VRect fOrigRect;//    original visible rectangle
 VPoint fOrigPoint;//     original anchor point (window coords)
 void IScrollCmd(TPagePicture* aPagePicture,
 const VPoint& aMouse);
 virtual void TrackFeedback(TrackPhase trackPhase,
 const VPoint& anchorPoint,
 const VPoint& previousPoint,
 const VPoint& nextPoint,
 Boolean mouseDidMove,
 Boolean turnItOn);
 virtual TTracker* TrackMouse(TrackPhase trackPhase,
 VPoint& anchorPoint, VPoint& previousPoint,
 VPoint& nextPoint, Boolean mouseDidMove);
};

The TScrollCmd is used for scrolling the documentation page within the view. The open-hand cursor is replaced by a closed-hand cursor, and the scrolling parameters of the view are changed as the cursor moves. The scrolling operation is straightforward using MacApp: the display rectangle of the TPageView object is modified based on the cursor location, the screen image is scrolled, and the revealed areas of the picture are drawn.

TPageText and TPageIcon

class TPageIcon : public TIcon {
 public:
 virtual void Hilite(void);
 virtual void SuperViewChangedFrame(const VRect& oldFrame,
 const VRect& newFrame, Boolean invalidate);
};
class TPageText : public TStaticText {
 public:
 virtual void Hilite(void);
 virtual void SuperViewChangedFrame(const VRect& oldFrame,
 const VRect& newFrame, Boolean invalidate);
};

The display of the page number in the lower-left corner of the window is handled by the TPageText class. The TPageIcon class displays the selected tool at the bottom of the window. The Hilite methods change the control hiliting method from a simple inversion (the default MacApp method) to coloring the empty area with the system selection color. The SuperViewChangedFrame methods are required so that the control relocates itself in the bottom-left corner when the window is resized.

TPagePrintHandler

class TPagePrintHandler : public TStdPrintHandler {
 public:
 void IPagePrintHandler(TView* aView);
 virtual Boolean Print(CommandNumber itsCommandNumber);
 virtual Boolean SetupPrintOne(void);
 virtual void SetPage(long aPageNumber);
 virtual void CalcPageStrips(VPoint& pageStrips);
 virtual void DrawPageInterior(void);
};

The printing of a document page requires some special handling. The default MacApp mechanism divides a view into printer page-sized output pieces and prints the pages sequentially. The methods of TPagePrintHandler collectively make sure that the selected page is the correct 'PICT' resource from the document file.

Dialogs

Two dialogs are needed to input specific values for going to a page number or setting the zoom amount. Figure 4 shows them.

Figure 4: Go to and Zoom dialog boxes

The MacApp utility application ViewEdit was used to create all dialogs. Note that no application-specific classes are needed to instantiate, activate, and get the results from these dialogs. This illustrates the fact that new subclasses are not needed for every different operation. Here is a code snippet from the method TPageView::DoMenuCommand processing the GoTo menu command (some error-checking and declaration code have been removed).

TPageView::DoMenuCommand [excerpt]
// create new window containing dialog
aWindow = gViewServer->NewTemplateWindow(kGoToView, NULL);
// set current page in text edit object
aEditText = (TEditText*) aWindow->FindSubView('tPg#');
NumToString(fPage + 1, string);
aEditText->SetText(string, kDontRedraw);
// pose the dialog window
if (aWindow->PoseModally() == 'bOK ') {
    //    get new page number
 aEditText->GetText(string);
 if (!string.IsEmpty()) {
 StringToNum(string, &page);
 this->SetPage(page);
 };
};
aWindow->CloseAndFree();

Sections

One feature not yet covered is the ability to move forward and backwards through the documentation pages by sections or chapters. This is accomplished by adding the resource 'indx' to the documentation file that lists the section names and the starting page number of each section. When a documentation file is opened and activated within WorldViewer, the menu items under the Section menubar are changed to the section names. When one of these menu items is selected, the page associated with the section start is automatically displayed. Here we show the MPW Rez source file used to create the section resource.

dictionary.r
// Creates an ‘indx’ resource for a WorldViewer documentation file

#include "Types.r"

type 'indx' {
 integer = $$Countof(IndexArray);
 array IndexArray { integer; pstring; align word; };
};

resource 'indx' (1000, "index", purgeable) {
 {
 1,"Title",
 2,"Required Suite",
 3,"Core Suite",
 7,"Miscellaneous Standards",
 9,"Reality Suite",
 }
};

Creating a Document

Here is an example of creating a WorldViewer documentation file. First, install the Print2Pict utility and select it using the Chooser. Open the Print2Pict options and choose to print to a new scrapbook file. If you like, you can reduce the default page size to a screen-sized amount, such as 4 by 6.

Next, start your favorite word processing program and enter the following lines, separated by a page break.

 Hello, WorldViewer!
 This is the second page.

Print this document using Print2Pict and find the scrapbook file named {Program}•-Untitled•001 that was created (the bracketed “{Program}” is the name of your word processing program).

Rename the file to Hello. Start the ResEdit utility and change the file’s creator to 'WVMN' and the file type to 'manl'. Save the file and quit the application.

Double-click the documentation file Hello from the Finder. Figure 5 shows this documentation file opened within WorldViewer.

Figure 5: The Hello documentation file

Remember that a documentation file can be created from any printable source, including publishing applications, drawing programs, and label-makers. With ResEdit and a little finagling, 'PICT' resources from different source applications can be placed into a single WorldViewer documentation file.

In Conclusion

WorldViewer was not intended to replace Apple Computer’s DocViewer or other documentation viewers, but rather to create a home-grown reduced-feature version. As more software products are distributed using CD-ROM media and networks, the inclusion of on-line documentation will become more widespread. For those developers who need an easy (and cheap!) method to include their documentation, WorldViewer is a solution. Further, the ease with which it was implemented (as well as the simplicity of updating for MacApp 3.3, including the generation of a FAT binary) is a recommendation for the MacApp approach.

Related Reading

Cox, B., Object Oriented Programming: An Evolutionary Approach, Addison-Wesley, 1986.

Wilson, D., Rosenstein, L., and Shafer, D., Programming with MacApp, Addison-Wesley, 1990.

 
AAPL
$119.00
Apple Inc.
+1.40
MSFT
$47.75
Microsoft Corpora
+0.28
GOOG
$540.37
Google Inc.
-0.71

MacTech Search:
Community Search:

Software Updates via MacUpdate

HoudahSpot 3.9.6 - Advanced file search...
HoudahSpot is a powerful file search tool built upon MacOS X Spotlight. Spotlight unleashed Create detailed queries to locate the exact file you need Narrow down searches. Zero in on files Save... Read more
RapidWeaver 6.0.3 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
iPhoto Library Manager 4.1.10 - Manage m...
iPhoto Library Manager lets you organize your photos into multiple iPhoto libraries. Separate your high school and college photos from your latest summer vacation pictures. Or keep some photo... Read more
iExplorer 3.5.1.9 - View and transfer al...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
MacUpdate Desktop 6.0.3 - Discover and i...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more
SteerMouse 4.2.2 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. It also supports Apple Mighty Mouse very well. SteerMouse can assign various functions to buttons that Apple's software does not allow,... Read more
iMazing 1.1 - Complete iOS device manage...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
PopChar X 7.0 - Floating window shows av...
PopChar X helps you get the most out of your font collection. With its crystal-clear interface, PopChar X provides a frustration-free way to access any font's special characters. Expanded... Read more
Carbon Copy Cloner 4.0.3 - Easy-to-use b...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
ForeverSave 2.1.3 - Universal auto-save...
ForeverSave auto-saves all documents you're working on while simultaneously doing backup versioning in the background. Lost data can be quickly restored at any time. Losing data, caused by... Read more

Latest Forum Discussions

See All

Make Way for Fat Chicken, from the Maker...
Make Way for Fat Chicken, from the Makers of Scrap Squad Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Relevant Games has announced they will be releasing their reverse tower defense game, | Read more »
Tripnary Review
Tripnary Review By Jennifer Allen on November 26th, 2014 Our Rating: :: TRAVEL BUCKET LISTiPhone App - Designed for the iPhone, compatible with the iPad Want to create a travel bucket list? Tripnary is a fun way to do exactly that... | Read more »
Ossian Studios’ RPG, The Shadow Sun, is...
Ossian Studios’ RPG, The Shadow Sun, is Now Available for $4.99 Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Mmmm, Tasty – Having the Angry Birds for...
The very first Angry Birds debuted on iOS back in 2009. When you sit back and tally up the number of Angry Birds games out there and the impact they’ve had on pop culture as a whole, you just need to ask yourself: “How would the birds taste... | Read more »
Rescue Quest Review
Rescue Quest Review By Jennifer Allen on November 26th, 2014 Our Rating: :: PATH BASED MATCH-3Universal App - Designed for iPhone and iPad Guide a wizard to safety by matching gems. Rescue Quest might not be an entirely original... | Read more »
You Can Play the Final Chapter of Lone W...
You Can Play the Final Chapter of Lone Wolf: Dawn Over V’taag Right Now Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Swords of Anima (Games)
Swords of Anima 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: A new tactical turn-based RPG experience. Command the Savior Rex Squad in an epic journey of courage and deception. Can you... | Read more »
Audio Defence: Zombie Arena
Audio Defence: Zombie Arena By Lee Hamlet on November 26th, 2014 Our Rating: :: DRAGS ITS FEETUniversal App - Designed for iPhone and iPad From the makers of Papa Sangre comes a defense game that forces players to listen carefully... | Read more »
Tales from the Borderland​s Will be Comi...
Tales from the Borderland​s Will be Coming to iOS by the End of the Year Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Telltale Games has announced | Read more »
Sunburn! Review
Sunburn! Review By Campbell Bird on November 26th, 2014 Our Rating: :: DON'T DIE ALONEUniversal App - Designed for iPhone and iPad Platform through the depths of space to make sure your entire crew dies together in this satisfying... | Read more »

Price Scanner via MacPrices.net

2014 1.4GHz Mac mini on sale for $449, save $...
 B&H Photo has the new 1.4GHz Mac mini on sale for $449.99 including free shipping plus NY tax only. Their price is $50 off MSRP, and it’s the lowest price available for this new model. Adorama... Read more
Early Black Friday pricing on 27-inch 5K iMac...
 B&H Photo continues to offer Black Friday sale prices on the 27″ 3.5GHz 5K iMac, in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP... Read more
Early Black Friday sale prices on iPad Air 2,...
 MacMall is discounting iPad Air 2s by up to $75 off MSRP as part of their Black Friday sale. Shipping is free: - 16GB iPad Air WiFi: $459 $40 off - 64GB iPad Air WiFi: $559 $40 off - 128GB iPad Air... Read more
Early Black Friday MacBook Air sale prices, $...
 MacMall has posted early Black Friday MacBook Air sale prices. Save $101 on all models for a limited time: - 11″ 1.4GHz/128GB MacBook Air: $798 - 11″ 1.4GHz/256GB MacBook Air: $998 - 13″ 1.4GHz/... Read more
Why iPhone 6 Tablet/Laptop Cannibalization Is...
247wallst.com blogger Douglas A. McIntyre noted last week that according to research posted on the Applovin blog site the iPhone 6 is outselling the iPhone 6 Plus by a wide margin . Hardly a surprise... Read more
Worldwide Tablet Growth Expected to Slow to 7...
The global tablet market is expected to record massive deceleration in 2014 with year-over-year growth slowing to 7.2%, down from 52.5% in 2013, according to a new forecast from International Data... Read more
Touchscreen Glove Company Announces New Produ...
Surrey, United Kingdom based TouchAbility specializes in design and manufacture of a wide variety of products compatible with touchscreen devices including smartphones, tablets and computers. Their... Read more
OtterBox Alpha Glass Screen Protectors for iP...
To complement the bigger, sharper displays on the latest Apple devices, OtterBox has introduced Alpha Glass screen protectors to the iPhone 6 and iPhone 6 Plus. The fortified glass screen protectors... Read more
Early Black Friday Mac Pro sale, 6-Core 3.5GH...
 B&H Photo has the 6-Core 3.5GHz Mac Pro on sale today for $3499 including free shipping plus NY sales tax. Their price is $500 off MSRP, and it’s the lowest price available for this model from... Read more
Early Black Friday sale price: 15-inch 2.2GHz...
 B&H Photo has the 2014 15″ 2.2GHz Retina MacBook Pro on sale today for $1699.99. Shipping is free, and B&H charges NY sales tax only. Their price is $300 off MSRP, equalling Best Buy’s price... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.