PowerPlant Tips
Volume Number: 15
Issue Number: 4
Column Tag: PowerPlant Workshop
PowerPlant Tips, Tricks, and Gotchas
by John C. Daub, Austin, Texas USA
Tidbits of knowledge to improve your use of
Hello, Again
I hope you've been enjoying my "series" of articles on PowerPlant as they've appeared
here in MacTech Magazine. I've enjoyed writing it. Just about a week before I started
writing this article, one of the hard drives on my Mac at home starting making a
strange clicking noise, so I've disabled it - there went my development drive. So since
I don't have all my normal resources at my immediate disposal, I thought this month
I'd turn to the Internet for some input and posted a question to the
comp.sys.mac.oop.powerplant newsgroup. I asked the readers to post their favorite
PowerPlant "tip, trick, or gotcha". I received a few, but one reader had a lot to say.
I've dedicated a special section of this article to his experiences :-)
This is the sort of stuff that you learn through experience. As much as Carl tries to
document PowerPlant, most of these things you just don't appreciate until you get
bitten, and especially if they save your hide or find that niggling bug that you haven't
been able to squash for the past three months. This isn't to say I'm the most
experienced programmer out there, but rather to try to put some of those experiences
of mine and your fellow PowerPlant-users down in print to document them. A
magazine article's a good medium for this purpose. So I tried to collect from various
peoples and sources and put down what's relevant today. Some of this might still be
relevant years from now, others obsolete, or maybe all of this moot.
But still, I remember what it was like when I started. It's a steep learning curve to get
into programming, and definitely into PowerPlant. Once you're there it's not always
easy, but it's certainly not as difficult as when you started. Hang in there. I remember
all of the wonderful people that helped me when I was starting (Marco, Dan, Tim, Eric,
Greg) and still help me today (especially you, Greg) and so I'm just trying my best to
return the favor. It's this really cool Mac developers community that we have full of
openness and helpfulness. Maybe that's why Mac folk seem to find linux-ppc really
cool (and can't wait for OS X). And that's why I love to stick with Mac. If we can keep
this kind of community of sharing going on, that'll benefit us in the long run.
So read on. I hope you'll learn something new. I know that I did.
Let's start out with some general tips for using PowerPlant. These should remain valid
for a while as they are more principles of PowerPlant's design and implementation
style than matters of code. After Tips will come the Tricks, and following that the
Gotchas. The numbers are present for ease of reference. I present these in no
particular ordering, except for this first one:
1. Always read the release notes (or, RTFM)
This cannot be stressed enough. PowerPlant is a very dynamic framework that is
ever-evolving to suit the needs of Mac OS software developers. It's certainly
frustrating at times to have to keep up with each release, but you must. Reading the
release notes is the shortcut to seeing what changed and learning how to quickly update
your project to suit.
There are sections in the release notes that deal with new features, a detailed change
log, possible referrals to documents and PowerPlant TechNotes (yes, we have them
too). And most importantly, we try to catch all of the places where existing projects
will have to tweak something and report those first in the notes file. Heed them and it
should eliminate most of your upgrading pains and posting to the newsgroups (or
emailing Metrowerks Support). You'll get faster turnaround if you RTFM first.
And if you do have trouble, of course email Metrowerks Support at
<support@metrowerks.com> and/or post to the comp.sys.mac.oop.powerplant
newsgroup. There's usually someone just a keyboard away that can help.
2. Check the Reference CD
On your Reference CD in the PowerPlant Examples folder we keep a great deal of
information about PowerPlant. Not only examples, but also archives of obsolete code,
TechNotes, and archived release notes. Yes, all PowerPlant release notes archived back
to DR/1. Eases those upgrades when you jump a couple releases.
PP TechNotes is our folder of PowerPlant Technical Notes (just like Apple's
TechNotes). This is a good place to go for explanation on greater concepts like the
design of the Appearance Classes, or understanding the Networking and Internet
Classes, docs for Andy Dent's More Table Classes, and many other items of interest.
Worth checking out.
3. Keep up with OS evolution
Although PowerPlant is written in C++ and is an application framework (see my
the Toolbox. A lot of people are after higher levels of abstraction and encapsulation
these days, mostly because it aids porting to other platforms. PowerPlant doesn't want
to prevent you from going cross-platform, but it'd rather focus on the Mac. Do one
thing really well instead of trying to do more and failing.
And so PowerPlant must keep pace with the Mac OS as it evolves. ATSUI, Carbon, OS X,
OpenGL. There are some great things in store for the future of Mac. PowerPlant will be
there, we all have to keep up.
4. This is C++. Take advantage of what the language has to offer
As the C++ language has evolved and compilers race to implement the standard,
PowerPlant has made more and more use of the C++ language. By the time you read
this, CodeWarrior Professional 5 should have shipped and hopefully you have a copy on
your desk. PowerPlant now uses a real exception class, LException, publicly
inheriting from std::exception as the means of providing information about error
conditions (instead of the ExceptionCode, which is just a typedef'd long). Templates are
being used more (TArray, I'm working on a template version of UMemoryMgr for
post-Pro 5). RTTI is utilized throughout the framework. C++ is a good language -
strive to take advantage of it.
So as well, use classes like TArray to manage your lists of data; use LString and
friends LStr255, LStringRef, and TString (see my article on LString in the January,
resource management and exception safety. Work logically.
5. Use compiler warnings
Compiler warnings are there to help you. They are not errors, which mean something
is certainly wrong, but rather they are warnings - informative messages to try to
point out potential problems. Turn them on, use them on your code. They can prevent
problems.
Figure 1. CW Pro 4 C/C++ Warnings Preference Panel.
As you can see in Figure 1, there is a good deal of coverage performed by the
Metrowerks C/C++ compiler. I'd like to talk about three warnings: Implicit
Arithmetic Conversions, Non-Inlined Functions, and Hidden Virtual Functions.
Implicit Arithmetic Conversions is a warning issued "if the destination of an operation
isn't large enough to hold all possible results. For example, assigning a value of a
variable of type long to a variable of type char will result in a warning if this option
is on" (Metrowerks 1998, CCR-26). PowerPlant strives to compile cleanly with this
warning on, but some areas do slip through (e.g. Grayscale Implementations of the
Appearance Classes). Barring that one point, PowerPlant should compile cleanly with
this option.
Non-Inlined Functions is a warning that provides you with information on what you
asked the compiler to inline but it did not for some reason (remember, inline is just a
suggestion). Aside from the usual guidelines for inlining, the inline depth, a C/C++
compiler setting, does affect the output of this warning. Depending upon your inline
setting, you may receive these warnings on PowerPlant code. Play around with the
inline levels and see how that affects your resulting binary. Choose what works for
you. Generally I leave this option off and just use it when I wish to fine-tune my inline
settings for maximum gain from this C++ language feature.
Hidden Virtual Functions is another warning with which PowerPlant should compile
cleanly. PowerPlant does compile cleanly with this warning enabled, but not without a
little help from a #pragma. TArray hides some inherited virtual functions, but due to
the design and intent of the class we can guarantee this hiding is safe; in fact it is
needed for the intent of the class. But when you use a TArray, you receive several
hidden virtual function warnings. To quiet the compiler perform an explicit
instantiation of the template or just at the point of instantiation, wrap it with
#pragma warn_hidevirtual off/reset like this:
#pragma warn_hidevirtual off
template class TArray;
#pragma warn_hidevirtual reset
Using a technique like this you are able to ensure quiet and clean compiles with
TArray. Look in the PowerPlant sources - this technique is used throughout the
framework.
All compiler warnings are useful and generally I leave all on except the non-inline and
arithmetic conversions warnings, turning those on as needed. Refer to the C Compilers
Reference on your CodeWarrior Reference CD for more information on the warnings
and other language preferences.
6. Explore unfamiliar areas of PowerPlant
I do not know all of PowerPlant, but I do my best to at least have a familiarity with all
of PowerPlant. It takes time to learn and master every aspect, and with PowerPlant so
large it's difficult to know it all. But if you are at least familiar with what PowerPlant
has to offer then in the future when you have a new project, by knowing what