TweetFollow Us on Twitter

PP Documents
Volume Number:12
Issue Number:4
Column Tag:Getting Started

PowerPlant and Documents

By Dave Mark, MacTech Magazine Regular Contributing Author

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


Last month, we implemented a window containing a scrolling TextEdit view. Though you could type text in a window, there was no way of saving the text out as a file or of loading a text file into a text editing window. What’s missing here is the concept of a document. PowerPlant features a sophisticated set of document-handling classes that allow you to quickly tie a file to a window. Each file/window pairing is known as a document. Although PowerPlant does support a more complex model (multiple windows tied to a single file, for example), the most common document approach ties a single file to a single window, all controlled by the LSingleDoc class.

This month, we’re going to examine a sample application that ships with CodeWarrior. The application is called DocDemo, and it implements a simple TextEdit window that supports most standard document behaviour. That is, you can Save a document, Save As... under a new name, Open an existing document, and Print a document. DocDemo supports Apple events and is recordable. You can find DocDemo on the CodeWarrior CD. On CodeWarrior 8, it is in a folder called Document Demo.

My original goal for this month’s column was to add the LSingleDoc class to last month’s program, allowing you to save your text window as a file and open an existing file in a text window. But when I saw DocDemo, I changed my mind. DocDemo does everything I wanted to do, but also adds printing and great Apple event support. This is definitely a great learning program. Cool!

Getting Started with DocDemo

Before you go any further, you might want to find a copy of DocDemo on your CodeWarrior disk (or download it from whatever site you go to to pick up the Getting Started source code each month [such as ftp://ftp.mactech.com/pub/src/ - man]). Figure 1 shows the project window for the PowerPC version of DocDemo. Take a look at the files grouped under the name Application. The file CDocDemoApp.cp contains main() and the member functions that make up our main application class. CDocDemoApp is derived from LDocApplication, which is derived from LApplication. If you plan on building an application that supports multiple documents, CDocDemoApp.cp makes a great starting point.

(Remember, a class that starts with “L” belongs to PowerPlant. All the classes that you add to your PowerPlant programs will start with “C”.)

Figure 1. The DocDemoPPC.µ project window

Where CDocDemoApp.cp implements the application, the file CTextDoc.cp implements a single text-based document. CTextDoc is derived from LSingleDoc, which is derived from LDocument.

CDirtyText.cp implements the actual text stream, the text stored in memory that appears in one of the DocDemo windows. The word “dirty” refers to the state of a text stream, either changed since the last save (dirty) or not.

Later in the column we’ll step through each of these three source code files, pointing out the highlights. The remaining three files in the Application group are resource files. Notice that the Constructor resources are stored separately from the rest of the resources. As mentioned in a previous column, this is a good idea. When you double-click on the file DocDemo.rsrc, your favorite resource editor is launched (in this case, the creator code of DocDemo.rsrc is set to launch Resorcerer - feel free to change it to use ResEdit if that’s your preference). When you double-click on the file DocDemo.PPob, Constructor is launched.

Figure 2. The main window for DocDemo.PPob

Take some time to look through the resource files, especially the Constructor file. If you haven’t seen it yet, this would be an excellent time to check out Constructor 2.1, the version that shipped on CW8. It has a cool new look and a great new menu editor. Yup, Constructor now does menus! Figure 2 shows the main Constructor window for DocDemo.PPob. Very nice...

The main view of interest here is the one named “Text Window”. If you double-click on it, you’ll see something very similar to the scrolling text pane we created last month, with an LScroller enclosing an LTextEdit pane. Figure 3 shows the pane info window for the LTextEdit pane. Notice that the Pane ID is set to the four byte value 'Text' and that the Text ID checkbox is checked. When the Text ID checkbox is checked, the value in the Pane ID field is represented as a sequence of 4 characters (like a resource type) instead of as a long integer.

Notice also that the Class ID is set to the four byte value 'Dtxt'. This value will come into play when we register our classes in the source code. We’ll pass this value as a parameter to URegistrar::RegisterClass() in the CDocDemoApp constructor. You’ll see this in a bit, when we explore the project source code.

Figure 3. The LTextEdit pane info window for the pane

Running DocDemo

Take some time to put DocDemo through its paces. The important things to test are the ability to save and reopen text files. If you have AppleScript installed on your machine (and you should), run the Script Editor, click the Record button, then run DocDemo. While recording, create a new window, type some text, then save the document to disk. Go back to the Script Editor and click the Stop button. Figure 4 shows the results when I did this on my Mac. The line saying “make new document” was a result of selecting New from the File menu. The line following it was a result of doing a Save. Notice that the action of typing my text was not recorded. Once you’ve been through the code, see if you can figure out why this action wasn’t captured and how to make this happen.

Figure 4. A script recorded using Script Editor
while running DocDemoPPC

Here’s another interesting thing to try. You may experience an unrecoverable crash with this one, so be sure you save any open docs first! In DocDemo, open a new window, type some text, then save the document on your hard drive. Without closing the window, select Open from the File menu. Select the file you just saved (it’s already open, right?) from the SFGetFile list, then sit back and watch some exception handling kick in. Remember that option-Apple-escape forces a quit; you might end up using it. You might want to repeat this experiment with the debugger turned on.

OK, enough play. Let’s check out the source code.

CDocDemoApp.cp

You’ll notice a strong similarity between CDocDemoApp and last month’s PPTextEdit.cp file. While PPTextEdit’s application class, CPPStarterApp, was derived from LApplication, CDocDemoApp is derived from LDocApplication (LDocApplication is derived from LApplication). Here are some important things to look at as you go through the source in CDocDemoApp.cp:

• CDocDemoApp overrides OpenDocument(), MakeNewDocument(), ChooseDocument(), ObeyCommand(), and FindCommandStatus(). ObeyCommand() and FindCommandStatus() should be familiar to you from previous columns. In DocDemo, they don’t do much, since we haven’t added any commands specific to DocDemo.

• OpenDocument() gets called on an 'odoc' Apple event and opens the file specified in the incoming FSSpec. In a truly recordable application, OpenDocument() should never be called directly. When you want to do an open, you should post an 'odoc' event, which will cause OpenDocument() to get called. Remember, Apple events are what get recorded. Without the Apple event, the process of opening a document won’t be recorded. To post an 'odoc' Apple event, call LDocApplication::SendAEOpenDoc().

• MakeNewDocument() gets called in response to a kAECreateElement Apple event. When you select New fom the File menu, PowerPlant sends itself a kAECreateElement Apple event. Again, this is vital if you want your app to be recordable. To see this in action, take a look in CDocDemoApp::ObeyCommand(). Notice that cmd_New is not handled and that this causes a call of LDocApplication::ObeyCommand(). LDocApplication::ObeyCommand() sends the kAECreateElement Apple event in response to cmd_New. MakeNewDocument() uses new to create a new CTextDoc.

• Take a look at the ChooseDocument() source code:

void
CDocDemoApp::ChooseDocument()
{
 StandardFileReply macFileReply;
 SFTypeList typeList;
 
 UDesktop::Deactivate();
 typeList[0] = 'TEXT';
 ::StandardGetFile(nil, 1, typeList, &macFileReply);
 UDesktop::Activate();
 if (macFileReply.sfGood) {
 OpenDocument(&macFileReply.sfFile);
 }

There are a couple of interesting points here. First, notice that ChooseDocument() calls OpenDocument() directly. This action will now not be recordable (try it). Instead, ChooseDocument should pass macFileReply.sfFile to LDocApplication::SendAEOpenDoc().

UDesktop::Deactivate() calls Deactivate() for every window object in your app. This is needed since StandardGetFile() eats all the events as soon as it is called and your application windows never get a chance to get deactivated. If you don’t call UDesktop::Deactivate(), then when the StandardGetFile() dialog appears, your previously frontmost window will still appear in its active state (the title bar will still have stripes, for example). This is purely for aesthetics.

UDesktop::Activate() calls FrontWindow() and calls that window’s Activate(), returning things to the way they were before the call to UDesktop::Deactivate().

Note: If you have floating windows in your application, replace the file UDesktop.cp in your project window with UFloatingDesktop.cp. UFloatingDesktop.cp uses a slightly different mechanism for activate/deactivate that takes floating windows into account. This file is a little bigger and causes your built app to be a little larger, so don’t make the switch unless you use floating windows.

Take a look at the call of ::StandardGetFile() in ChooseDocument(). The two colons before the function name tell the compiler that the function is a global function. By convention, we always put two colons in front of a direct Toolbox call; this helps us discriminate between Toolbox and member function calls.

• ObeyCommand() and FindCommandStatus() don’t do much here. You’ll want to add stuff to these functions as you add commands and menus to your own applications.

• Take a look at the other member functions in LDocApplication (the ones we didn’t override). They are mostly there to handle Apple events and printing, and are definitely worth reviewing, especially if you are trying to learn how to work with Apple events.

CTextDoc.cp

CTextDoc is derived from LSingleDoc which is derived from LDocument. CTextDoc implements a single DocDemo document. Here are the highlights from the source code file:

• CTextDoc overrides IsModified(), DoAESave(), DoSave(), DoRevert(), and DoPrint().

• Take a look at the function CDocDemoApp::Open-Document():

void
CDocDemoApp::OpenDocument(
 FSSpec *inMacFSSpec)
{
 CTextDoc *theDoc = new CTextDoc(this, inMacFSSpec);
}

Notice that this code causes the CTextDoc constructor to be called. The CTextDoc constructor calls CreateWindow() to create a new window, passing it the 'PPob' resource ID 200 as a parameter. Here’s the constructor:

CTextDoc::CTextDoc(
 LCommander *inSuper,
 FSSpec *inFileSpec)
 : LSingleDoc(inSuper)
{
 // Create window for our document
 mWindow = LWindow::CreateWindow(WIND_TextDoc, this);
 
 // Specify that the text view should
 // be the Target when the Window
 // is activated
 mTextView = (CDirtyText*) mWindow->FindPaneByID('Text');
 mWindow->SetLatentSub(mTextView);
 
 if (inFileSpec == nil) {
 NameNewDoc();   // Set name of untitled window
 
 } else {
 OpenFile(*inFileSpec);   // Display contents of file in window
 }
}

The call to FindPaneByID() returns a pointer to the LTextEdit pane object. The call to SetLatentSub() tells PowerPlant that the LTextEdit pane should be the target when the window is activated. Without this call, the text edit field would not become active when the window was activated, and the text insertion cursor would not flash (or even appear) until you clicked on the text edit pane. If you go back to last month’s example, you’ll see that that is exactly what happened. Take a few minutes, open up last month’s program, and see if you can add the code that makes the text cursor blink as soon as a new window is created.

• NameNewDoc() makes use of a pair of strings to name the new document “Untitled” or “Untitled x”. If there is no window named “Untitled”, NameNewDoc() makes that the new window name. If there already is a window named “Untitled”, NameNewDoc() looks for a window named “Untitled 1”, then “Untitled 2”, etc. As soon as it finds an open slot, that becomes the name of the new window.

Here’s the code:

void
CTextDoc::NameNewDoc()
{
 // Start with the default name (“untitled”)
 Str255 name;
 ::GetIndString(name, STRx_Untitled, 1);
 
 long num = 0;
 while (UWindows::FindNamedWindow(name) != nil) {
 
 // An existing window has the current name
 // Increment counter and try again

 ::GetIndString(name, STRx_Untitled, 2);
 num++;
 Str15  numStr;
 ::NumToString(num, numStr);
 LString::AppendPStr(name, numStr);
 } 
 
 mWindow->SetDescriptor(name);
}

The first call to ::GetIndString() returns the string “Untitled”. The second call returns the string “Untitled ” (note the space at the end of the string).

The call to mWindow->SetDescriptor() sets the window’s title. Don’t be fooled. SetDescriptor() has nothing to do with Apple event descriptors. Greg used the function name SetDescriptor() any time you were setting the title of an object to a value.

• Here’s the code to CTextDoc::OpenFile():

void
CTextDoc::OpenFile(
 FSSpec &inFileSpec)
{
 Try_ {
 mFile = new LFile(inFileSpec);
 mFile->OpenDataFork(fsRdWrPerm);
 Handle textH = mFile->ReadDataFork();
 mTextView->SetTextHandle(textH);
 ::DisposeHandle(textH);
 
 mWindow->SetDescriptor(inFileSpec.name);
 mIsSpecified = true;
 }
 
 Catch_(inErr) {
 delete this;
 Throw_(inErr);
 
 } EndCatch_
}

Try_ is a macro Greg wrote to simulate exception handling before CodeWarrior supported exception handling. Now that exception handling is supported, Try_ is just defined as try and Catch_ is just defined as catch.

You will definitely want to spend some time curled up with a good book or paper on exception handling. Basically, here’s how this works. The try keyword tells the compiler to execute the block of code that follows the try. If the function throw() is called anywhere within that block (assuming there are no nested trys within the block), control is immediately transferred to the try’s matching catch block. The idea is, you can be way down in some code, encounter an error, and you jump out to the catch block attached to the code you are trying. The call to throw() is called, throwing an exception, and the catch block catches the exception. If the try code all runs without throwing an exception, the catch block is never entered.

By the way, the data member mIsSpecified indicates whether an existing file is tied to this document. If it isn‘t, and we do a Save, we need to do a StandardPutFile() to create a new file.

• IsModified() tells you whether the document is dirty (if you’ve made any changes to it since the last save):

Boolean
CTextDoc::IsModified()
{
 mIsModified = mTextView->IsDirty();
 return mIsModified;
}

mIsModified indicates whether the document is dirty. Note that in this case, whenever the pane is dirty, the document will be dirty. But what if we had two text panes, both stored in the same document? mIsModified would be based on either of the panes being dirty.

• DoAESave() gets called in response to a kAESave Apple event:

void
CTextDoc::DoAESave(
 FSSpec &inFileSpec,
 OSType inFileType)
{
 delete mFile;   // Kill existing file
 
 mFile = new LFile(inFileSpec);  // Make new file object
 
 OSType fileType = 'TEXT';// Find proper file type
 if (inFileType != fileType_Default) {
 fileType = inFileType;
 }
    // Make new file on disk
 mFile->CreateNewDataFile(Creator_DemoDoc, fileType, 0);
 mFile->OpenDataFork(fsRdWrPerm);
 DoSave();// Write out data
    // Change window name
 mWindow->SetDescriptor(inFileSpec.name);
 mIsSpecified = true;// Document now has a specified file
}

DoAESave() uses a pretty simple file-saving strategy. It deletes the existing file, then creates a brand new file and writes the text out to it. This strategy isn’t very good if your computer happens to crash between deleting the file and writing out the new contents. In that case, you lose everything. A better strategy is to create the new file first, then delete the old one. There is a tech note somewhere that tells you the exactly right (i.e., official thought police) way to do this.

• DoSave() is a utility routine that actually copies the text out to an existing file.

void
CTextDoc::DoSave()
{
 // Get text and write to file
 Handle textH = mTextView->GetTextHandle();
 StHandleLocker  theLock(textH);
 mFile->WriteDataFork(*textH, GetHandleSize(textH));
 
 mTextView->SetDirty(false);// Saving makes doc un-dirty
}

• DoRevert() reloads the text from the file into the text pane and refreshes mTextView:

void
CTextDoc::DoRevert()
{
 Handle textH = mFile->ReadDataFork();
 mTextView->SetTextHandle(textH);
 ::DisposeHandle(textH);
 mTextView->Refresh();
}

• DoPrint() does printing. We’ll talk about that in a future column:

void
CTextDoc::DoPrint()
{
 LPrintout*thePrintout =
 LPrintout::CreatePrintout(prto_TextDoc);
 thePrintout->SetPrintRecord(mPrintRecordH);
 LPlaceHolder  *textPlace = (LPlaceHolder*)
 thePrintout->FindPaneByID('TBox');
 textPlace->InstallOccupant(mTextView, atNone);
 
 thePrintout->DoPrintJob();
 delete thePrintout;
}

CDirtyText.cp

CDirtyText is derived from LTextEdit which is derived from LView. It is basically a version of LTextEdit that keeps track of whether it is dirty or not.

• CDirtyText overrides SetTextPtr() and UserChangedText().

• CDirtyText::CDirtyText() sets its dirty flag to false.

• CreateDirtyTextStream() is passed as a parameter to URegistrar::RegisterClass() (in the CDocDemoApp constructor) and is what allows us to create a CDirtyText object from a 'PPob':


CDirtyText*
CDirtyText::CreateDirtyTextStream(
 LStream*inStream)
{
 return (new CDirtyText(inStream));
}

• SetTextPtr() takes a pointer to a block of text and a length parameter and connects that block of text to this LTextEdit object:

void
CDirtyText::SetTextPtr(
 Ptr    inTextP,
 Int32  inTextLen)
{
 LTextEdit::SetTextPtr(inTextP, inTextLen);
 
 mIsDirty = false;
}

• UserChangedText() gets called whenever an action takes place on the LTextEdit view. If something has happened, if the pane is not already dirty, we have to change the menus to reflect the dirty status and flip the dirty flag. If the view is already dirty, we can’t make it any dirtier:

void
CDirtyText::UserChangedText()
{
 if (!mIsDirty) {
 SetUpdateCommandStatus(true);
 mIsDirty = true;
 }
}

• IsDirty() just returns the status of the dirty flag.

• SetDirty() sets the dirty flag.

Till Next Month...

DocDemo is one of the most interesting PowerPlant examples I’ve seen. It is incredibly rich without being too difficult to understand. There are a bunch of ways you can extend this app, so take some time and start playing. Try adding a few menus to the DocDemo. Use Constructor to change the word-wrapping of the LTextEdit field. Try to change the font, style, and color of the text displayed in each document. I’ll see you next month...


 

Community Search:
MacTech Search:

Software Updates via MacUpdate

5 slither.io mash-ups we'd love to...
If there's one thing that slither.io has proved, it's that the addictive gameplay of Agar.io can be transplanted onto basically anything and it will still be good fun. It wouldn't be surprising if we saw other developers jumping on the bandwagon,... | Read more »
How to navigate the terrain in Sky Charm...
Sky Charms is a whimsical match-'em up adventure that uses creative level design to really ramp up the difficulty. [Read more] | Read more »
Victorious Knight (Games)
Victorious Knight 1.3 Device: iOS Universal Category: Games Price: $1.99, Version: 1.3 (iTunes) Description: New challenges awaits you! Experience fresh RPG experience with a unique combat mechanic, packed with high quality 3D... | Read more »
Agent Gumball - Roguelike Spy Game (Gam...
Agent Gumball - Roguelike Spy Game 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Someone’s been spying on Gumball. What the what?! Two can play at that game! GO UNDERCOVERSneak past enemy... | Read more »
Runaway Toad (Games)
Runaway Toad 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It ain’t easy bein’ green! Tap, hold, and swipe to help Toad hop to safety in this gorgeous new action game from the creators of... | Read more »
PsyCard (Games)
PsyCard 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: From the makers och Card City Nights, Progress To 100 and Ittle Dew PSYCARD is a minesweeper-like game set in a cozy cyberpunk... | Read more »
Sago Mini Robot Party (Education)
Sago Mini Robot Party 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: -- Children's Technology Review Editor's Choice -- | Read more »
How to get a high score in every level o...
Sky Charms is an adorable match three puzzler that provides a decent challenge thanks to its creative level design. It regularly presents something new, forcing you to think on your feet. [Read more] | Read more »
Apestorm: Full Bananas (Games)
Apestorm: Full Bananas 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: ***Launch sale – limited time only!*** Fugitive Apes have taken to the skies in search of revenge after humans have... | Read more »
How to create bigger words in Spellspire
Words have power. At least they do in Spellspire,a game about blasting out magical attacks by making words out of a jumble of letters. And it's a lot of fun. But if you want to be the best, you're going to have to think tactically when you start... | Read more »

Price Scanner via MacPrices.net

Aleratec Releases Mac Software Upgrade for 1...
California based Aleratec Inc., designer, developer and manufacturer of Portable Device Management (PDM) charge/sync products for mobile devices and professional-grade duplicators for hard disk... Read more
Sale! Amazon offers 27-inch iMac, 13-inch 2.9...
Amazon has the 27″ 3.2GHz 5K iMac and the 13″ 3.9GHz Retina MacBook Pro on sale for $300 off MSRP, each including free shipping, for a limited time: - 27″ 3.2GHz/1TB HD 5K iMac (model MK462LL/A): $... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
13-inch 2.7GHz/128GB Retina MacBook Pro on sa...
Take $200 off MSRP on the price of a new 13″ 2.7GHz/128GB Retina MacBook Pro (model MF839LL/A) at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1099.99 $200 off MSRP Act now if... Read more
Apple refurbished clearance 15-inch Retina Ma...
Apple has Certified Refurbished 2014 15″ 2.2GHz Retina MacBook Pros available for $1609, $390 off original MSRP. Apple’s one-year warranty is included, and shipping is free. They have refurbished 15... Read more
27-inch 5K iMacs on sale for up to $150 off M...
B&H Photo has 27″ 5K iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2199 $100 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1849.99 $150... Read more
What Does The Refreshed 12-Inch MacBook Tell...
A lot of commentators are complaining that Apple’s update of the 12-Inch MacBook last week is a bit of a damp squib. I don’t know what they were expecting, since it would be very unlike Apple to do a... Read more
Free Wittify Keyboard Now Available On The Ap...
A team of Harvard Business School students have announced that the Wittify Keyboard, a new app utility for iOS devices, is now available on the Apple App Store. The Wittify keyboard and application... Read more
Apple Reports First Year-Over-Year Quarterly...
Apple on TUesday announced financial results for its fiscal 2016 second quarter ending March 26, 2016. The Company posted quarterly revenue of $50.6 billion and quarterly net income of $10.5 billion... Read more
13-inch 2.7GHz Retina MacBook Pros on sale fo...
Take $130-$150 off MSRP on the price of a new 13″ 2.7GHz Retina MacBook Pro at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1169 $130 off MSRP - 13″ 2.7GHz/256GB Retina MacBook... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 48260200 Phoenix, Arizona, United States Posted: Apr. 22, 2016 Weekly Hours: 40.00 **Job Summary** As an Apple Solutions Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the largest premier retailer of Apple products in the nation. In order to support our growing customer base, we are currently looking for a driven Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.