TweetFollow Us on Twitter

Utility In Utilities

Volume Number: 15 (1999)
Issue Number: 6
Column Tag: PowerPlant Workshop

Utility in Utilities

by John C. Daub, Austin, Texas USA

Exploring the PowerPlant Utility Classes

In The Details

When you first learn PowerPlant, you must concern yourself with the larger notions of The Framework - the event handler, the view hierarchy, the Commander chain, Broadcasters and Listeners. These are core, foundational aspects of PowerPlant that you must know and understand to begin writing applications in PowerPlant. After you have the core down and have hacked out your first PowerPlant app, you start to explore new areas of The Framework: perhaps the Networking Classes, Internet Classes, Threads, AppleScript-ability. Those areas are certainly all good, however I'd like to suggest one group of classes and code that you might not have thought to take a further look at. All the little classes that exist in both cohesive groups and scattered one-shots throughout The Framework - Utility Classes.

Utility Classes are an important part of any framework. They help you accomplish the work you need to do by perhaps simplifying an API, or providing means to manage other objects and states, or maybe just consolidate a lot of (perhaps commonly used) code into a single function call. Utilities won't solve all of your programming problems, but they certainly should prove to find a useful place in your toolbox as they alleviate a lot of the headaches you encounter on a daily basis. Working the use of such utilities into your coding habits can help you write more robust and less-error-prone code from the onset.

General Framework Utilities

Most of the Utility Classes in PowerPlant can be classified into a couple groups, with a few left over. We'll take a brief look at them all. By the way, you can follow along in source code by opening your Utility Classes folder and reading each source file as we get to it.

Core

There are some Utility Classes that implement the internal support structure for portions of The Framework's functionality. UReanimator and URegistrar are two such core classes, as they are central to the PPob mechanism. These classes implement the ability to instantiate your PPob at runtime. UReanimator reads the 'PPob' DataStream and calls the proper object constructor/creation-routine - found by a table lookup to URegistrar - to reanimate your PPob (Window, Dialog, etc.). UDebugging and UException are another file combination, implementing the core debugging and exception handling infrastructure for PowerPlant. UCursor implements basic cursor handling. UEnvironment collects, maintains, and provides a query mechanism on particular environmental information (EnvironmentFeature), such as if a certain technology is present (Drag and Drop, Thread Manager, Appearance Manager, etc.). These core classes are used throughout PowerPlant by the framework itself, and of course you are free to use them. In fact, you should use these facilities provided by The Framework because if you write to PowerPlant's API, you can many-times be shielded from the pains of OS conversions (especially useful as we move towards Carbon) as well as pick up any advances/fixes from PowerPlant for free.

An important piece of, as well as a recent addition to, the core utilities is UAppearance. UAppearance is a strange but useful class for working with the Appearance Manager, especially Appearance Manager v1.1. In Appearance Manager 1.1 (released as a part of Mac OS 8.5), Apple introduced Themes. Themes were a way to modify the overall cosmetic look and feel of your Mac (akin to the shareware Kaleidoscope). For whatever reason, Themes didn't come to pass in OS 8.5, but nevertheless PowerPlant worked to try to be as Theme-savvy as possible. One problem faced was how to support the various versions of the Appearance Manager (v1.0, v1.0.x, v1.1) from a unified API. Furthermore, OS 8.5 was PowerPC-only, which meant Appearance Manager 1.1 was PPC-only as well. As PowerPlant must work on both 68K and PPC from the same codebase, what to do to allow ones code to work properly with Themes, all Appearance Manager versions, and possible runtime architectures? Whew! Enter UAppearance, consolidating the various means for determining Appearance-related information into a single-API. If you need to get the text color, call UAppearance::GetThemeTextColor() and it will Do The Right Thing® based upon compile and runtime options. Read the source (that includes reading the header, too!) to get the low-down. UAppearance doesn't bridge all such needs that might exist in the Toolbox, just what PowerPlant itself needs. Of course, if you need to obtain this information in any of your code, do use the UAppearance bottlenecks as they should always Do The Right Thing.

Encapsulated Functionality

Some Utility Classes work to consolidate common behaviors into groups and easy-to-call functions. UTextTraits provides the complete functionality needed by The Framework to work with TextTraits Resources ('Txtr'). UWindows provides implementations of some common window manipulation routines, like getting the content and structure Rects. UScreenPort creates a GrafPort the size of the GrayRgn (see UFloatingDesktop for use). UPrintingMgr provides wrappers for some common printing needs. UKeyFilters provides the functionality to implement KeyFilters (as used by classes like LEditField and LEditText).

UDrawingState and UDrawingUtils are two of the more commonly used portions of this group. If you look in those source files, you'll see there's a lot of good stuff. UDrawingState is mainly a collection of small stack-based classes for saving/restoring drawing states: GrafPort, color, pen, text style, clipping region, port origin. I'll speak about stack-based classes in greater depth later in this article. UDrawingState also contains stack-based classes for manipulating the visRgn and the CQDProcs. UDrawingUtils is a general collection of routines for drawing behaviors. UTextDrawing performs various text renderings, akin to TETextBox only better. LMarchingAnts and UMarchingAnts can help you implement a marquee selection (see also LMarqueeTask in the Constructor Additions). UDrawingUtils and StColorDrawLoop help to work with drawing devices so PowerPlant can Draw() in a device-friendly manner (e.g. proper rendering of widgets when they straddle multiple monitors each set at a different bit-depth).

Other

Finally, some classes don't fit into any nice grouping. UAttachments contains many simple, pre-made Attachment classes. UProfiler contains a simple stack-based class to aid working with the Metrowerks Profiler. UQDOperators.h implements some global operators for easily comparison of some QuickDraw data types. Most of the routines in the Utility Classes are small and quick, simple to understand and use. Many are stack-based classes, and those hold a special bit of functionality within the Utility classes.

Exception Safety and Resource Management

One powerful feature of C++ is its error handling mechanism - exceptions. One joy of exceptions is they can interrupt the flow of execution when something goes wrong. But, this same joy can bring problems in that the normal flow of execution normally ended with a cleaning up of resources, for example:

   {
      Handle      theHandle   = ::NewHandle(kSize);
      ThrowIfMemFail_(theHandle);

      DoSomething(theHandle);      // Could throw an exception.

      ::DisposeHandle(theHandle);
   }

If DoSomething() causes an exception to be thrown, the stack will unwind and ::DisposeHandle() will never be called causing theHandle to be leaked with no possible means of cleaning it up. Not a desirable situation. You could handle this problem with a try/catch block:

   {
      Handle      theHandle = ::NewHandle(kSize);
      ThrowIfMemFail_(theHandle);

      try {
         DoSomething(theHandle);    // Could throw an exception.
      } catch(...) {
         
            // Perform cleanup
         ::DisposeHandle(theHandle);

            // Rethrow the exception
         throw;
      }

      ::DisposeHandle(theHandle);
   }

The above certainly works and handles the situation, but it feels overkill for such a simple situation. Furthermore, in more complex situations than this trivial example, littering your code with too many try/catch blocks can get to be cumbersome. Instead, consider exploiting a power hook of the C++ language: the destructor. Whenever a C++ object is destroyed (by calling delete on a heap-based object, or going out of scope on a stack-based object), it is guaranteed that the destructor will be called. You can exploit this hook to aid in the management of resources (which aren't necessarily Mac OS Resources, but certainly can be); this is what stack-based classes are all about. Let's look at how this works in greater detail by examining probably the most frequently-utilized group of stack-based classes in PowerPlant: UMemoryMgr, and specifically StHandleBlock.

The basic premise behind a stack-based class is the constructor does something and the destructor undoes it. Push-Pop. Hence, stack-based. A common paradigm in programming is to temporarily change the state of something by saving off its current state, changing it to the new state, doing whatever work you needed to do, then restoring the original state. Such situations are prime for stack-based classes, and the classes of UDrawingState are perfect examples of this lot (StColorPenState). Other stack-based classes still function on the same push-pop paradigm (say that five times fast!), but provide greater functionality to the user; StHandleBlock is a good example of this sort of class.

StHandleBlock is a stack-based class that manages a Mac OS Handle. (I'm sure by now you've noticed the PowerPlant convention of naming (most) stack-based classes with an St prefix). The StHandleBlock constructors either take ownership of an existing Handle or allocate a new one (::NewHandle()). There are routines to manipulate the Handle, so you can treat an StHandleBlock object as a Handle in your code. And most importantly the StHandleBlock destructor disposes of the Handle. One benefit of the class is that the Dispose() method is smart and checks first to see if the Handle is a Memory or Resource Handle, calling ::DisposeHandle() or ::ReleaseResource() as appropriate (no more need for the DisposeResource INIT). StHandleBlock is fairly straightforward, and most of your use of the class in code will be fairly boring and uneventful. The joy the class brings comes in terms of cleanup.

Again, StHandleBlock is a stack-based class - whenever the object leaves scope (since you do tend to create stack-based classes on the stack...), the destructor for the object will be called. Think about the ways that you can leave scope. You could leave them normally, like reaching the bottom of the function. You could leave abnormally, perhaps as a goto or as a result of an error or exception. But no matter how you leave, the (StHandleBlock ) object leaves scope and its destructor is called thereby undoing whatever you did (::DisposeHandle())and leaving the world in the state that you found it. So we can rewrite our above code snippet like this:

   {
      StHandleBlock   theHandle(kSize);
      DoSomething(theHandle);
   }

Yea, that's all the code becomes, and therein is part of the joy. The StHandleBlock constructor will try to allocate a Handle of the requested kSize, failure resulting in an exception being thrown (due to the constructor that we used, see the source for more details). Once that returns, theHandle is now a valid StHandleBlock object with a Handle of size kSize, just like before. Through the magic of an implicit type conversion operator, theHandle can be passed directly to DoSomething() as argument. If DoSomething() should throw an exception, theHandle will go out of scope and ::DisposeHandle(mHandle). If DoSomething() does not throw and the routine exits normally, theHandle still goes out of scope and ::DisposeHandle(mHandle). By use of StHandleBlock, no functionality has been lost, and the gains of resource management and exception safety have been won. You just write it and forget it. Your code is now more robust, less chance for error, and Spotlight should hopefully find your code more agreeable (and then so should your customers!).

Certainly the use of the stack-based class isn't without cost (Meyers discusses costs of C++ in More Effective C++). There is the overhead of the object itself, the storage requirements (in addition to the storing of the normal data, be it a Handle or Ptr or Str255 or what have you), the time involved to create/dispose the object. In most situations these are worthwhile tradeoffs. If exception safety is needed, if delegating the responsibility of cleanup to the object itself is desired, then by all means use the classes. But there are occasions where it's more wasteful to use them, e.g.:

   {
      Handle      theHandle   = ::NewHandle(kSize);
      ::BlockMoveData(dataPtr, *theHandle, 
                           ::GetPtrSize(dataPtr));
      ::DisposeHandle(theHandle);
   }

In the above code, theHandle was allocated, used, and disposed of with no chance for the flow of execution to change unexpectedly. Using StHandleBlock here is certainly legal and fine to do, but is not as efficient as is direct Toolbox access. Base your approach upon the context.

If you like StHandleBlock, check out StTempHandle and StClearHandleBlock which are subclasses of StHandleBlock that allocate a Handle in temporary memory and allocate a cleared Handle, respectively. Related to StHandleBlock is StPointerBlock (and StClearPointerBlock); these classes behave similar to their Handle counterparts, but maintain a Mac OS Ptr rather than a Handle. UMemoryMgr also contains a PowerPlant version of std::auto_ptr<T> called PP_PowerPlant::StDeleter<T>; StDeleter is functionally equivalent to auto_ptr, but exists to minimize dependencies upon the C++ standard library. StHandleLocker merely locks a Handle and ensures a proper restoration of the Handle state, which allows StHandleLocker objects to be nested safely. Furthermore, StHandleLocker implements Handle locking in a scheme consistent with Apple TechNote 1122, which discusses the proper way to lock a Handle.

Related to UMemoryMgr is URegions. URegions is comprised of two classes: StRegion and StRegionBuilder, providing similar functionality as StHandleBlock, but specifically tuned towards working with Mac OS Regions. Not only is the creation/destruction of the RgnHandle accounted for, but all manner of operator overloads and methods are provided to facilitate working with Regions - never has working with Regions been so simple! StRegionBuilder works in conjunction with StRegion to facilitate the on-the-fly creation of Regions. As you use these classes in your own code, you start to see how through their use throughout your code, the tighter the web they weave to keep code clean and properly coping with unexpected problems when they crop up.

UMemoryMgr is a prime example of how stack-based classes can help you better manage your resources, eliminate memory leaks, eliminate stale state information, be exception-safe, and write more robust code. These sorts of utility classes should find their way into your toolbox as need for them arises. Explore. If you'd like to learn more about the concepts these classes are based upon, check out C++ FAQs by Cline and Lomow, and Scott Meyers' excellent books Effective C++ and More Effective C++.

More Than Utility Classes

There are a good many "utility" classes throughout PowerPlant; it's not isolated to only those files and classes located with the Utility Classes folder. Many of the other folders contain "utility" type classes, and many files have little utility classes and/or methods to ease working with other classes within the same file.

The Support Classes folder is a prime example of another set of "utility" classes. With classes for working with the Clipboard (LClipboard), GrowZones (LGrowZone), tracking the mouse (LMouseTracker), manipulating windows (UDesktop and UFloatingDesktop), and of course we can't forget LString. The In Progress folder also houses a number of utility classes (at least at the time of this writing, looking at PowerPlant 2.0). There are utilities for working with graphics (LGAIconMixin, LGATitleMixin, UGAColorRamp, UGraphicUtils), menus, StuffIt archives, contextual menus. AppleEvent Classes folder has UAppleEventsMgr and UExtractFromAEDesc.

Contained within many source files are utilities for the particular main class. In LModelObject.h, you'll find the StLazyLock and StTempTellTarget classes that facilitate working with LModelObject. TSharablePtr is a smart-pointer class for working with LSharable objects (reference counting). And the lists can go on.

Fin

Utility Classes are an essential part of any framework. They are tidbits of code that help make our life a little bit easier by letting us write one line instead of ten, automate some process, facilitate another process. They help our code be more robust through exception-safety and resource management. They help us out in the long run because we can write more trouble-free code from the start, which means less time wasted debugging and more time spent refining the features of your killer app.

I hope this brief tour of the Utility Classes in PowerPlant has shown you something new, perhaps some unexplored area of PowerPlant. Stack-based classes are a great part of the Utility classes and are probably a good place for you to start to get familiar with these classes. But don't stop there! Read the source code and see what else PowerPlant has to offer. There are lots of nooks and crannies in PowerPlant that hold some really neat stuff. The more you know, the more you can do.

Happy programming!

Bibliography

  • Dow, Greg. Chief PowerPlant Architect.
  • Hinnant, Howard. Metrowerks C++ Library Wizard.

URLs


John C. Daub loves his new WallStreet/DVD - it's what he's using to type this article. John is transitioning to a new position with Pervasive Software working on the Mac Editor portion of Tango. At the time of this writing, John has been with the company three weeks and is having fun! As always, you can reach John via email at <hsoi@pobox.com>, or feel free to drop him a line at <John.Daub@pervasive.com> (IS won't let him have "hsoi" ;-)

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

EtreCheck 3.4.2 - For troubleshooting yo...
EtreCheck is an app that displays the important details of your system configuration and allow you to copy that information to the Clipboard. It is meant to be used with Apple Support Communities to... Read more
Hopper Disassembler 4.2.10- - Binary dis...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
VueScan 9.5.81 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
iFFmpeg 6.4.2 - Convert multimedia files...
iFFmpeg is a comprehensive media tool to convert movie, audio and media files between formats. The FFmpeg command line instructions can be very hard to master/understand, so iFFmpeg does all the hard... Read more
Fantastical 2.4.1 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Fantastical 2.4.1 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Live Home 3D Pro 3.2.2 - $69.99
Live Home 3D Pro, a successor of Live Interior 3D, is the powerful yet intuitive home design software that lets you build the house of your dreams right on your Mac. It has every feature of Live Home... Read more
Live Home 3D Pro 3.2.2 - $69.99
Live Home 3D Pro, a successor of Live Interior 3D, is the powerful yet intuitive home design software that lets you build the house of your dreams right on your Mac. It has every feature of Live Home... Read more
FileZilla 3.27.0.1 - Fast and reliable F...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.27.0.1: MSW: Add misssing file to .zip binary package... Read more
Spotify 1.0.59.395. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more

Latest Forum Discussions

See All

The best deals on the App Store this wee...
There are quite a few truly superb games on sale on the App Store this week. If you haven't played some of these, many of which are true classics, now's the time to jump on the bandwagon. Here are the deals you need to know about. [Read more] | Read more »
Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »
Layton's Mystery Journey arrives to...
As you might recall, Layton's Mystery Journey is headed to iOS and Android -- tomorrow! To celebrate the impending launch, Level-5's released a new trailer, complete with an adorable hamster. [Read more] | Read more »
Sidewords (Games)
Sidewords 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Grab a cup of coffee and relax with Sidewords. Sidewords is part logic puzzle, part word game, all original. No timers. No... | Read more »
Noodlecake Games' 'Leap On!...
Noodlecake Games is always good for some light-hearted arcade fun, and its latest project, Leap On! could carry on that tradition. It's a bit like high stakes tetherball in a way. Your job is to guide a cute little blob around a series of floating... | Read more »
RuneScape goes mobile later this year
Yes, RuneScape still exists. In fact, it's coming to iOS and Android in just a few short months. Jagex, creators of the hit fantasy MMORPG of yesteryear, is releasing RuneScape Mobile and Old School RuneScape for mobile devices, complete with... | Read more »
Crash of Cars wants you to capture the c...
Crash of Cars is going full on medieval in its latest update, introducing castles and all manner of new cars and skins fresh from the Dark Ages. The update introduces a new castle-themed map (complete with catapults) and a gladiator-style battle... | Read more »

Price Scanner via MacPrices.net

Apple Move Away from White Label Event Apps C...
DoubleDutch, Inc., a global provider of Live Engagement Marketing (LEM) solutions, has made a statement in the light of a game-changing announcement from Apple at this year’s WWDC conference.... Read more
70 Year Old Artist Creates Art Tools for the...
New Hampshire-based developer Pirate’s Moon has announced MyArtTools 1.1.3, the update to their precision drawing app, designed by artist Richard Hoeper exclusively for use with the 12.9-inch iPad... Read more
Sale! New 2017 13-inch 2.3GHz MacBook Pros fo...
Amazon has new 2017 13″ 2.3GHz/128GB MacBook Pros on sale today for $150 off MSRP including free shipping. Their prices are the lowest available for these models from any reseller: – 13″ 2.3GHz/128GB... Read more
13″ 2.3GHz/128GB Space Gray MacBook Pro on sa...
MacMall has the 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A) on sale for $1219 including free shipping. Their price is $80 off MSRP. Read more
Clearance 2016 12-inch Retina MacBooks, Apple...
Apple recently dropped prices on Certified Refurbished 2016 12″ Retina MacBooks, with models now available starting at $1019. Apple will include a standard one-year warranty with each MacBook, and... Read more
Save or Share
FotoJet Designer, is a simple but powerful new graphic design apps available on both Mac and Windows. With FotoJet Designer’s 900+ templates, thousands of resources, and powerful editing tools you... Read more
Logo Maker Shop iOS App Lets Businesses Get C...
A newly released app is designed to help business owners to get creative with their branding by designing their own logos. With more than 1,000 editable templates, Logo Maker Shop 1.0 provides the... Read more
Sale! New 15-inch MacBook Pros for up to $150...
Amazon has the new 2017 15″ MacBook Pros on sale for up to $150 off MSRP including free shipping: – 15″ 2.8GHz MacBook Pro Space Gray: $2249 $150 off MSRP – 15″ 2.89Hz MacBook Pro Space Gray: $2779 $... Read more
DEVONthink To Go 2.1.7 For iOS Brings Usabili...
DEVONtechnologies has updated DEVONthink To Go, the iOS companion to DEVONthink for Mac, with enhancements and bug fixes. Version 2.1.7 adds an option to clear the Global Inbox and makes the grid... Read more
15-inch 2.2GHz Retina MacBook Pro, Apple refu...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP, and it’s the lowest price available for a 15″ MacBook Pro. An Apple one-year warranty is... Read more

Jobs Board

Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Senior Payments Architect - *Apple* Pay - A...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.