TweetFollow Us on Twitter

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.


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.


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


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 {
 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.


class TWVDocument : public TFileBasedDocument {
 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!


class TPageView : public TView {
 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.


class TPagePicture : public TPicture {
 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


class TScrollCmd : public TTracker {
 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 {
 virtual void Hilite(void);
 virtual void SuperViewChangedFrame(const VRect& oldFrame,
 const VRect& newFrame, Boolean invalidate);
class TPageText : public TStaticText {
 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.


class TPagePrintHandler : public TStdPrintHandler {
 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.


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
 if (!string.IsEmpty()) {
 StringToNum(string, &page);


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.

// 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) {
 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.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Planet Diver guide - How to survive long...
Planet Diver is an endless arcade game about diving through planets while dodging lava, killing bats, and collecting Starstuff. Here are some tips to help you go the distance. [Read more] | Read more »
KORG iDS-10 (Music)
KORG iDS-10 1.0.0 Device: iOS iPhone Category: Music Price: $9.99, Version: 1.0.0 (iTunes) Description: ** Debut Discount: 50% OFF! Sale Price US$9.99 (Regular price US$19.99). Other all Korg apps are also 50% OFF until Dec 28! **... | Read more »
World of Tanks Generals guide - Tips and...
World of Tanks Generals is a brand new card game by the developer behind the World of Tanks shooter franchise. It plays like a cross between chess and your typical card game. You have to keep in consideration where you place your tanks on the board... | Read more »
TruckSimulation 16 guide: How to succeed...
Remember those strangely enjoyable truck missions in Grand Theft Auto V whereit was a disturbing amount of fun to deliver cargo? TruckSimulation 16 is reminiscent of that, and has you play the role of a truck driver who has to deliver various... | Read more »
The best GIF making apps
Animated GIFs have exploded in popularity recently which is likely thanks to a combination of Tumblr, our shorter attention spans, and the simple fact they’re a lot of fun. [Read more] | Read more »
The best remote desktop apps for iOS
We've been sifting through the App Store to find the best ways to do computer tasks on a tablet. That gave us a thought - what if we could just do computer tasks from our tablets? Here's a list of the best remote desktop apps to help you use your... | Read more »
Warhammer 40,000: Freeblade guide - How...
Warhammer 40,000: Freebladejust launched in the App Store and it lets you live your childhood dream of blowing up and slashing a bunch of enemies as a massive, hulking Space Marine. It's not easy being a Space Marine though - and particularly if... | Read more »
Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »

Price Scanner via

World’s First USB-C Adapter For MacBook Suppo...
Innergie, a brand of Delta Electronics, has announced its official release of the world’s first USB-C adapter supporting four DC output voltages, the PowerGear USB-C 45. This true Type C adapter... Read more
13-inch and 11-inch MacBook Airs on sale for...
B&H Photo has 13″ and 11″ MacBook Airs on sale for up to $120 off MSRP as part of their Holiday sale including free shipping plus NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $819 $90 off... Read more
13-inch MacBook Pros on sale for up to $150 o...
Take up to $150 off MSRP on the price of a new 13″ MacBook Pro at B&H Photo today as part of their Holiday sale. Shipping is free, and B&H charges NY tax only. These prices are currently the... Read more
13-inch 128GB MacBook Air now on sale for $79...
Best Buy has just lowered their price on the 2015 13″ 1.6GHz/128GB MacBook Air to $799.99 on their online store for Cyber Monday. Choose free shipping or free local store pickup (if available). Sale... Read more
Best Buy lowers 13-inch MacBook Pro prices, n...
Best Buy has lowered prices on select 13″ MacBook Pros this afternoon. Now save up to $200 off MSRP for Cyber Monday on the following models. Choose free shipping or free local store pickup (if... Read more
Cyber Monday: Apple MacBooks on sale for up t...
Apple resellers have MacBook Pros, MacBook Airs, and MacBooks on sale for up to $250 off MSRP for Cyber Monday 2015. The following is a roundup of the lowest prices available for new models from any... Read more
Cyber Monday: Apple Watch on sale for up to $...
B&H Photo has the Apple Watch on sale for Cyber Monday for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - Apple Watch Sport: $50 off - Apple Watch: $50-$100 off B... Read more
Cyber Monday: 15% off Apple products, and sto...
Use code CYBER15 on Cyber Monday only to take 15% on Apple products at Target, and store-wide. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-... Read more
iPad Air 2 And iPad mini Among Top Five Black...
Adobe has released its 2015 online shopping data for Black Friday and Thanksgiving Day. The five best selling electronic products on Black Friday were Samsung 4K TVs, Apple iPad Air 2, Microsoft Xbox... Read more
All-in-one PC Shipments Projected To Drop Ove...
Digitimes’ Aaron Lee and Joseph Tsai report that all-in-one (AIO) PC shipments may drop a double-digit percentage on-year in 2015 due to weaker-than-expected demand, although second-largest AIO make... Read more

Jobs Board

*Apple* New Products Tester Needed - Apple (...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, continues Read more
Software Engineer, *Apple* Watch - Apple (U...
# Software Engineer, Apple Watch Job Number: 33362459 Santa Clara Valley, Califo ia, United States Posted: Jul. 28, 2015 Weekly Hours: 40.00 **Job Summary** Join the Read more
SW Engineer - *Apple* Music - Apple (United...
# SW Engineer - Apple Music Job Number: 40899104 San Francisco, Califo ia, United States Posted: Aug. 18, 2015 Weekly Hours: 40.00 **Job Summary** Join the Android Read more
Sr Software Engineer *Apple* Pay - Apple (U...
# Sr Software Engineer Apple Pay Job Number: 44003019 Santa Clara Valley, Califo ia, United States Posted: Nov. 13, 2015 Weekly Hours: 40.00 **Job Summary** Apple Read more
*Apple* Site Security Manager - Apple (Unite...
# Apple Site Security Manager Job Number: 42975010 Culver City, Califo ia, United States Posted: Oct. 2, 2015 Weekly Hours: 40.00 **Job Summary** The Apple Site Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.