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

Bookends 12.5.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Access the power of Bookends directly from Mellel, Nisus Writer Pro, or MS Word (... Read more
Chromium 44.0.2403.125 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 44.0.2403.125: This release contains a number... Read more
iMazing 1.2.2 - Complete iOS device mana...
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
Audio Hijack 3.2.0 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
FontExplorer X Pro 5.0.1 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Calcbot 1.0.2 - Intelligent calculator a...
Calcbot is an intelligent calculator and unit converter for the rest of us. Featuring an easy-to-read history tape, expression view, intuitive conversion, and much more! Features History Tape -... Read more
MTR 5.0.0.1 - The Mac's oldest and...
MTR (was MacTheRipper)--the Mac's oldest and smartest DVD-backup app--is now updated to version 5.001 MTR -- the complete toolbox, not a one-trick, point-and-click extractor. MTR is intended for... Read more
LibreOffice 4.4.5.2 - Free, open-source...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Adobe Lightroom 6.1.1 - Import, develop,...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
File Juicer 4.41 - Extract images, video...
File Juicer is a drag-and-drop can opener and data archaeologist. Its specialty is to find and extract images, video, audio, or text from files which are hard to open in other ways. It finds and... Read more

Pac-Man Championship Edition DX has brou...
Bandai Namco has released Pac-Man Championship Edition DX on iOS and Android, which features the classic arcade gameplay that we've all grown to love. Pac-Man Championship Edition DX can be enjoyed in much shorter bursts than the arcade versions... | Read more »
Cosmonautica (Games)
Cosmonautica 1.1 Device: iOS Universal Category: Games Price: $6.99, Version: 1.1 (iTunes) Description: Cast off! Are you ready for some hilarious adventures in outer space? | Read more »
Rescue humanity from a Demon horde in An...
Angel Stone is Fincon's follow up to the massively successful Hello Hero and is out now on iOS and Android. You play as a member of The Resistance, a group of mighty human warriors who have risen up in defiance of the Demon horde threatening to... | Read more »
Gallery Doctor (Photography)
Gallery Doctor 1.0 Device: iOS iPhone Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Free up valuable iCloud and iPhone storage with Gallery Doctor, the only iPhone cleaner that automatically identifies the... | Read more »
You Against Me (Games)
You Against Me 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: A simple game… You. Me. Claim, steal, lock, score, win! | Read more »
Yep, it's True - Angry Birds 2 is O...
The not exactly rumors were true and the birds are back. Angry Birds 2 has come to the App Store and the world will... well I suppose it'll still be the same, but now we have more bird-flinging options! [Read more] | Read more »
You Could Design Your Own Card for Chain...
If you've ever wanted to create your own item, weapon, trap, or even monster for Chainsaw Warrior: Lords of the Night, this is your chance. Auroch Digital is currently holding a contest so that fans can fight to the death (not really) to see which... | Read more »
Bitcoin Billionaire is Going Back in Tim...
If you thought you managed to buy everything there is to buy in Bitcoin Billionaire and make all the money, well you though wrong. Those of you who made it far enough might remember investing in time travel - and it looks like that investment is... | Read more »
Domino Drop (Games)
Domino Drop 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Domino Drop is a delightful new puzzle game with dominos and gravity!Learn how to play it in a minute, master it day by day.Your... | Read more »
OPERATION DRACULA (Games)
OPERATION DRACULA 1.0.1 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0.1 (iTunes) Description: 25% off launch sale!!! 'Could prove to be one of the most accurate representations of the Japanese bullet hell shmup... | Read more »

Price Scanner via MacPrices.net

11-inch MacBook Airs on sale for $100 off MSR...
Best Buy has 11-inch MacBook Airs on sale for $100 off MSRP. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - 11″ 1.6GHz... Read more
iPad Air 2 on sale for up to $100 off MSRP
Best Buy has iPad Air 2s on sale for up to $100 off MSRP on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale prices available for online... Read more
Sale! 13-inch MacBook Pros on sale for $100 o...
B&H Photo has 13″ MacBook Pros on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.5GHz/500GB MacBook Pro: $999.99 save $100 - 13″ 2.7GHz/128GB Retina... Read more
Sale! Save $100 on 13-inch MacBook Airs this...
B&H Photo has the 13″ 1.6GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model.... Read more
Worldwide Tablet Market Decline Continues, Ap...
The worldwide tablet market declined -7.0% year-over-year in the second quarter of 2015 (2Q15) with shipments totaling 44.7 million units according to preliminary data from the International Data... Read more
TP-LINK TL-PA8030P KIT Powerline Featuring Ho...
Consumer and business networking products provider TP-LINK is now shipping its TL-PA8030P KIT AV1200 3-Port Gigabit Passthrough Powerline Starter Kit that expands your home’s network over its... Read more
Apple refurbished iPad Air 2s available for u...
The Apple Store has Apple Certified Refurbished iPad Air 2s available for up to $140 off the price of new models. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB... Read more
Updated Apple iPad Price Trackers
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. Read more
Apple refurbished 2014 13-inch 128GB MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ MacBook Airs available starting at $759. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.4GHz/128GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more

Jobs Board

Infrastructure Engineer - *Apple* /Mac - Hil...
Infrastructure Engineer - Apple /Mac Job Code: 1608 # of openings: 1 Description Our fortune 500 client is looking to hire an experienced Infrastructure Engineer to join Read more
Executive Administrative Assistant, *Apple*...
…supporting presentation development for senior leadership. * User experience with Apple hardware and software is preferred. Additional Requirements The following list Read more
*Apple* Bus Company is now hirin - Apple Bus...
Apple Bus Company is now hiring school bus drivers in the Pettis County area. Class B CDL preferred. Free training provided. No nights or weekends required. Flexible Read more
*Apple* Certified Mac Technician - Updated 6...
…and friendly, hands-on technical support to customers troubleshooting and repairing Apple /Mac products with courtesy, speed and skill. Use your problem-solving skills Read more
Infrastructure Engineer - *Apple* /Mac Envir...
…a part of a team Requires proven problem solving skills Preferred Additional Apple Certified System Administrator (ACSA) Apple Certified Technical Coordinator (ACTC) Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.