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

macOS Catalina 10.15.7 - An Operating Sy...
macOS Catalina gives you more of everything you love about Mac. Experience three all-new media apps: Apple Music, Apple TV, and Apple Podcasts. Locate a missing Mac with the new Find My app. And now... Read more
BlueStacks 4.230.10 - Run Android applic...
BlueStacks App Player lets you run your Android apps fast and fullscreen on your Mac. Feature comparison chart How to install Bluestacks on your Mac Go to MacUpdate and click the green "Download"... Read more
Kodi 18.8 - Powerful media center tool f...
Kodi (was XBMC) is an award-winning free and open-source (GPL) software media player and entertainment hub that can be installed on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user... Read more
Wireshark 3.2.7 - Network protocol analy...
Wireshark is one of the world's foremost network protocol analyzers, and is the standard in many parts of the industry. It is the continuation of a project that started in 1998. Hundreds of... Read more
Fantastical 3.2 - Create calendar events...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Mindjet MindManager 13.2.132 - Professio...
MindManager is a powerful mind mapping tool that increases your productivity. From business plans or developing a new website, its robust mind maps have all the features you need to accomplish your... Read more
Tweetbot 3.4.3 - Popular Twitter client.
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
OmniPlan 4.0.2 - Professional-grade proj...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Numbers 10.2 - Apple's spreadsheet...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
A Better Finder Attributes 6.25 - Change...
A Better Finder Attributes 6 allows you to change JPEG & RAW shooting dates, JPEG EXIF meta-data tags, file creation & modification dates, file flags and deal with invisible files. Correct... Read more

Latest Forum Discussions

See All

BTS Universe Story, the social game that...
Netmarble's highly anticipated social game, BTS Universe Story, is available now for iOS and Android. It's the second collaboration between the hugely successful mobile developer and the K-pop superstars following BTS World. [Read more] | Read more »
The 5 Best Mobile Games Like Hades
Supergiant Games finally released Hades upon the world this week, and we’re loving it. The game plays to all of the studio’s strengths while still retaining a strong sense of identity. It also just so happens to play rather well using the Steam... | Read more »
A Year of Apple Arcade: The Good, The Ba...
Apple Arcade has persisted for just over a year at this point, and although that means I've been busy ranking and re-ranking every game on the service for just about as long, I haven't done much reflection on the service as a whole. [Read more] | Read more »
Animal Restaurant anniversary event team...
Animal idle simulator Animal Restaurant is celebrating its first-year anniversary with a crossover event with popular YouTube series Aaron’s Animals. [Read more] | Read more »
Raziel: Dungeon Arena is a hack 'n...
Raziel: Dungeon Arena is available now on mobile and will appeal to fans of both comic books and old school dungeon crawlers. Not only will you hack 'n' slash your way through mobs of enemies but there's also fully-narrated animated comic to enjoy... | Read more »
Steam Link Spotlight - Hades
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was on Disco Elysium. Read about how it plays using Steam Link over here. | Read more »
Microsoft has acquired ZeniMax Media and...
In the latest of a series of blockbuster moves, Microsoft has now acquired Zenimax Media and its subsidiary, Bethesda Softworks, for $7.5 billion. [Read more] | Read more »
Infinity Mechs is an upcoming idle game...
Indie developer SkullStar studio has announced an upcoming idle mech game called Infinity Mechs. It draws inspiration from the mobile game Iron Saga and has been officially licensed by Game Duchy. It's set to launch for both iOS and Android on... | Read more »
PUBG Mobile Lite's latest update se...
PUBG Mobile Lite, the streamlined version of the popular battle royale that's designed to work on less powerful devices, sees the return of a popular game variant today, Survive Till Dawn mode. It arrives as part of the 0.19.0 content update. [... | Read more »
Matchy Catch, Jyamma Games’ new hyper-ca...
Matchy Catch is a new hyper-casual puzzler from Jyamma Games, the Italian studio behind the Pong-inspired puzzle-adventure Hi-Ball Rush. It’s only the developer’s second game for iOS and Android devices, but it promises to be every bit as fun and... | Read more »

Price Scanner via

Lowest price anywhere: New 13″ 2.0GHz MacBook...
Amazon has new 2020 13″ 2.0GHz/512GB MacBook Pros with 10th generation Intel processors back in stock on sale today for $200 off Apple’s MSRP. Shipping is free. Be sure to purchase the MacBook Pro... Read more
Apple Pro Display XDR with Nano-Texture Glass...
Amazon Apple Premier Partner GatorTec has the Apple Pro Display XDR with Nano-Texture Glass on sale for $5599 shipped, on Amazon. Their price is $400 off Apple’s MSRP, and it’s the cheapest price... Read more
Get a 2019 13″ MacBook Air for only $779 toda...
Apple has clearance, Certified Refurbished, 2019 13″ 1.6GHz/128GB MacBook Airs available again for $779. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is... Read more
2020 11″ iPad Pros on sale today for $50-$75...
Apple reseller Expercom has new 2020 11″ Apple iPad Pros on sale for $50-$75 off MSRP, with prices starting at $749. These are the same iPad Pros sold by Apple in their retail and online stores: – 11... Read more
Apple has restocked 2020 13″ MacBook Airs sta...
Apple has restocked Certified Refurbished 2020 13″ MacBook Airs starting at only $849 and up to $200 off the cost of new Airs. Each MacBook features a new outer case, comes with a standard Apple one-... Read more
Apple’s new 8th generation 10.2″ iPads are on...
Amazon is discounting new 2020 8th generation 10.2″ Apple iPads by up to $35 off MSRP with prices starting at only $299. Shipping is free. These are the same iPads sold by Apple in their retail and... Read more
Today on Woot: Apple refurbished 16″ MacBook...
Amazon-owned Woot has Apple refurbished 16″ MacBook Pros available today for up to $605 off the cost of new models. Shipping is free for Prime members: – 16″ 6-Core MacBook Pros: $1874.99 $525 off... Read more
Apple offers last year’s iMacs for as little...
Apple has dropped prices on last year’s 21″ iMacs, Certified Refurbished, by up to $240 off the original cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Get last year’s 32GB iPad for only $279 today...
Amazon has dropped prices on clearance 2019 Silver 32GB WiFi Apple iPads by $50 to $279 shipped. That’s the cheapest price available for a new 10.2″ iPad from any Apple reseller. Act now if you’re... Read more
New Apple Watch Series 6 and SE models now on...
Amazon is the first Apple reseller to offer the new Apple Watch Series 6 and Apple Watch SE models at discounted sale prices. These are the same Watches sold by Apple in their retail and online... Read more

Jobs Board

Security Officer ($23.00/Hourly) - *Apple*...
**Security Officer \($23\.00/Hourly\) \- Apple Store** **Description** About NMS Built on a culture of safety and integrity, NMSdelivers award\-winning, integrated Read more
*Apple* Certified Macintosh Technician - Exc...
Apple Certified Macintosh Technician Summary Title: Apple Certified Macintosh Technician ID:350 Department:All Location:Falls Church, VA Description Apple Read more
Department Manager- Tech Shop/ *Apple* Stor...
…their parents want, and our faculty needs. As a Department Manager in our Tech Shop/ Apple Store you will spend the majority of your time on the sales floor engaging Read more
Security Officer ($23.00/Hourly) - *Apple*...
**Security Officer \($23\.00/Hourly\) \- Apple Store** **Description** About NMS Built on a culture of safety and integrity, NMSdelivers award\-winning, integrated Read more
Product Manager, *Apple* Commercial Sales -...
Product Manager, Apple Commercial Sales Austin, TX, US Requisition Number:77652 As an Apple Product Manager for the Commercial Sales team at Insight, you Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.