First Steps
Volume Number: 17
Issue Number: 4
Column Tag: PowerPlant Workshop
By Aaron Montgomery
How one goes about writing a PowerPlant application
My Intended Audience
This series of articles is intended to be an introduction into the use of the PowerPlant
application framework. It is intended to be a gentler introduction than The PowerPlant
Book supplied on the CodeWarrior CD and more elementary than previous MacTech
articles (in particular, those by John C. Daub). We will start by building a very basic
application in this article and we will add features to it in later articles (upcoming
articles are planned on the topics of: debugging, windows, files, dialogs, preferences,
and panes).
PowerPlant is big and it would be hard (if not impossible) to try to provide a simple
linear introduction to the topic. As a result, these articles are likely to introduce some
aspect of the framework without fully explaining how it works. In some cases, the
series will make a concerted effort to return to the topic but in other cases the reader
will be expected to do a little reading on their own. One consequence of this is that it
will probably be worthwhile to re-read earlier articles after finishing with the later
articles. Another consequence is that often I will introduce a term without explanation
and you may need to read more of the article before it makes sense.
While writing this article, I've assumed that the readers are familiar with the C++
programming language and basic Macintosh API programming topics. In addition to
these programming skills, readers are also assumed to be familiar with the
CodeWarrior IDE (including the use of the class browser and debugger).
Myself
Before you start reading this article, it is best to know where I learned what I know. I
program as a hobby (not as a profession) and have been using PowerPlant in my
projects for the past three years. Although I consider myself fairly adept with the
framework, I don't claim to know all the details. I encourage those who know the
framework better to contact me if I make any errors or miss any topics. Probably the
best forum for this is the PowerPlant newsgroup and I will also post errata at my web
site (see by-line).
Why Learn PowerPlant
PowerPlant is an application framework. You can find a detailed discussion of what this
means in The PowerPlant Book, but basically, this means that it provides much of the
routine code needed for a Macintosh application (in particular, the interface) and
allows you to focus on the details of your specific program. At the time that I am
writing this, a natural question arises: why bother with PowerPlant when you could
use Cocoa? Personally, I decided to continue to use PowerPlant for two reasons. The
first of which is my own personal familiarity with C++. Since I only program as a
hobby, I don't have the time (or the need) to build that level of familiarity with
Objective C and would like to continue to use a language I know. A second reason is that
many of the programs I write for educational purposes will be used in environments
where OS X is not going to be available for a number of years. PowerPlant allows me to
use a single code-base to support a wide variety of platforms (from 68K to G4).
The Tools
This article will assume that you are using CodeWarrior 6 with the net-update to IDE
4.1.0.3 and no other modifications. In particular, it assumes the use of Universal
Headers 3.3.2 and no modified PowerPlant files. I believe much of the code I write
should also run on CodeWarrior 5 or with newer Universal Headers without much
trouble (other than that caused by the Metrowerks' PowerPlant source). If you are
trying to use these articles as a guide and run into trouble with a particular
configuration, let me know and I will try to suggest a solution.
Stationary Options
The first thing to do with any project is to create a new project file from the
Metrowerks supplied stationary. There are four options: Basic, Appearance, Document
or Advanced. The Basic option is the simplest and all other options are built on top of
it. The Document and Appearance options have identical library source file and include
everything in the Basic option as well as the Appearance Classes, the Graphic Utilities,
the Grayscale Classes and the Page Controller. The difference between the two versions
is that the sample code for the Document option is set up for a basic application
supporting the use of documents. The Advanced option contains everything in the
Document and Appearance options as well as the Context Menu, the Debugging Classes,
the Table Classes and the Threads Classes. This is the option I choose most frequently
(the Debugging Classes are so good, they will be the topic of the second article in this
series).
For this project, I started with the Advanced option, moved some unused classes out of
the regular targets to a side-target (Other Stuff). We'll add them back to the build
targets when I start using them in later projects. I have also made some stylistic
changes (e.g., requiring explicit use of the PowerPlant namespace and adding a
separate file to contain main()). Finally, I removed some code so that I will be able to
focus on the basics. Much of the removed code will reappear in later articles.
Naming Conventions
Before examining any source code, the PowerPlant naming conventions deserve
mention. All PowerPlant types defined by typedef macros end with a T. All PowerPlant
classes begin with L (for library), U (for utility) or St (for stack-based). Class
methods begin with uppercase letters and use capitalization as a word-break. Class
data (static data) begins with the letter s and object data begins with the letter m.
Calls to the Macintosh API are indicated by a global scope operator (::). Local variables
are indicated by the prefix the. You can find more conventions in The PowerPlant Book.
User classes (those that you write) will typically start with a C (for class), I also use
Ut (for utility) and Au (for automatic, i.e., stack-based) classes. Class data for my
classes begins with our and object data begins with my. This helps me distinguish
between data I am responsible for and data coming from the framework.
Browsing the Initialization Code
The first code we will discuss is the function main() in main.cp. One effective way to
learn about PowerPlant is to use the class browser to examine a function's definition
and commentary. In order to follow along, you will need to make the project with the
class browser activated (see the Build Extras preference panel for the target). I will
be using the PPC Debug target although you may want to use a different target
depending on your setup. (I have removed all comments for listing in the magazine.)
main() in main.cp
int main()
UQDGlobals::InitializeToolbox();