All DatabasesMacTech Vol 11-1995
PowerPlant
Volume Number: 11
Issue Number: 9
Column Tag: Getting Started
PowerPlant
By Dave Mark, MacTech Magazine Regular Contributing Author
Note: Source code files accompanying article are located on MacTech CD-ROM or
source code disks.
This month, we’re going to take a look at PowerPlant, the framework included on every
CodeWarrior CD. If you own Symantec C++, take heart: we’ll get to the TCL in a future
column. In the meantime, follow along anyway. Who knows, you might find yourself
making the switch to PowerPlant someday.
This Month’s Program
I don’t know about you but, after four month’s straight of menus, I’m ready for
something else. So instead of talking about PowerPlant and menu handling (we’ll do
that in a future column), this month’s program will introduce PowerPlant’s
messaging system.
As you design your PowerPlant programs, you’ll work with objects called
broadcasters and listeners. A broadcaster sends a message and a listener receives that
message. In this month’s program, we’ll create a window containing a button. Each
time the button is clicked, it will send a message to any objects registered as listeners
to it. Basically, this means that the broadcasting objects’ BroadcastMessage()
member function calls the listening object’s ListenToMessage() member function.
This mechanism is simpler than it sounds. As we build our project, just
remember that the button is a broadcaster, and that the class CDashboardApp will be
the listener.
If you have the CW6 documentation, you might want to read the section named
LBroadcaster & LListener in the PowerPlant manual (chapter 8, page 93).
As is usually the case when working with a framework, we’ll take an existing
PowerPlant example and modify it to suit our needs.
• Duplicate the folder “CodeWarrior6:Metrowerks PowerPlant:More PowerPlant
Examples:Dashboard Starter”.
If you run one of the projects in this folder (either Dashboard68K.µ or
DashboardPPC.µ), you’ll see the window shown in Figure 1. To quit the program,
select Quit from the File menu. As you can see, Quit is the only item in the File
menu. In a future column, we’ll add some menus and items to a PowerPlant program.
For now, let’s add a button to the Dashboard window.
Figure 1. The Dashboard Starter window, before our modifications.
Editing Dashboard.PPob
CodeWarrior comes with a ResEdit-like program, named Contructor, that lets you
create and edit PowerPlant-specific resources. The resource we’re interested in in
this column is the PPob resource. A PPob resource is like a combination of a DLOG and
DITL, but for any PowerPlant view including windows and dialogs. We’ll use
Constructor to add a button to the Dashboard window.
CodeWarrior 6 ships with two different versions of Constructor. Though both
will do the job, Constructor 2.0a16 is far newer than Constructor 1.0.1 and seems
pretty stable for an alpha release. The screen shots and instructions in this column
were all based on 2.0a16. You’ll find both versions in the CodeWarrior 6 folder,
inside the Metrowerks PowerPlant subfolder.
• Launch Constructor 2.0a16 and open the file Dashboard.PPob (it’s in the same
folder as the two Dashboard project files).
As you can see by the Constructor window shown in Figure 2, the file
Dashboard.PPob already contains a resource. This PPob resource represents the main
Dashboard window. It has a resource ID of 200 and represents an object belonging to
the class LWindow.
Figure 2. The Constructor window listing the view resources in Dashboard.PPob.
Our next step is to edit this PPob resource.
• Double-click on the LWindow PPob with an id of 200.
When you double-click on PPob 200, a PPob editing window will appear (see
Figure 3) showing the object view hierarchy defined by this PPob. Right now, the
PPob consists of a single window.
Figure 3. A Constructor window showing PPob 200.
If you click on the window view and select Pane Information... from the Pane
menu (or just double-click on the window view), a pane info window will appear (see
Figure 4) allowing you to edit the selected view. In this case, the selected view
describes a document window with a zoom box, no close box, positioned automatically
in the Alert position on the main screen, etc. Feel free to edit this view if you like. To
test your changes, quit Constructor, saving your changes, then use CodeWarrior to
rerun the project.
Figure 4. The Pane Info window describing the Dashboard window.
Figure 5. The items you can place in a window using Constructor.
With the PPob 200 window in front, you should notice a palette window listing
all the items you can place in a PPob view. The palette, shown in Figure 5, works just
like ResEdit’s DITL palette. To add an item to a view, drag the item off the palette into
the PPob window.
Here’s where we’ll add the button to the window.
• Drag an LStdButton off of the palette into the window view in the PPob 200
window.
• Double-click on the button that appears and edit the info window to match the one
shown in Figure 6.
Figure 6. The info window for the LStdButton we added to our window view.
There are three important changes to make in the LStdButton info window.
First, change the Pane ID: field to read 1000 (be sure the Text ID checkbox is
unchecked before you change the ID). The Pane ID serves to identify the button pane
from all the other panes in the PPob resource. By convention, number your panes
starting at 1000 and moving upwards from there. For example, if you added three
items to the Dashboard window represented by PPob 200, you’d set their Pane IDs to
1000, 1001, and 1002.
The second change to make to the LStdButton info window is to fill in the Button
Title: field. Since we want our button to beep, the word Beep will make a fine button
title.
The third change is to the Value Message: field. This field contains the message
that will get sent when the button is clicked. The message is an integer constant that
will be passed as a parameter to any objects registered as listeners to the broadcasting
button. Again, by convention, we’ll number our messages starting at 1000.
That’s it. Save your changes and quit Constructor.
Dashboard68K.µ or DashboardPPC.µ
If you haven’t already, open up one of the Dashboard projects (either Dashboard68K.µ
or DashboardPPC.µ). Since we want to add a button to our window, we’ll need to add
the files that contain the PowerPlant classes that implement push buttons:
LControl.cp and LStdControl.cp.
• In the project window, click on the triangle to the left of the group named Pane.
When we add the two files, we want to add them to this group.
• Add the files LControl.cp and LStdControl.cp to the project. You’ll find them
in the folder “CodeWarrior 6:Metrowerks C/C++:PowerPlant Libraries:Pane
Classes”
CDashboardApp.h
• Open the file CDashboardApp.h.
• Add this line after the #include of :
#include
• Change the first line of the CDashboardApp class to look like this:
class CDashboardApp : public LApplication, public LListener {
To convert the CDashboardApp class into a listener, we have to make sure it is
derived from the class LListener. Deriving a class from more than one class is
perfectly acceptable in C++ and is known as multiple inheritence.
Another step in making the CDashboardApp class a listener is to add a member
function named ListenToMessage(). ListenToMessage() will get called when any
broadcaster it is listening to broadcasts a message.
• Add this line after the definition of the member function FindCommandStatus():
virtual void ListenToMessage(MessageT inMessage, void *ioParam);
• Close CDashboardApp.h and save your changes.
CDashboardApp.cp
Here’s where all the action is. Take some time to look through the file and read all the
comments (don’t worry, the file isn’t that long). Notice that main() defines a
CDashboardApp object and then calls the member function Run() which was inherited
from the LApplication class.
• Add this line after all the other #include files:
#include
Notice that even though we added the files LStdControl.cp and LControl.cp to
the project, we don’t include the file . is included by
.
• In the constructor, find the call of the static function
URegister::RegisterClass() and add this line right below it:
URegistrar::RegisterClass(LStdButton::class_ID,
LStdButton::CreateStdButtonStream);
This line tells PowerPlant which function to call
(LStdButton::CreateStdButtonStream()) when an object of type LStdButton is
created based on a PPob resource. Before we came along, this program only needed to
register the LWindow class. Since we added an LStdButton object to the PPob resource,
we’ll need to register that class as well.
• Also in the constructor, just before the call of mDisplayWindow->Show(), add
these lines:
LStdButton *theButton =
(LStdButton *)mDisplayWindow->FindPaneByID( 1000 );
theButton->AddListener( this );
The first line searches the window mDisplayWindow for the pane with the id
1000. Now you know why we entered the number 1000 in the LStdButton’s Pane ID:
field.
The second line registers the current object (the CDashboardApp object, known
here as this) as a listener of the button we just found.
• At the end of the file, add the member function
CDashboardApp::ListenToMessage():
// ----------------------------------------------------------
// • ListenToMessage
// ----------------------------------------------------------
// Respond to message 1000 broadcast by pushbutton
void
CDashboardApp::ListenToMessage(MessageT inMessage, void *ioParam)
{
if ( inMessage == 1000 )
SysBeep( 20 );
}
This function will get called whenever the button is clicked. The message 1000
will be passed in as the parameter inMessage.
Figure 7. The Dashboard window. This time it has a button in it.
Running the Program
That’s about it. Save your changes and run the program. The usual Dashboard window
will appear, but this time with a button smack-dab in the middle of it. Press the
button and, guess what, your Mac will beep at you.
Till Next Month
Obviously, this month’s program gives you only a brief glimpse into the PowerPlant
framework. On the other hand, it’s a pretty solid glimpse. Try your hand at adding
some other panes to the Dashboard window containment hierarchy. Start by adding a
second button with its own pane ID and its own message ID. Next, try to add some other
controls.
What part of PowerPlant would you like to learn about next? Should I get into
other control types? How about (shudder) menus? Send email. I’ll be waiting to hear
from you. See you next month...
Referenced by (136):