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
$99.76
Apple Inc.
+2.09
MSFT
$44.08
Microsoft Corpora
+0.45
GOOG
$520.84
Google Inc.
+9.67

MacTech Search:
Community Search:

Software Updates via MacUpdate

Macgo Blu-ray Player 2.10.9.1750 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
TechTool Pro 7.0.5 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PDFKey Pro 4.0.2 - Edit and print passwo...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Yasu 2.9.1 - System maintenance app; per...
Yasu was originally created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks... Read more
Hazel 3.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a... Read more
Autopano Giga 3.7 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
MenuMeters 1.8 - CPU, memory, disk, and...
MenuMeters is a set of CPU, memory, disk, and network monitoring tools for Mac OS X. Although there are numerous other programs which do the same thing, none had quite the feature set I was looking... Read more
Coda 2.5 - One-window Web development su...
Coda is a powerful Web editor that puts everything in one place. An editor. Terminal. CSS. Files. With Coda 2, we went beyond expectations. With loads of new, much-requested features, a few... Read more
Arq 4.6.1 - Online backup to Google Driv...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more

Latest Forum Discussions

See All

This Week at 148Apps: October 13-17, 201...
Expert App Reviewers   So little time and so very many apps. What’s a poor iPhone/iPad lover to do? Fortunately, 148Apps is here to give you the rundown on the latest and greatest releases. And we even have a tremendous back catalog of reviews; just... | Read more »
Angry Birds Transformers Review
Angry Birds Transformers Review By Jennifer Allen on October 20th, 2014 Our Rating: :: TRANSFORMED BIRDSUniversal App - Designed for iPhone and iPad Transformed in a way you wouldn’t expect, Angry Birds Transformers is a quite... | Read more »
GAMEVIL Announces the Upcoming Launch of...
GAMEVIL Announces the Upcoming Launch of Mark of the Dragon Posted by Jessica Fisher on October 20th, 2014 [ permalink ] Mark of the Dragon, by GAMEVIL, put | Read more »
Interview With the Angry Birds Transform...
Angry Birds Transformers recently transformed and rolled out worldwide. This run-and-gun title is a hit with young Transformers fans, but the ample references to classic Transformers fandom has also earned it a place in the hearts of long-time... | Read more »
Find Free Food on Campus with Ypay
Find Free Food on Campus with Ypay Posted by Jessica Fisher on October 20th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
Strung Along Review
Strung Along Review By Jordan Minor on October 20th, 2014 Our Rating: :: GOT NO STRINGSUniversal App - Designed for iPhone and iPad A cool gimmick and a great art style keep Strung Along from completely falling apart.   | Read more »
P2P file transferring app Send Anywhere...
File sharing services like Dropbox have security issues. Email attachments can be problematic when it comes to sharing large files. USB dongles don’t fit into your phone. Send Anywhere, a peer-to-peer file transferring application, solves all of... | Read more »
Zero Age Review
Zero Age Review By Jordan Minor on October 20th, 2014 Our Rating: :: MORE THAN ZEROiPad Only App - Designed for the iPad With its mind-bending puzzles and spellbinding visuals, Zero Age has it all.   | Read more »
Hay Ewe Review
Hay Ewe Review By Campbell Bird on October 20th, 2014 Our Rating: :: SAVE YOUR SHEEPLEUniversal App - Designed for iPhone and iPad Pave the way for your flock in this line drawing puzzle game from the creators of Worms.   | Read more »
My Very Hungry Caterpillar (Education)
My Very Hungry Caterpillar 1.0.0 Device: iOS Universal Category: Education Price: $3.99, Version: 1.0.0 (iTunes) Description: Care for your very own Very Hungry Caterpillar! My Very Hungry Caterpillar will captivate you as he crawls... | Read more »

Price Scanner via MacPrices.net

2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Updated iPad Prices
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers, including the new iPad Air 2 and the... Read more
Apple Pay Available to Millions of Visa Cardh...
Visa Inc. brings secure, convenient payments to iPad Air 2 and iPad mini 3as well as iPhone 6 and 6 Plus. Starting October 20th, eligible Visa cardholders in the U.S. will be able to use Apple Pay,... Read more
Textkraft Pocket – the missing TextEdit for i...
infovole GmbH has announced the release and immediate availability of Textkraft Pocket 1.0, a professional text editor and note taking app for Apple’s iPhone. In March 2014 rumors were all about... Read more
C Spire to offer iPad Air 2 and iPad mini 3,...
C Spire on Friday announced that it will offer iPad Air 2 and iPad mini 3, both with Wi-Fi + Cellular, on its 4G+ LTE network in the coming weeks. C Spire will offer the new iPads with a range of... Read more
Belkin Announces Full Line of Keyboards and C...
Belkin International has unveiled a new lineup of keyboard cases and accessories for Apple’s newest iPads, featuring three QODE keyboards and a collection of thin, lightweight folios for both the... Read more
Verizon offers new iPad Air 2 preorders for $...
Verizon Wireless is accepting preorders for the new iPad Air 2, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB iPad Air 2 WiFi... Read more
Price drops on refurbished Mac minis, now ava...
The Apple Store has dropped prices on Apple Certified Refurbished previous-generation Mac minis, with models now available starting at $419. Apple’s one-year warranty is included with each mini, and... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Refurbished 2013 MacBook Pros available for u...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As businesses discover the power of Apple computers and mobile devices, it's your job - as a Solutions Engineer - to show them how to introduce these Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.