PowerPlant and Scrolling Windows

By Dave Mark, MacTech Magazine Regular Contributing Author

Due to popular demand, this month’s column returns to the land of CodeWarrior and PowerPlant. Assuming it’s okay with all of you, I’d like to spend the next few months really getting to know PowerPlant, instead of hopping back and forth between PowerPlant, TCL, and Sprocket. Any dissenting opinions? Let me know! As always, look on page 2 of the magazine to find out how to get in touch with us.

I want to take a moment and thank Greg Dow, the creator of PowerPlant, for all his help. Greg has never been too busy to answer my questions, and spent a lot of time making sure I got it right. If you see Greg at MacWorld or at WWDC, thank him and buy him an Espresso!

Create the PictScroller Project

This month’s program will create windows that look like the one shown in Figure 1. Notice that the window is divided into two areas. The top area contains two buttons. The left button beeps when you click on it. The right button is disabled (we’ll change that in next month’s column). The lower portion of the window contains a PICT, and the scroll bars allow you to scroll the PICT up and down, left and right. The close box, zoom box, and size box each work as expected. The PICT is not scaled, and “sticks” to the upper left corner of the scrolling region. Perhaps the coolest thing about this program is that dragging the thumb forces the window to update dynamically. In other words, the window is constantly redrawn as you drag the thumb, unlike a normal Macintosh window which updates only after the scrollbar’s thumb is released.

Figure 1: A PictScroller window

Let’s get to work.

• Create a folder named PictScroller ƒ on your hard drive, anywhere outside of the CW7 folder.

• Lauch CodeWarrior IDE 1.3. You’ll find it inside the CodeWarrior 7 folder, inside the Metrowerks CodeWarrior subfolder.

• Create a new project file named PictScroller.µ - be sure you use one of the two PowerPlant stationery files when you create the project. Select either PowerPlant 68K.µ or PowerPlant PPC.µ from the Project Stationery popup menu.

• In the project window that appears, double-click on the file name <PP Starter Source>.cp.

This file is located in the stationery folder. Since we’ll eventually modify this file and we don’t want our changes reflected in the project stationery, we’ll save a copy of this file in our working folder.

• Select Save As... from the File menu and save the file as PictScroller.cp in your PictScroller ƒ folder.

Notice that the file name actually changed in the project window, showing that your copy of the file has replaced the stationery file in the project. Our next step is to change the name of the include file associated with this .cp file.

• Towards the top of the file PictScroller.cp, you’ll find an include file named <PP Starter Header>.h. Open this file by selecting the file name and typing AppleD.

• Once the file <PP Starter Header>.h opens, select Save As... from the File menu and save it in your PictScroller ƒ folder under the name PictScroller.h.

• Close the file PictScroller.h.

• Back in PictScroller.cp, change the reference <PP Starter Header>.h in the #include to say PictScroller.h instead.

At this point, all of our source code is disconnected from the stationery files. There is one more stationery dependency left, however, and that is the file <PP Starter Resource>, the default constructor file.

• Back in the project window, double-click on the file named <PP Starter Resource>.rsrc. Though the file contains regular old resources, its creator is MWC2, the creator type associated with Constructor 2.0.

• In Constructor, select Save As... from the File menu, navigate back over to your PictScroller ƒ folder and save the file as PictScroller.rsrc.

• Go back to CodeWarrior and select the file <PP Starter Resource>.rsrc in the project window.

• Select Add Files... from the Project menu and add the file PictScroller.rsrc to the project.

• Once again, select <PP Starter Resource>.rsrc in the project window. This time, select Remove Files from the Project menu to remove the last stationery file from the project.

We have now made our own copy of the three files we’ll be modifying: PictScroller.rsrc, PictScroller.cp, and PictScroller.h. Before we make our changes, let’s take the default project for a spin.

• Select Run from the Project menu.

PowerPlant will now compile all of the source code files (the entire PowerPlant framework) in your project. This took about one minute and 15 seconds on a PowerMac 8100/100. Your mileage may vary.

It is interesting to note that the completely compiled project file takes up about 1.1 meg of hard drive space, as compared with the more than 10 meg consumed by last month’s TCL project. Obviously, Symantec stores a lot more project information than CodeWarrior. Still, a size factor of 10 to 1 is pretty significant. Hey, Rich Parker, do you know why this is?

• Once the project compiles and runs, select Quit from the File menu.

We are now ready to use Constructor to design our custom two-button scrolling window.

• Go back to Constructor. The file PictScroller.rsrc should still be open.

Figure 2 shows the PictScroller.rsrc Constructor window before we start messing with it. Constructor handles three different resource types. Views, by far the most popular type, are what we’ll be working with. Views are Constructor interface elements designed to act as containers for other Constructor elements. You’ll frequently encounter the terms view and pane. All visual Constructor elements are panes. Views are panes that can contain other panes. Don’t get too hung up on the terminology. It really isn’t important.

Figure 2: The PictScroller.rsrc window, before we make our changes

Text traits allow you to embed TextEdit style information inside a resource, rather than specifying it programmatically using QuickDraw calls. Think of text traits as a poor person’s style sheet.

Custom types allow you to create your own custom views, as opposed to the views that are built into Constructor.

The project stationery came with a single view, an LWindow with a resource ID of 1 and a name of <replace me>. This View resource will act as the template for our two-button scrolling window. Let’s start changing it.

• Make sure the LWindow view is selected, then select Resource Info from the Edit menu.

A resource info window will appear (Figure 3). We’ll change the resource name to something a little more meaningful.

Figure 3: The resource info window for the LWindow view

• Change the Resource Name: to PictScroller.

• Close the resource info window.

• Now double-click on the LWindow view. A view editing window will appear (Figure 4).

You should recognize this as the window that appeared when you ran your program before. Notice that this view consists of 2 panes, one representing the window and one representing a static text string that appears in the window.

Figure 4: The “before” picture of our LWindow view

• Click on the static text string and press the Delete key to delete the static text pane from the LWindow view.

• Double-click on the window pane (the one with the number 1 in the upper right corner). A pane info window will appear (Figure 5).

• Click on the Size Box, Resizable, and Zoom Box checkboxes (so all five checkboxes in that area are checked).

• Select Stagger on Main Screen from the Auto Position: popup menu.

• Change the Window Title: to PictScroller.

• Close the info window.

Figure 5: The pane info window for the PictScroller window,
after all the changes were made

• Click on the Tools palette window and drag an LStdButton from the palette into the PictScroller view.

• Double-click on the button that appears. A pane info window for the button will appear (Figure 6).

Figure 6: The pane info for the Beep button,
after all the changes were made

The Binding to Superview: checkboxes let you specify how this pane binds to its enclosure. For example, if we check the Top checkbox, the button will stick to the top of the enclosing view. If the enclosing view is resized, the button won’t move. If the Bottom checkbox were checked instead, the button would move when the enclosing view is resized, sticking a fixed number of pixels from the bottom. Note that if the Top and Bottom checkboxes were both checked, if the enclosing view was resized, the button would scale!

Since the top of our enclosing pane won’t scroll, not checking any of the checkboxes is equivalent to checking both Top and Left.

• Change the Pane ID: to 1000. We can use this ID to retireve a pointer to the button object. We’ll do this in the code later on.

• Change the Button Title: to Beep.

• Change the Value Message: to 1000. As pointed out in the last PowerPlant column, the Text Message check box lets you use 4-letter codes (like 'beep') instead of integers (like 1000).

• Change the Location: fields as follows. Left = 20, Top = 8, Width = 80, and Height = 20.

• Close the button’s info window.

Now let’s do the second button.

• Drag out a second LStdButton from the Tools palette.

• Double-click on the button. The button’s info window will appear.

• In the Binding to Superview: window, click on the Right checkbox. This makes the button stick to the right side of the window when the window is resized.

• Change the Location: fields as follows. Left = 200, Top = 8, Width = 80, and Height = 20.

• Change the Button Title: to Dialog.

• Uncheck the Enabled check box (so the button is dimmed). Note that there is a bug in Constructor: disabled buttons appear with no title text. No big deal. The title appears in grey when you run the program.

• Change the Pane ID to 1001.

• Change the Value Message to 1001. We won’t be tying any code to this button till next month.

• Close the button’s info window.

Now let’s create the scrolling pane that will contain the PICT.

• Drag an LActiveScroller from the palette to the LWindow view window. An LActiveScroller updates dynamically in response to thumb drags. An LScroller updates once the thumb is released.

• Double-click on the LActiveScroller. The LActiveScroller’s info window will appear.

• Change the Location: fields as follows. Left = -1, Top = 36, Width = 302, and Height = 165. Try some different values and you’ll see why I chose these.

• Check all four of the Binding to Superview: checkboxes. We do this so that the pane will stay the same size as the window, even when it resizes. Note that this will not affect the PICT resource that we embed in this view. In other words, just because this view scales doesn’t mean that embedded panes scale.

• Set the Pane ID: to 1002.

• Set the Scrolling View ID: to 1003. Note that this is the ID of the view we want scrolled inside this view. We’ll create view 1003 next.

• Close the LActiveScroller’s info window.

Now we’ll create the pane that will hold the PICT resource.

• Drag an LPicture from the palette inside the LActiveScroller.

Due to a bug in Constructor, you won’t be able to drag the LPicture so it is embedded inside the LActiveScroller. Luckily, there is a different way to make this happen.

• Select Show Hierarchy from the Display menu. The hierarchy window will appear, listing all the views inside the LWindow view.

• In the hierarchy window, click on the LPicture icon and drag it to the right and slightly up. The little black triangle that appears as you drag should point to the lower right corner of the LActiveScroller icon and the line that appears should be below LActiveScroller. Figure 7 shows a before and after picture of the hierarchy change.

Figure 7: The first picture is before
and the second picture is after the hierarchy change,
moving the LPicture within the LActiveScroller

• Close the hierarchy window.

Now we’ll set the LPicture info.

• Double-click on the LPicture. The LPicture’s info window will appear.

• Change the Location: fields as follows. Left = 1, Top = 1, Width = 285, and Height = 148.

• Set the Pane ID: to 1003.

• Set the PICT Resource ID: to 128.

• Check all four of the Binding to Superview: checkboxes. Once you get your program working, try unchecking a few of these to see what happens.

• Check the Reconcile Overhang checkbox. This keeps white space from appearing when you grow the window down. It is usually checked for PICTs, unchecked for text.

• Set the Scroll Unit: values to 1 and 1. This specifies the scrolling resolution.

• Leave the Image Size: values at 0 and 0. This tells Constructor to use the FrameRect of the PICT as the bounding rectangle. Try setting these values as the width and height used in the Location: fields. Combine this with your Binding to Superview experimentation for maximal effect.

• Leave the Scroll Position: values at 0 and 0. These are the initial values of the scroll bars. 0 and 0 will start the PICT off unscrolled.

• Close the LPicture info window.

At this point, the LPicture will be grey. That’s because we haven’t created a PICT resource with an ID of 128. We’ll do that next.

• Quit Constructor, saving your changes when prompted to.

• Go into Resorcerer or ResEdit and open the file PictScroller.rsrc.

• Open up your Scrapbook and copy a picture into the clipboard.

• Back in Resorcerer/ResEdit, paste the picture, creating a new PICT resource.

• Change the PICT resource ID to 128.

• Quit Resorcerer/ResEdit, saving your changes.

• Go back into Constructor, open PictScroller.rsrc and verify that your picture made it into the LPicture (Figure 8).

• Quit Constructor.

Figure 8: The final version of the PictScroller view in Constructor

Modifying the Source Code

Now that we have our Constructor view completely defined, we’ll make a few small code changes to bring it to life. Since our stationery-based program already has the ability to generate a new window tied to the LWindow view with a resource ID of 1, all we have to do is register the LActiveScroller class (you’ll see why in a minute), turn the CPPStarterApp class into an LListener, then add a function that listens for the message generated by the Beep button (and beep when we get that message).

• Back in CodeWarrior, open the file PictScroller.h.

• Change the declaration of the CPPStarterApp class so it is derived from both the LApplication and LListener class. Take a look at the new listing of PictScroller.h that follows the next few commands.

• Add the #include of the file LListener.h.

• Finally, add a new, public member function named ListenToMessage() to the class declaration.

• Close PictScroller.h.

Here’s the new version of PictScroller.h:

// ====================
// <PP Starter Header>.h         ©1994-1995 Metrowerks Inc.
// All rights reserved.
// ====================

#pragma once

#include <LApplication.h>
#include <LListener.h>

class CPPStarterApp : 
 public LApplication, public LListener {

public:

    // constructor registers all PPobs
 CPPStarterApp();
    // stub destructor
 virtual ~CPPStarterApp();
 
    // this overriding function performs application functions
 virtual Boolean ObeyCommand
 (CommandT inCommand, void* ioParam);
 
    // this overriding function returns the status of menu items
 virtual void FindCommandStatus
 (CommandT inCommand,
 Boolean &outEnabled, Boolean &outUsesMark,
 Char16 &outMark, Str255 outName);
 
 virtual void ListenToMessage
 (MessageT inMessage,
 void *ioParam);

protected:

    // overriding startup functions
 virtual voidStartUp();
};

We covered the LListener class 3 columns ago, in our first PowerPlant program. As a reminder, a class that is derived from LListener can receive messages sent to it by other classes. In this case, we’re going to tie a CPPStarterApp object to the Beep button by passing a CPPStarterApp pointer to the Beep button object’s AddListener() member function. Check back to the previous PowerPlant column for more detail. And if you still don’t get it, don’t worry. We’ll do more message listening in future PowerPlant columns.

Our next step is to make changes to the file PictScroller.cp.

• Open the file PictScroller.cp.

• Add this line below the #include of LEditField.h:

 
#include <LActiveScroller.h>

• Scroll down to the constructor CPPStarterApp::CPPStarterApp(), and add this line at the end of the function:

 URegistrar::RegisterClass
 (LActiveScroller::class_ID,
 LActiveScroller::CreateActiveScrollerStream);

As we discussed in the previous PowerPlant column, we need to register all the PowerPlant classes we’ll be using. Before we added this line, the only thing the constructor did was call RegisterAllPPClasses(), which registers a bunch of classes. Unfortunately, this does not include the LActiveScroller class. No big deal. We just registered it ourselves.

To see which classes are registered automatically, open the file PPobClasses.cp and check out the function RegisterAllPPClasses() (at the very bottom of the file). To get there quickly, once you’ve compiled your source, option-double-click on the constructor call RegisterAllPPClasses().

I copied the RegisterClass() call above directly from the bottom of PPobClasses.cp. Note that we could have avoided this step if we had used an LScroller instead of an LActiveScroller. LScrollers are part of the mainstream. LActiveScrollers are part of the iconoclastic fringe, the bad seeds, the outcasts...

OK, OK, back to the code. Our next step is to add a listener function that beeps when it gets the right message.

• Add this function to the bottom of PictScroller.cp:

// ---------
// • ListenToMessage
// ---------
// Constructor

void CPPStarterApp::ListenToMessage
 (MessageT inMessage, void *ioParam )
{
 if ( inMessage == 1000 )
 SysBeep( 20 );
}

Our final step: add the listener to the Beep button.

• Find the function CPPStarterApp::ObeyCommand(). It is about 3/4 of the way through the file.

• In the switch statement, find the case for cmd_New.

• Insert these lines after the call to CreateWindow() and before the call theWindow->Show():

 LStandardButton *theButton =
 (LStandardButton *)theWindow->FindPaneByID( 1000 );
 theButton->AddListener( this );

Here’s what the entire case looks like:

 case cmd_New:
    // EXAMPLE, create a new window
 LWindow*theWindow;
 theWindow = LWindow::CreateWindow
 (window_Sample, this);
 LStdButton *theButton =
 (LStdButton *)theWindow->FindPaneByID( 1000 );
 theButton->AddListener( this );
 theWindow->Show();
 break;

Run the Sucker

That’s it. Now go take this puppy for a ride. When it runs, a window like the one shown in Figure 1 will appear by default. Look through the code and see if you can figure out why. Select New from the File menu and more windows will appear. If your PICT was large enough, you’ll be able to scroll it. Try dragging a scrollbar’s thumb. Is that cool or what? The window updates automatically, as you move the thumb. Interestingly, the CodeWarrior source code windows do the same thing. Gee, do you think the CodeWarrior editor was written in PowerPlant? Very cool.

When you resize the window, notice that the right, disabled button sticks to the right side of the window. If you make the window small enough, the buttons will run into each other. Go back into Constructor and figure out how to set the minimum height and width for the window. Here’s a clue: To get at the LWindow info window, open the LWindow view, then double-click on the title bar of the window shown in the overview window (the window shown in Figure 8).

Finally, notice that the Beep button beeps and that the Dialog button is disabled and that its title was drawn in grey.

Till Next Month...

Next month, we’ll add another view to our program. Right now, I’m thinking about a modeless dialog, but who knows? See you then...