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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

iTubeDownloader 6.5.13 - Easily download...
iTubeDownloader is a powerful-yet-simple YouTube downloader for the masses. Because it contains a proprietary browser, you can browse YouTube like you normally would. When you see something you want... Read more
FileZilla 3.47.0 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.47.0: Fixed regression loading advanced site... Read more
Transmit 5.6.3 - Excellent FTP/SFTP clie...
Transmit is an excellent FTP (file transfer protocol), SFTP, S3 (Amazon.com file hosting) and iDisk/WebDAV client that allows you to upload, download, and delete files over the internet. With the... Read more
Doomsday 2.2.2 - Play classic Doom on mo...
id Software's Doom pioneered the modern first-person shooter genre. Released in 1993, it was a quantum leap in game engine technology with fluid and - at the time - incredibly realistic 3D graphics.... Read more
Ableton Live 10.1.9 - Record music using...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Maintenance 2.6.5 - System maintenance u...
Maintenance is a system maintenance and cleaning utility. It allows you to run miscellaneous tasks of system maintenance: Check the the structure of the disk Repair permissions Run periodic scripts... Read more
Adobe Photoshop 21.1.0 - Professional im...
You can download Photoshop for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have purchased an earlier software version). Adobe Photoshop remains the gold standard in... Read more
Adobe Lightroom Classic 9.2 - Import, de...
You can download Lightroom for Mac as a part of Creative Cloud for only $9.99/month with Photoshop, included as part of the photography package. The latest version of Lightroom gives you all of the... Read more
Adobe InCopy 15.0.1 - Create streamlined...
InCopy is available as part of Adobe Creative Cloud for $52.99/month (or $4.99/month for InCopy app only). Adobe InCopy, ideal for large team projects involving both written copy and design work,... Read more
Adobe Illustrator 24.0.3 - Professional...
You can download Adobe Illustrator for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have also purchased an earlier software version). Adobe Illustrator for Mac is the... Read more

Latest Forum Discussions

See All

Mobile Games Starter Kit
Over here at 148Apps, we regularly dive deep into the latest and greatest mobile games hitting the App Store, but that’s not always what people are looking for when searching for a new mobile game. Some folks just want to dip their toes into... | Read more »
Unresolved is a hard-hitting narrative a...
Ghofran Akil's Unresolved in an upcoming text-based adventure game that sees you playing as a mother attempting to find her disappeared husband during the Lebanese Civil War. [Read more] | Read more »
Marvel Strike Force introduces new brawl...
FoxNext's squad-based RPG Marvel Strike Force is set to receive some fresh characters from the X-Men and Iron Man series. They'll arrive as part of the game's latest update, which follows a sizable spending boycott on the title due to complaints... | Read more »
Speed Dating for Ghosts is a narrative a...
Speed Dating for Ghosts originally released on Steam back 2018, since then it has received honourable mentions for narrative during the Independent Games Festival. Now it's made its way over to iOS devices where it's available as a premium title... | Read more »
Fast-paced multiplayer title Tennis Star...
Tennis Stars: Ultimate Clash is the latest free-to-play tennis title to hit iOS and Android. It's said to be a fairly casual experience, offering easy-to-learn controls and fast-paced, mobile-friendly matches. [Read more] | Read more »
Super Mecha Champions' latest updat...
Super Mecha Champions' latest update sees the addition of a brand new character called R.E.D. Alongside that, there's news about the current season and a series of Emojis that have been added to the game. [Read more] | Read more »
Apple Arcade: Ranked - Top 50 [Updated 2...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
Apple Arcade: Ranked - 51+ [Updated 2.19...
This is part 2 of our Apple Arcade Ranking list. To see part 1, go here. To skip to part 3, click here. 51. Mini Motorways Description: [Read more] | Read more »
Isle Escape: The House is an upcoming pu...
Isle Escape: The House is an upcoming puzzle game from Simeon Angelov that's intended to serve as an introduction to a saga they're planning on releasing in an episodic fashion. The first chapter is set to release for both iOS and Android on 29th... | Read more »
Company of Heroes, the classic RTS, is n...
Feral Interactive has finally released their highly anticipated iOS version of the strategy classic Company of Heroes. It's available now for iPad as a premium title and has had various tweaks to ensure that it's optimised for touch controls. [... | Read more »

Price Scanner via MacPrices.net

Verizon offers free iPhone 7 to customers ope...
Verizon is offering a free 32GB iPhone 7 for new or existing customers who open a new line of service, no trade-in required. Cost of the phone is credited to your account monthly over 24 months. The... Read more
Sale! 10.5″ 256GB WiFi iPad Air for $549, $10...
Amazon has new 10.5″ 256GB WiFi iPad Airs, in Space Gray, on sale today for $549 shipped. Their price is $100 off Apple’s MSRP for this model, and it’s the cheapest price available from any Apple... Read more
Back on sale! Apple’s new Mac Pro for $5499,...
B&H Photo has the base 2019 Mac Pro (3.5GHz 8-Core Xeon, 32GB RAM, 256GB SSD) in stock today and on sale for $5499 including free overnight delivery to many addresses in the US. Their price is $... Read more
B&H offers $100 discount on base 13″ 1.4G...
B&H Photo has new 2019 13″ 1.4GHz MacBook Pros on sale for $100 off Apple’s MSRP today with prices starting at $1199. Overnight shipping is free to many addresses in the US. These are the same... Read more
Apple continues to offer Certified Refurbishe...
Apple has Certified Refurbished iPhone XS models available for up to $350 off MSRP, with prices starting at $699. Each iPhone is unlocked and comes with Apple’s standard one-year warranty and a new... Read more
Apple AirPods are on sale for $30 off today
Amazon has new 2019 Apple AirPods (non-Pro models) on sale today for $30 off MSRP, starting at $129. Shipping is free: – AirPods with Wireless Charging Case: $169 $30 off MSRP – AirPods with Charging... Read more
27″ 3.7GHz 6-Core 5K iMac on sale for $2099,...
B&H Photo has the 2019 27″ 3.7GHz 6-Core 5K iMac in stock today and on sale for $200 off Apple’s MSRP. Overnight shipping is free to many locations in the US: – 27″ 3.7GHz 6-Core 5K iMac: $2099 $... Read more
Save up to $250 on a 12.9″ iPad Pros with the...
Apple has Certified Refurbished 12.9″ iPad Pros available on their online store for up to $250 off the cost of new models. Prices start at $849. Each iPad comes with a standard Apple one-year... Read more
Save up to $220 on 11″ iPad Pros with these r...
Apple has Certified Refurbished 11″ iPad Pros available on their online store for up to $220 off the cost of new models. Prices start at $679. Each iPad comes with a standard Apple one-year warranty... Read more
8-Core 27″ iMac Pro available for $4249, Cert...
Apple has Certified Refurbished 27″ 3.2GHz 8-Core iMac Pros available for $4249 including free shipping. Their price is $750 off the cost of new models. A standard Apple one-year warranty is included... Read more

Jobs Board

Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Windows/ *Apple* Technical Support Engineer...
Windows/ Apple Technical Support Engineer McLean , VA , US Apply + Be you + Be Booz Allen + Be empowered + Learn More Job Description Location: McLean, VA, US Job Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
Geek Squad *Apple* Consultation Professiona...
**762475BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 001423-San Jose-Store **Job Read more
Medical Assistant - *Apple* Valley Clinic -...
…professional, quality care to patients in the ambulatory setting at the M Health Fairview Apple Valley Clinic, located in Apple Valley, MN. Join the **M Health Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.