Before you can begin developing software with PowerPlant, you must have the necessary hardware and software. This chapter covers the details on these topics:
There are two kinds of requirements you should consider:
1. Hardware and system software you need to write a PowerPlant application.
2. Hardware and system software the user needs to run the final application.
Memory and hardware requirements to develop applications with PowerPlant are the same as to run the CodeWarrior IDE. More RAM may be required if you run the IDE, Constructor, and your application concurrently.
The IDE User Guide for information on system requirements.
All PowerPlant applications (programs that you create with PowerPlant) require the following minimum Macintosh setup:
ObjectSupportLib shared library. This library is an integral part of System 7.5
and later. ObjectSupportLib is built into Mac OS 8.0 and later.
NOTE For earlier systems, the user must have installed the ObjectSupportLib shared library in their Extensions folder. This file is on the CodeWarrior Tools CD in several locations. You may ship it with your products without additional licenses.
You should follow the installation instructions provided with CodeWarrior to install the files for PowerPlant. The safest way to install PowerPlant (and ensure you aren't missing anything vital) is to use the CodeWarrior installer.
Examine the options available in the installer. Most of the Mac OS-related options install PowerPlant as part of the process. The only options that do not are the minimal Mac OS installations. Even if you choose a minimal install, you can still select the "Metrowerks PowerPlant" option in the installer.
The installer does all the rest of the work. Installing PowerPlant creates a folder named Metrowerks PowerPlant inside your CodeWarrior folder. That folder contains the following items:
The original PowerPlant folder referred to by the alias is located in the "MacOS Support" folder inside the Metrowerks CodeWarrior folder.
This folder contains all the PowerPlant source code, both header and source files. They are grouped according to functionality into a series of folders such as Pane Classes, Commander Classes, and so forth. You will meet most of these classes as you read this manual.
All the PowerPlant source code is directly available to you so that you can study it, use it, see it in the debugger, and even modify it if modification is vital to your project.
WARNING! Although you can do so, you should think twice before modifying PowerPlant code. The whole purpose of an object-oriented application framework is to give you a structure that you can easily extend to suit your needs. You should rarely if ever run into a situation where modifying the actual PowerPlant code is either necessary or advisable.
The PowerPlant folder also contains the PowerPlant Resources folder. The PowerPlant Resources folder contains templates for both ResEdit and Resorcerer so that you can use those applications to edit and manipulate vital PowerPlant resources. We'll revisit this topic in "Installing Resource Templates."
The "PowerPlant Doc" folder is on the CodeWarrior Reference CD in the CodeWarrior Documentation folder. The PowerPlant documentation consists of this manual, PowerPlant Advanced Topics, the PowerPlant Reference, and the Constructor for PowerPlant User Guide.
PowerPlant Advanced Topics covers a variety of significant PowerPlant issues. It is a collection of independent chapters complete with example code.
The PowerPlant Reference is a series of HTML files that covers detailed information on PowerPlant classes, methods, and member variables. PowerPlant Reference can be viewed using any graphical web browser.
The Constructor for PowerPlant Guide provides the information necessary to use PowerPlant's view editor. You'll find it very useful as you get to know and use Constructor.
The tools installer does not install PowerPlant example code. Nonetheless, there is an abundance of PowerPlant example code available to you on the CodeWarrior Reference CD. You'll use some of that code in the code-intensive chapters of this manual.
The example code is located on the CodeWarrior Reference CD in
the MacOS Examples folder inside the CodeWarrior Examples folder. Inside the PowerPlant Examples folder there are several folders full of PowerPlant-related code.
The PP Book Code folder contains the code you use in this manual. We'll discuss
installing and using that code in detail when we reach the first
code exercise in this manual.
TIP Visit the PowerPlant contributed class archive available at http://www.metrowerks.com/support/powerplant/ for more classes written by other PowerPlant enthusiasts.
In the process of writing a PowerPlant-based application, you will create and use several unique resource types:
Constructor is the principal tool you use to create and edit PPob (PowerPlant object) resources. The PPob resource specifies the contents of a view (typically a window or part of a window), and how the contents relate to each other hierarchically. Constructor allows you to interactively create and design windows with lists, controls, pictures, and more by simply selecting items from a palette and placing them where you want them to appear in the window.
NOTE Constructor does not generate code, it simply creates the PPob resource. PowerPlant itself contains the code necessary to build the standard objects you specify in the PPob resource.
You can also use Constructor to create and edit MBAR, MENU, and Txtr resources. Constructor creates but cannot edit RidL resources. Constructor also lets you create and edit Mcmd resources right in the menu editor.
Although Constructor lets you work directly with all the necessary resources, you may wish to use a third-party resource editor such as ResEdit or Resorcerer to manipulate these resources. We have provided Rez and Resorcerer templates for all the resources, and ResEdit templates for some of them. Follow the instructions below for the editor you want to use.
"Basic PowerPlant Resources" for more information on PowerPlant resources.
The Resorcerer templates for all four PowerPlant resources are
in the PowerPlant Resorcerer TMPLs file. Locate this file in the PowerPlant Resources folder inside
the PowerPlant folder (the one that contains all the source code).
Be sure that Resorcerer is not running. Copy the file PowerPlant Resorcerer TMPLs to the "Private Templates" folder inside your Resorcerer folder.
The new templates will be available the next time you launch Resorcerer.
It's really that easy.
The ResEdit templates for three PowerPlant resources are in the
PowerPlant ResEdit TMPLs file. Locate this file in the PowerPlant Resources folder inside
the PowerPlant folder (the one that contains all the source code).
Open the PowerPlant ResEdit TMPLs file with ResEdit. Then open the ResEdit Preferences file (in the Preferences folder of your System folder). Go back
to the PowerPlant file, select the TMPL resources, and copy them.
Paste the resources into ResEdit Preferences, then save and close
the file. The new templates will appear immediately.
NOTE The PPob resource does not have a ResEdit template. You can't edit PPob resources in ResEdit because the layered containment hierarchy in a PPob resource is too complex for Res-Edit's template mechanism.
Rez is a resource compiler that translates text files into resources.
(DeRez is the corresponding decompiler). You can use Rez as a
tool under ToolServer (an MPW tool available under the CodeWarrior
IDE) or by using the plug-in Rez compiler that comes with CodeWarrior.
The necessary information to use Rez with PowerPlant resources
is in the PowerPlant.r file in the PowerPlant Resource folder. You'll find this file
in the PowerPlant Resources folder inside the PowerPlant folder
(the one that contains all the source code).
Most programmers who use Rez typically use it for resources that have convenient text representations. This includes all resources whose data is primarily strings or numbers, but also PPob resources, which have a simple textual format. You do not need any special templates to work with PowerPlant resources in Rez.
After you install PowerPlant, locate the source files so you can find them when you need them. You might want to locate the documentation files, and copy the PowerPlant Reference folder to your hard drive.
Also remember to install the resource templates for the resource editor of your choice, ResEdit, Resorcerer, or both.
Now you've got some great tools lined up, and you're ready to go to work! Before you do, let's cover some PowerPlant terminology and get comfortable with how the tools are organized.