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
$101.63
Apple Inc.
+0.00
MSFT
$46.24
Microsoft Corpora
+0.00
GOOG
$573.10
Google Inc.
+0.00

MacTech Search:
Community Search:

Software Updates via MacUpdate

Adobe Acrobat Pro 11.0.09 - Powerful PDF...
Adobe Acrobat allows users to communicate and collaborate more effectively and securely. Unify a wide range of content in a single organized PDF Portfolio. Collaborate through electronic document... Read more
Adobe Reader 11.0.09 - View PDF document...
Adobe Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
iFFmpeg 4.6.1 - Convert multimedia files...
iFFmpeg is a graphical front-end for FFmpeg, a command-line tool used to convert multimedia files between formats. The command line instructions can be very hard to master/understand, so iFFmpeg does... Read more
NTFS 11.3.62 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more
OS X Yosemite 10.10 DP8 - Developer Prev...
Note: This is a Developer Preview. You must be a registered Apple Mac Developer to download this update. You can also sign up for the free OS X Beta Program to download and preview public beta... Read more
FotoMagico 4.5 - Powerful slideshow crea...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Screenshot Path 1.2.1 - Change the defau...
Screenshot Path lets you change the folder where OS X saves screenshots. Screenshots are saved by default to the user’s desktop. This is handy for the occasional screenshot but those looking to take... Read more
Fantastical 1.3.16 - Create calendar eve...
Fantastical 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 details... Read more
GIMP 2.8.14 - Powerful, free image editi...
GIMP is a multi-platform photo manipulation tool. GIMP is an acronym for GNU Image Manipulation Program. The GIMP is suitable for a variety of image manipulation tasks, including photo retouching,... Read more
HoudahSpot 3.9.3 - Advanced front-end fo...
HoudahSpot is an advanced file search tool built upon MacOS X Spotlight. Spotlight unleashed Create detailed queries to locate the exact file you need Narrow down searches. Zero in on files Save... Read more

Latest Forum Discussions

See All

Vizzywig 4K (Photography)
Vizzywig 4K 1.0 Device: iOS iPhone Category: Photography Price: $999.99, Version: 1.0 (iTunes) Description: REQUIRES: iOS 7 on iPhone 5S with 32GB or 64GB. (Do not use iOS 8)The world's FIRST mobile 4K video capture, editing and... | Read more »
The Sleeping Prince Review
The Sleeping Prince Review By Jennifer Allen on September 15th, 2014 Our Rating: :: RESTRICTIVE KINGDOM SAVINGUniversal App - Designed for iPhone and iPad The Sleeping Prince looks and feels great to play, but its lack of peril and... | Read more »
It Came From Canada: Terra Battle
In some way or another, most Japanese RPGs owe something to Final Fantasy. But with Terra Battle, the now-common mix of Western medieval fantasy with Eastern anime aesthetic feels earned. After all, its developer, Mistwalker, was founded by the... | Read more »
Five Nights at Freddy’s Review
Five Nights at Freddy’s Review By Rob Thomas on September 15th, 2014 Our Rating: :: FIVE FRIGHTS AT FREDDY'SUniversal App - Designed for iPhone and iPad Can you survive five nights as the new night watchman of Freddy Fazbear’s... | Read more »
Phantom Rift Review
Phantom Rift Review By Nadia Oxford on September 15th, 2014 Our Rating: :: FRIENDLY PHANTOMUniversal App - Designed for iPhone and iPad Despite a snag here and there, Phantom Rift is a well-crafted and imaginative adventure RPG.   | Read more »
Phantom Rift – Tips, Tricks, Strategies,...
Hello, Wanderers: | Read more »
Meet the Newest Character for Temple Run...
Meet the Newest Character for Temple Run 2, from National Geographic Kids’ Action-Adventure Book Posted by Jessica Fisher on September 15th, 2014 [ | Read more »
Battle Riders Review
Battle Riders Review By Jordan Minor on September 15th, 2014 Our Rating: :: UNTWISTED METALUniversal App - Designed for iPhone and iPad BattleRiders has cool car combat, but it could be crazier.   | Read more »
Rapture - World Conquest (Games)
Rapture - World Conquest 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: The End is coming! Bombard the globe with devastating miracles and decimate the enemy civilizations. Guide your... | Read more »
TRANSFORMERS: Age of Extinction Update A...
TRANSFORMERS: Age of Extinction Update Adds New Levels, a New Boss, and Special Events Posted by Jessica Fisher on September 15th, 2014 [ p | Read more »

Price Scanner via MacPrices.net

Free GIMP Professional Grade Graphics App Ver...
The latest 2.8.14 version of the oddly-named GIMP (acronym for: GNU Image Manipulation Program) open source, high-end image editing and creation alternative to Adobe’s Photoshop and refuge from... Read more
10% off iPhone 6 and 6 Plus Otterbox cases
Get 10% off on popular Otterbox iPhone 6 and iPhone 6 Plus cases at MacMall through September 19th. Use code OTTERBOX10 to see the discount. Read more
15-inch MacBook Pros on sale for up to $125 o...
Amazon has the new 2014 15″ Retina MacBook Pros on sale for up to $125 off MSRP including free shipping: - 15″ 2.2GHz Retina MacBook Pro: $1899.99 save $100 - 15″ 2.5GHz Retina MacBook Pro: $2374... Read more
27-inch 3.2GHz iMac on sale for $1698, $101 o...
Abt has the 27″ 3.2GHz iMac on sale for $1698 including free shipping. Their price is $101 off MSRP. Read more
More To Making A Larger iPad Than Expanded Sc...
CNET’s Ross Rubin has posted a thoughtful analysis of prospects for a larger display iPad Pro, noting that Microsoft and Samsung currently have the large-display touchscreen tablet category to... Read more
SwiftKey Keyboard Finally Coming To iPhone An...
At the TechCrunch Disrupt event in San Francisco, Swiftkey unveiled the first details about SwiftKey Keyboard for iPhone, iPad & iPod touch. SwiftKey’s philosophy is that you should be able to... Read more
Save $75 on the 16GB iPad mini with Retina Di...
Best Buy has the 16GB iPad mini with Retina Display on sale for $324.99 on their online store for a limited time. Their price is $75 off MSRP, and it’s the lowest price available for this mini.... Read more
21-inch 1.4GHz iMac on sale for $979, $120 of...
B&H Photo has the new 21″ 1.4GHz iMac on sale for $979.99 including free shipping plus NY sales tax only. Their price is $120 off MSRP. B&H will also include free copies of Parallels Desktop... Read more
Apple restocks refurbished 21-inch 1.4GHz iMa...
The Apple Store has restocked Apple Certified Refurbished 21″ 1.4GHz iMacs for $929 including free shipping plus Apple’s standard one-year warranty. Their price is $170 off the cost of new models,... Read more
13-inch 2.6GHz/256GB Retina MacBook Pro on sa...
Adorama has the 13″ 2.6GHz/256GB Retina MacBook Pro on sale for $1379 including free shipping plus NY & NJ sales tax only. Their price is $120 off MSRP, and it’s the lowest price available for... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.