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


Community Search:
MacTech Search:

Software Updates via MacUpdate

Day One 2.3 - Maintain a daily journal.
Day One is the easiest and best-looking way to use a journal / diary / text-logging application for the Mac. Day One is well designed and extremely focused to encourage you to write more through... Read more
Carbon Copy Cloner 4.1.16 - Easy-to-use...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
Sketch 45 - Design app for UX/UI for iOS...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
NeoFinder 7.1 - Catalog your external me...
NeoFinder (formerly CDFinder) rapidly organizes your data, either on external or internal disks, or any other volumes. It catalogs all your data, so you stay in control of your data archive or disk... Read more
TunnelBear 3.0.15 - Subscription-based p...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
Hopper Disassembler 4.2.5- - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32-bit and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about... Read more
BetterTouchTool 2.261 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Sketch 44.1 - Design app for UX/UI for i...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
BetterTouchTool 2.260 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Chromium 59.0.3071.115 - 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 59.0.3071.115: This update has no Flash plug... Read more

Latest Forum Discussions

See All

You can now travel to Skyrim in The Elde...
The Elder Scrolls: Legends' new expansion has opened up Skyrim's craggy mountains and snowy plains for exploration today. Heroes of Skyrim is out now, adding a bunch of new Skyrim content to Bethesda's recent CCG. [Read more] | Read more »
High-stakes solitaire game 'Missile...
Missile Command and Solitaire might seem like an odd couple, but indie developer Nathan Meunier has brought them together to create his first game, Missile Cards, which launched on the App Store today. [Read more] | Read more »
Eos 2 (Music)
Eos 2 2.0.2 Device: iOS Universal Category: Music Price: $5.99, Version: 2.0.2 (iTunes) Description: | Read more »
Supercell celebrates Hay Day's comm...
Before there was Clash Royale or Clash of Clans, there was Hay Day. Now, Supercell's first game is celebrating its fifth anniversary, and the developer is commemorating the event with this touching new video. Supercell picked one long-running Hay... | Read more »
Dive into epic summer adventure with Oce...
Summer may be the best time to enjoy ocean adventures, and now you don’t even have to leave the comfort of your own home, thanks to the folks at Joycity, creators of Oceans & Empires. The old-timey naval MMO is getting a sizable new June Grand... | Read more »
Missile Cards (Games)
Missile Cards 1.0.9 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.9 (iTunes) Description: "Missile Command meets Solitaire...only with more doomlasers, death, and explosions." | Read more »
Collect mini assassins in 'Assassin...
Assassin's Creed is traveling back in time to the Spanish Inquisition for its latest mobile entry, Assassin's Creed Rebellion. The game is giving the series a look that's a huge departure from its past design, recreating classic characters in a... | Read more »
Animal Crossing is still coming to mobil...
Animal Crossing is still coming to mobile in 2017, according to aWaypointinterview with Nintendo. Announced in 2016, the game was delayed without a defined release window. However, fans of Nintendo's fantasy slice of life game won't have to wait... | Read more »
Ravenscroft 275 Piano (Music)
Ravenscroft 275 Piano 1.0.0 Device: iOS Universal Category: Music Price: $35.99, Version: 1.0.0 (iTunes) Description: Experience the splendor of a Ravenscroft Grand with the most realistic sounding piano ever created for iOS. Launch... | Read more »
This War of Mine gets a new ending and m...
This War of Mine just got a big new update, featuring free DLC that adds a new ending to the game, among other exciting changes. The update is celebrating the game's two-year release anniversary. Apart from the new ending, which will be quite... | Read more »

Price Scanner via

Will iPad Running iOS 11 Be The ‘Ute’ Of The...
Steve Jobs’ analogy comparing iPads and PCs to cars and trucks respectively is seven years old but still stimulates discussion and debate. Appearing on an All Things D panel in 2010 shortly after the... Read more
Free CarePassport App gives Patients control...
Boston based CarePassport is on a mission to enable patients to take control of their medical records by allowing patients to aggregate, store, share and manage all their medical data including... Read more
Western Digital Launches New My Passport Ultr...
Western Digital Corporation has expanded its WD brand My Passport portable drive line with the redesigned My Passport Ultra drive. In addition to a new metallic look, the drive offers intuitive WD... Read more
Clearance 2016 13-inch MacBook Pros available...
B&H Photo has clearance 2016 13″ MacBook Pros in stock today for up to $210 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 13″ 2.9GHz/512GB Touch Bar... Read more
Apple Releases iOS 11 Public Beta; How To Get...
The official release of Apple’s latest mobile operating system iOS 11 is vaguely slated for the fall, but as of June 26, ordinary users can download an iOS 11 public beta. To download the iOS 11... Read more
Extend Life of MacBook Pro Retina 2.0TB With... World Computing has announced availability of the new OWC 2.0TB Aura Pro Solid State Drive for mid-2012 to early 2013 Apple MacBook Pro with Retina display. One of the fastest... Read more
BBEdit SummerFest 2017 Discount Ends Friday,...
You can get 20% off BBEdit for a limited time in Bare Bones Software’s[UNIQID]SummerFest 2017 sale and... Read more
Use Apple’s Education discount to save up to...
Purchase a new Mac using Apple’s Education discount, and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: - 15″ 2... Read more
Clearance 27-inch 3.3GHz 5K iMac available fo...
Amazon clearance 27″ 3.3GHz 5K iMacs (MK482LL/A) available for $1799.90 including free shipping. Their price is $500 off original MSRP, and it’s the lowest price available for this model from any... Read more
13-inch 1.8GHz/256GB MacBook Air on sale for...
B&H Photo has the updated 2017 13″ 1.8GHz/256GB MacBook Air (MQD42LL/A) in stock and on sale for $1129 including free shipping plus NY & NJ tax only. Their price is $70 off MSRP. Read more

Jobs Board

*Apple* Online Store WW Customer Insights -...
…with data mining tools: R, SAS, etc.Experience with common shell scripting tools: unix, python, apple script, Swift etc. Apple Online is one of the largest and Read more
Engineering Project Manager, *Apple* Online...
…the electronic commerce (eCommerce) systems and solutions that enable and support the Apple Online Store (AOS) - one of world's largest online retail businesses, Read more
*Apple* News Product Marketing Mgr., Publish...
…organizational consensus on strategy and vision for publisher tools, authoring, and Apple News Format.Carries this strategy and vision across the organization to 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
Security Data Analyst - *Apple* Information...
…data sources need to be collected to allow Information Security to better protect Apple employees and customers from a wide range of threats.Act as the subject matter Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.