TweetFollow Us on Twitter

Aug 01 PowerPlant Workshop

Volume Number: 17 (2001)
Issue Number: 08
Column Tag: PowerPlant Workshop

Basic Dialogs

by Aaron Montgomery

How one goes about writing a PowerPlant application

These Articles

This is the fifth article in a series of articles about Metrowerks' PowerPlant application framework. The first article introduced how the framework deals with commands, the second article discussed the debugging facilities of the framework, the third introduced windows, and the fourth article tacked file classes. This article completes the discussion of the core of PowerPlant by discussing the way PowerPlant handles dialogs. This series assumes familiarity with the C++ language, the Macintosh Toolbox API and the CodeWarrior IDE. The articles were written using CodeWarrior 6 with the net-update to IDE and no other modifications. Throughout this and future articles, I will assume that you are using the class browser and the debugger to explore the PowerPlant code more fully.

Broadcasters and Listeners

We have talked about the command chain that PowerPlant uses to convert menu selections to code calls, but trying to pass all of the user interaction with a dialog box through this chain would be cumbersome. Fortunately, PowerPlant offers an alternative method of linking different classes together through its LBroadcaster and LListener classes. Each LBroadcaster object keeps a list of LListeners and can broadcast a message to the objects in its list. The broadcast is done by calling each LListener's ListenToMessage() method. This method takes two parameters. The first, of type MessageT, describes the message being broadcast. The second, of type void*, allows the LBroadcaster object to pass message specific data to the LListener object.

Although this article focuses dialogs, the LBroadcaster and LListener classes can also be used in other places. For example, the LGrowZone class (mentioned in the second article) broadcasts a message when it needs more memory. If you have a class that can release memory in a pinch, you might want to make it an LListener and register it with the LGrowZone object.

In the case of dialogs, the control classes are LBroadcasters and will broadcast their message whenever they are adjusted. This means that if you want something to happen when a control is adjusted, you can create an LListener and have it listen to that control. This means that much of the code for dynamic effects in dialogs can be placed in separate classes and linked to the dialog before it is presented to the user.


Before looking at the resource file, you may want to run HTMLedit and play with the controls in the dialog (select Preferences... from the Edit menu). Now go to the IDE and double-click the AppResources.ppob file (which should open in Constructor).

The Preferences dialog has two LPushButtons (OK and Cancel), an LMultiPanelView (where everything important happens) and an LTabsControl (to switch between the panels). The two LPushButtons did not require much set up, but you need to remember to let the LGADialog know the button IDs for the default and cancel buttons. The LTabsControl needs to have a valid Value Message. I set the value to SwPa for Switch Panel. This is the message that will be broadcast when someone clicks on the control. The LTabsControl needs to have an associated tab# resource which determines the titles of the tabs (as well as icons, if any are used on the tabs). Unfortunately, I do not think the tab# resource can be edited in Constructor. You have two choices: add it to the AppResources.rsrc file or open the AppResources.ppob file in Resourcerer or ResEdit. If you choose to keep the tab# resource in the AppResources.rsrc file, you will not see the tab names in Constructor. Because I like to see these while working on the dialog, I added the tab# resource to the AppResources.ppob file with Resourcerer.

Now to the centerpiece of the dialog: the LMultiPanelView. To add panels to a LMultiPanelView in Constructor, you select the Panels cell in the Property Inspector window and then select New Panel from the Edit menu. In this case, there are three (one for each tab). You then select which PPob resource to associate with each panel. In our case, we use resources with IDs 10031, 10032 and 10033. The final settings which need to be made for this resource are the setting of the Switch Message (it should match with the LTabsControl) and selecting the Listen To SuperView checkbox. The LMultiPanelView is an LListener and when it hears the Switch Message, it will switch to another panel. Selecting the Listen To SuperView checkbox adds the LMultiPanelView object as a listener to the LTabsControl object.

Now it is time to construct the three views that will appear in the LMultiPanelView. The first is used for determining the file creator of saved files. This LView was created by dragging an LView from the Catalog window into the AppResources.ppob window and then changing its Resource ID to 10031. The size of the panel needs to be adjusted to fit inside the LMultiPanelView. The Visible checkbox needs to be deselected (otherwise, all of the LViews will appear at once in the LMultiPanelView). The primary control here is a LRadioGroupView and four LRadioButtons. Since there is no need for the buttons to broadcast a message when they are hit, they do not need Value Messages. However, since the code will need to know which button is selected, the Pane IDs need to be set. The Pane IDs match the appropriate creator code for each application. Notice that there is an older LRadioGroup in the Other tab of the catalog. This has been replaced by the LRadioGroupView in the Views tab.

The second LView (Resource ID 10032) used in the LMultiPanelView is very simple and straightforward. One way to save a little work is to duplicate the LView with Resource ID 10031, renumbered it to 10032 and then deleted all of the controls. This means that the new resource will be the correct size and visibility. This LView has an LStaticText and an LEditText. The LEditText is given a Pane ID because we will need to be able to access its contents from the code. The LEditText is from the Appearance tab and replaces the LEditField in the Panes tab.

The third LView (Resource ID 10033) is the most complicated. Again, creation is done by duplicating the LView with Resource ID 10031, changing the Resource ID, deleting all the existing controls and adding new ones. It has an LPopupButton and an LMultiPanelView. The Message Value for the LPopupButton is SwPa for Switch Panel. The MENU Resource ID is set to 1002 (you can find this resource in the AppResources.ppob file as well). The LMultiPanelView uses Resource IDs 10034 and 10035. The Switch Message is set to SwPa so that it is consistent with the LPopupButton. Unlike the first LMultiPanelView, this one cannot simply listen to its SuperView and we will examine the code needed to link the LPopupButton to the LMultiPanelView below. Resources 10034 and 10035 are very basic, consisting of some LCheckboxes and LStaticTexts. The LCheckboxes have had their Message Values set because the code will need to listen for their broadcasts.

This concludes our tour of the AppResources.ppob file and we now turn our attention to the source code. As you build your interface, if you cannot find a control by browsing through the Catalog window, ask on the comp.sys.mac.oop.powerplant newsgroup. Usually someone will be able to tell you where it is in the Catalog, suggest a class from the PowerPlant Archive (at Metrowerks' web site), or provide a work around.

Preference Class

The CPreferences class handles the application's preferences. The class consists of a constructor; a destructor; a method to register used classes; a method to set the preferences via a dialog; and a method to alert other classes about a change in preferences. We begin with the constructor.

CPreferences() in CPreferences.cp
:   myFile(StringLiteral_("HTMLedit Prefs"))
      StNewResource thePrefs(ResType_Pref,
         SPreferences* thePrefsP
                                 = reinterpret_cast<SPreferences*>(
         thePrefsP->FileType = OSType_Default_Creator;
         thePrefsP->Marker = char_Default_Marker;
                           = bool_Default_LinkUsesTarget;
         thePrefsP->ImageUsesAlt = bool_Default_ImageUsesAlt;
                           = bool_Default_ImageUsesBorder;
         thePrefs.SetResAttrs(resLocked + resPreload);

   myPrefsH = reinterpret_cast<SPreferences**>(
                        ::Get1Resource(ResType_Pref, ResIDT_Pref));
   if (myPrefsH == nil)


The data member myFile is of type LPreferencesFile. This class is provided by PowerPlant to create preference files in the System folder. In this case, the code names the preference file HTMLedit Prefs and then opens the resource fork (creating it if needed).

The StNewResource class will attempt to open the specified resource and if it does not exist, it will create the resource. The ResourceExisted() method of that class will return false if the resource is new and in this case, the code fills the resource with the default preferences. The code also sets the resource attributes to preload and lock the resource since we will want to have it available at all times. The resource structure is small and so it is unlikely to cause an undue memory burden here. When the StNewResource passes out of scope, the resource will be written into the preference file.

Next the code loads the resource and then passes all of the preferences to those classes using them. I've decided to use a raw resource as a data member instead of using a StResource. This means that the code needs to call ::ReleaseResource() in CPreferences' destructor. I felt that there was no need to use a stack class to handle memory management because the resource will be loaded until the application quits. If you are going to add a resource data member to a class in other situations, you should consider using the StResource class instead of a raw resource.

The most interesting method in the CPreferences class is the Set() method which runs the dialog. We present the code for this method now.

Set() from CPreferences.cp
void CDocumentApp::CPreferences::Set()
   StDialogHandler      theHandler(PPob_Prefs,

   LWindow*         theWindowP = theHandler.GetDialog();
   LMultiPanelView*   theMPViewP = FindPaneByID_(theWindowP,

   LRadioGroupView*   theRadioGroupP =
            PPob_Prefs_FileType, LRadioGroupView);

   LEditText*         theFieldP = FindPaneByID_(theWindowP,
   LStr255            theMarker = (**myPrefsH).Marker;
   theMPViewP = FindPaneByID_(theWindowP,
                           PPob_Prefs_MPV2, LMultiPanelView);
   LPopupButton*      thePopupP = FindPaneByID_(theWindowP,

   LCheckBox*         theCheckBoxP = FindPaneByID_(theWindowP,
   LStaticText*      theStaticTextP = FindPaneByID_(theWindowP,

   CDynamicLinkText   theDynamicLinkText(theStaticTextP,
//omitted code setting up other panel
   while (true)
      MessageT theMessage = theHandler.DoDialog();
      if (theMessage == msg_Cancel)
      else if (theMessage == msg_OK)
   (**myPrefsH).FileType =
   theFieldP = FindPaneByID_(theWindowP,
                           PPob_Prefs_Marker, LEditText);
   (**myPrefsH).Marker = theMarker[1];

//omitted code updating preferences handle

Although it looks like a lot of code, there are only four basic steps. First, set the values of the controls based on the current preferences. Second, set up the dynamic text. Third, run the dialog box. Fourth, update the preferences based on the user interaction.

The StDialogHandler class was introduced in the third article and one is used here. The first parameter is the Resource ID of the dialog and the second parameter is the super commander of the dialog. Since we will need to adjust some of the user interface before presenting the dialog to the user, we use the GetDialog() method to obtain the dialog window. We now look at the interesting bits of the code.

The call to CreateAllPanels() is important because we will want to access the panels prior to user interaction. If you do not call this, the panels of the LMultiPanelView will be created as the user switches from one panel to another. If the panels were completely static, this approach would be appropriate. Because we are going to adjust each panel before presenting it to the user, it is easiest to adjust everything before starting to interact with the user.

The next call that is new is the call to AddListener(). This call links the LPopupButton in the third panel to the LMultiPanelView in the third panel. Both the LTabsControl class and the LPopupButton class pass the tab or item number chosen as the void* parameter in their call to ListenToMessage(). This is exactly what the LMultiPanelView class expects and so there is no need for any additional code to make the LMultiPanelView objects work.

The line creating a CDynamicLinkText object will be explained below. What is convenient is that in this code, simply the creation of these objects is all that is necessary to generate dynamic effects in the dialog. The actual code to do that work does not need to clutter up the code handling the user interaction with the dialog.

Next we show the window and let the StDialogHandler object run the dialog. The return value from DoDialog() will be the last message broadcast by an LBroadcaster in the dialog box (the StDialogHandler is an LListener that listens to the controls in the dialog). The only two messages we need to concern ourselves with are the msg_Cancel and msg_OK, all the other messages are handled by other LListener objects. The remainder of the code is straightforward, we obtain the values from the dialog and update the preferences.

We will not discuss the Update() method but its code is straight forward (calling a number of methods to update the user preferences in those classes that use them). We now turn our attention to the CDynamicLinkText and CDynamicImageText classes.

CDynamicLinkText & CDynamicImageText

These two classes are responsible for dynamically updating LStaticText objects in the dialog as the user checks and unchecks LCheckBox controls in the dialog. The two classes are almost identical and we present CDynamicLinkText here. The code is below is presented as a testament to the ease with which these effects can be accomplished with PowerPlant. Other than the code to generate the actual text to be displayed, there are under 10 lines of code in the entire class.

CDynamicLinkText code from CDynamicText.cp
         LStaticText* inTextP, LCheckBox* inUseTargetP)
:   myTextP(inTextP),

void CDynamicLinkText::ListenToMessage(
         MessageT inMessage, void* ioParam)
   ioParam = ioParam;
   if (inMessage == msg_ToggleTarget) { SetText(); }

void CDynamicLinkText::SetText()
      LStr255 theTag = "";
      theTag += "<A href=\””;
      theTag += ‘•’;
      theTag += “\””;
      if (myUseTargetP->GetValue())
         theTag += “ target=\””;
         theTag += ‘•’;
         theTag += “\””;
      theTag += “>”;
      theTag += ‘•’;
      theTag += “</A>”;
      theTag += ‘•';

CDynamicLinkText is an LListener and its primary method is the ListenToMessage() method. Its constructor accepts a pointer to an LCheckbox and a pointer to an LStaticText. When the LCheckbox object is clicked by the user, it will broadcast a message. The CDynamicLinkText object will receive this message and update the LStaticText object to reflect the current settings.

Other Classes

Changes needed to be made to the CDocumentApp class, CHTMLTextView class and the CTextDocument class in order use these preferences. CDocumentApp now handles the cmd_Preferences (and passes all of the work off to a static CPreferences data member). CHTMLTextView and CTextDocument now hold static data members for holding user preferences as well as methods to set and get this data. If you want to view the actual changes yourself, search the files CDocumentApp.cp, CHTMLTextView.cp and CTextDocument.cp for comments starting with //•.

Concluding Remarks

I haven't covered every useful control that can be placed in a dialog box but should have given you a feel for how to use Constructor to build the interface and the necessary code to run the interface. You may have noticed that this article is somewhat shorter than previous articles. The primary reason is that much of the code for this article has been used in previous articles (in slightly other contexts). At this point, I believe I have presented you with the tools to build a basic Macintosh application using PowerPlant (and covered most of The PowerPlant Book topics in the process). I'm planning on taking a month hiatus but returning in October. If you have a topic that you would like to see, please send me an e-mail.

PowerPlant References

For more on using the messaging system built into PowerPlant, you will want to read The PowerPlant Book chapter "Controls and Messaging." There is also a "Dialogs" chapter in The PowerPlant Book that covers (not surprisingly) dialogs. Another source of information is the source code of PowerPlant as well as the example files. I have found the Appearance Demo and the Grayscale Sample to be particularly useful as they present a variety of different controls. You can also see more examples of dialogs in the StdDialogs demo.

Aaron teaches in the Mathematics Department at Central Washington University in Ellensburg, WA. Outside of his job, he spends time riding his mountain bike, watching movies and entertaining his wife and two sons. You can email him at, try to catch his attention in the newsgroup comp.sys.mac.oop.powerplant or visit his web site at

Apple Inc.
Microsoft Corpora
Google Inc.

MacTech Search:
Community Search:

Software Updates via MacUpdate

Airfoil 4.8.9 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
WhatRoute 1.13.0 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the... Read more
Chromium 37.0.2062.122 - 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. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Attachment Tamer 3.1.14b9 - Take control...
Attachment Tamer gives you control over attachment handling in Apple Mail. It fixes the most annoying Apple Mail flaws, ensures compatibility with other email software, and allows you to set up how... Read more
Duplicate Annihilator 5.0 - Find and del...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator detects... Read more
jAlbum Pro 12.2 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more
jAlbum 12.2 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results Simply drag and drop photos into groups, choose a design... Read more
Quicken 2015 2.0.4 - Complete personal f...
Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial transactions,... Read more
iMazing 1.0 - Complete iOS device manage...
iMazing (formerly 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... Read more
Xcode 6.0.1 - Integrated development env...
Apple Xcode is Apple Computer's integrated development environment (IDE) for OS X. The full Xcode package is free to ADC members and includes all the tools you need to create, debug, and optimize... Read more

Latest Forum Discussions

See All

View Source – HTML, JavaScript and CSS...
View Source – HTML, JavaScript and CSS 1.0 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0 (iTunes) Description: View Source is an app plus an iOS 8 Safari extension that makes it easy to do one key web developer... | Read more »
Avenged Sevenfold’s Hail To The King: De...
Avenged Sevenfold’s Hail To The King: Deathbat is Coming to iOS on October 16th Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Just in time for Halloween, on October 16 Avenged Sevenfold will be launching | Read more »
Talisman Has Gone Universal – Can Now be...
Talisman Has Gone Universal – Can Now be Played on the iPhone Posted by Jessica Fisher on September 19th, 2014 [ permalink ] | Read more »
Tap Army Review
Tap Army Review By Jennifer Allen on September 19th, 2014 Our Rating: :: SHOOT EM ALLUniversal App - Designed for iPhone and iPad Mindless but fun, Tap Army is a lane-based shooter that should help you relieve some stress.   | Read more »
Monsters! Volcanoes! Loot! Epic Island f...
Monsters! Volcanoes! Loot! | Read more »
Plunder Pirates: Tips, Tricks, Strategie...
Ahoy There, Seadogs: Interested in knowing our thoughts on all this plundering and pirating? Check out our Plunder Pirates Review! Have you just downloaded the rather enjoyable pirate-em-up Plunder Pirates and are in need of some assistance? Never... | Read more »
Goat Simulator Review
Goat Simulator Review By Lee Hamlet on September 19th, 2014 Our Rating: :: THE GRUFFEST OF BILLY GOATSUniversal App - Designed for iPhone and iPad Unleash chaos as a grumpy goat in this humorous but short-lived casual game.   | Read more »
A New and Improved Wunderlist is Here fo...
A New and Improved Wunderlist is Here for iOS 8 Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Evernote Update for iOS 8 Adds Web Clipp...
Evernote Update for iOS 8 Adds Web Clipping, Quick Notes, and More Posted by Ellis Spice on September 19th, 2014 [ permalink ] | Read more »
Apple Names Ultimate Productivity Bundl...
Apple Names Ultimate Productivity Bundle by Readdle as the Essential Bundle on the App Store Posted by Jessica Fisher on September 19th, 2014 [ permalink | Read more »

Price Scanner via

Updated Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Mac Pros available for up to $260 off MSRP
Adorama has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 4-core Mac Pro: $2839.99, $160 off MSRP - 6-core Mac Pro: $3739.99, $260... Read more
13-inch 2.6GHz/256GB Retina MacBook Pros avai...
B&H Photo has the 13″ 2.6GHz/256GB Retina MacBook Pro on sale for $1379 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
Previous-generation 15-inch 2.0GHz Retina Mac...
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
21″ 2.7GHz iMac available for $1179, save $12...
Adorama has 21″ 2.7GHz Hawell iMacs on sale for $1179.99 including free shipping. Their price is $120 off MSRP. NY and NJ sales tax only. Read more
iOS 8 Adoption Rate Slower than iOS 7, 6, Hit...
Apple began pushing out iOS 8 updates to eligible devices around 1pm ET on September 17, 2014. However, unlike with iOS 7, which boasted a wide variety of differences from its predecessor iOS 6, in... Read more
LIkely Final Definitive OS X 10.9.5 Mavericks...
Apple has released what will almost certainly be the last incremental version number update of OS X 10.9 Mavericks (save for futire security updates) before OS X 10.10 Yosemite is released next month... Read more
Fingerprints, Apple Pay and Identity Theft Wa...
On Sep 9th, CEO Tim Cook unveiled Apple Pay, along with the new iPhone 6 and iWatch. Apple Pay is a newly developed technology that utilizes a near field communication (NFC) to enable customer... Read more
Amazon Introduces Two All-New Kindles
Amazon on Thursday introduced the 7th generation of its Kindle dedicated e-reader device: Kindle Voyage, its top-of-the-line e-reader, and the new $79 Kindle, with a 20% faster processor, twice the... Read more
Save up to $300 on the price of a new Mac wit...
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

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.