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" ;-)

 
AAPL
$97.03
Apple Inc.
-0.16
MSFT
$44.40
Microsoft Corpora
-0.47
GOOG
$593.35
Google Inc.
-2.63

MacTech Search:
Community Search:

Software Updates via MacUpdate

Audio Hijack Pro 2.11.0 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more
Airfoil 4.8.7 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Microsoft Remote Desktop 8.0.8 - Connect...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
xACT 2.30 - Audio compression toolkit. (...
xACT stands for X Aaudio Compression Toolkit, an application that encodes and decodes FLAC, SHN, Monkey’s Audio, TTA, Wavpack, and Apple Lossless files. It also can encode these formats to MP3, AAC... Read more
Firefox 31.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals... Read more
Little Snitch 3.3.3 - Alerts you to outg...
Little Snitch gives you control over your private outgoing data. Track background activityAs soon as your computer connects to the Internet, applications often have permission to send any... Read more
Thunderbird 31.0 - Email client from Moz...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Together 3.2 - Store and organize all of...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more
Cyberduck 4.5 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more

Latest Forum Discussions

See All

LEX Goes Free For One Day In Honor of Ne...
LEX Goes Free For One Day In Honor of New Update Posted by Jennifer Allen on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Thomas Was Alone Goes Universal, Slashes...
Thomas Was Alone Goes Universal, Slashes Price to $3.99 Posted by Ellis Spice on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Meerkatz Challenge Review
Meerkatz Challenge Review By Jennifer Allen on July 24th, 2014 Our Rating: :: FONDLY PUZZLINGUniversal App - Designed for iPhone and iPad Cute and challenging, Meerkatz Challenge is a fun puzzle game, particularly for fans of... | Read more »
Book Your Appointment with F.E.A.R. this...
Book Your Appointment with F.E.A.R. | Read more »
It Came From Canada: Epic Skater
For all the hate that it gets for being a pastime for slackers, skateboarding really does require a lot of skill. All those flips and spins take real athleticism, and there’s all the jargon to memorize. Fortunately for us less extreme individuals,... | Read more »
Cultures Review
Cultures Review By Jennifer Allen on July 24th, 2014 Our Rating: :: SLOW-PACED EMPIRE BUILDINGiPad Only App - Designed for the iPad Cute it might seem, but Cultures is a bit too slow paced when it comes to those pesky timers to... | Read more »
More Paintings Have Been Added to Paint...
More Paintings Have Been Added to Paint it Back! Posted by Jessica Fisher on July 24th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
The Order of Souls Review
The Order of Souls Review By Campbell Bird on July 24th, 2014 Our Rating: :: STORY GRINDUniversal App - Designed for iPhone and iPad The Order of Souls is a free-to-play, turn-based RPG with a genre-mixing art style, interesting... | Read more »
Revolution 60 Review
Revolution 60 Review By Jordan Minor on July 24th, 2014 Our Rating: :: LASS EFFECTUniversal App - Designed for iPhone and iPad Revolution 60 is a bold, cinematic action game with ambition to spare.   | Read more »
Matter (Photography)
Matter 1.0.1 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.1 (iTunes) Description: Add stunning 3D effects to your photos with real-time shadows and reflections. Export your creations as photos or video loops... | Read more »

Price Scanner via MacPrices.net

Save on 5th generation refurbished iPod touch...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
What Should Apple’s Next MacBook Priority Be;...
Stabley Times’ Phil Moore says that after expanding its iMac lineup with a new low end model, Apple’s next Mac hardware decision will be how it wants to approach expanding its MacBook lineup as well... Read more
ArtRage For iPhone Painting App Free During C...
ArtRage for iPhone is currently being offered for free (regularly $1.99) during Comic-Con San Diego #SDCC, July 24-27, in celebration of the upcoming ArtRage 4.5 and other 64-bit versions of the... Read more
With The Apple/IBM Alliance, Is The iPad Now...
Almost since the iPad was rolled out in 2010, and especially after Apple made a 128 GB storage configuration available in 2012, there’s been debate over whether the iPad is a serious tool for... Read more
MacBook Airs on sale starting at $799, free s...
B&H Photo has the new 2014 MacBook Airs on sale for up to $100 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels... Read more
Apple 27″ Thunderbolt Display (refurbished) a...
The Apple Store has Apple Certified Refurbished 27″ Thunderbolt Displays available for $799 including free shipping. That’s $200 off the cost of new models. Read more
WaterField Designs Unveils Cycling Ride Pouch...
High end computer case and bag maker WaterField Designs of San Francisco now enters the cycling market with the introduction of the Cycling Ride Pouch – an upscale toolkit with a scratch-free iPhone... Read more
Kingston Digital Ships Large Capacity Near 1T...
Kingston Digital, Inc., the Flash memory affiliate of Kingston Technology Company, Inc.,has announced its latest addition to the SSDNow V300 series, the V310. The Kingston SSDNow V310 solid-state... Read more
Apple’s Fiscal Third Quarter Results; Record...
Apple has announced financial results for its fiscal 2014 third quarter ended June 28, 2014, racking up quarterly revenue of $37.4 billion and quarterly net profit of $7.7 billion, or $1.28 per... Read more
15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Senior Interaction Designer, *Apple* Online...
**Job Summary** Apple is looking for a hands on Senior…will be a key player in designing for the Apple Online Store. The ideal designer will have a Read more
*Apple* Sales Chat Rep - Apple (United State...
…is looking for motivated, outgoing, and tech savvy individuals who want to offer Apple Customers an unparalleled customer experience over chat. At Apple , we believe Read more
Mac Expert - *Apple* Online Store Mexico -...
…MUST be fluent in English and Spanish to be considered for this position At Apple , we believe that hard work, a fun environment, creativity and innovation fuel the Read more
*Apple* Industrial Design CAD Sculptor - App...
**Job Summary** The Apple Industrial Design team is looking for a CAD sculptor/Digital 3D modeler to create high quality CAD models used in the industrial design process Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.