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

Viber 11.9.1 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Vallum 3.3.2 - $15.00
Vallum is a little tool that helps you monitor and block apps connections and throttle apps bandwidth. It is able to intercept connections at the application layer, and hold them while you decide... Read more
Microsoft OneNote 16.31 - Free digital n...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Apple Pages 8.2.1 - Apple's word pr...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Numbers 6.2.1 - Apple's spreadsheet...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
f.lux 39.9873 - Adjusts the color of you...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
Deeper 2.5.0 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
NTFS 15.5.71 - Provides full read and wr...
NTFS breaks down the barriers between Windows and macOS. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS. Write, edit, copy, move, delete files on NTFS... Read more
MTR 5.3.0.0 - The Mac's oldest and...
MTR (was MacTheRipper)--the Mac's oldest and smartest DVD-backup app. MTR - the complete toolbox, not a one-trick, point-and-click extractor. MTR is intended for making fair-use, backup copies of... Read more
Keynote 9.2.1 - Apple's presentatio...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more

Latest Forum Discussions

See All

Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »
Intense VR first-person shooter Colonicl...
Our latest VR obsession is Colonicle, an intense VR FPS, recently released on Oculus and Google Play, courtesy of From Fake Eyes and Goboogie Games. It's a pulse-pounding multiplayer shooter which should appeal to genre fanatics and newcomers alike... | Read more »
PUBG Mobile's incoming update bring...
PUGB Mobile's newest Royale Pass season they're calling Fury of the Wasteland arrives tomorrow and with it comes a fair chunk of new content to the game. We'll be seeing a new map, weapon and even a companion system. [Read more] | Read more »

Price Scanner via MacPrices.net

Weekend Sale: Apple AirPods Pro for $234.98 a...
Abt Electronics has Apple’s new AirPods Pro in stock and on sale today for $234.98 including free shipping and free returns. Their price is $15 off Apple’s MSRP for these AirPods and tie Amazon... Read more
New 2019 16″ MacBook Pros on sale for $100 of...
Apple Authorized Reseller Adorama has new 2019 16″ MacBook Pros on sale today for $100 off Apple’s MSRP, each including free shipping. In addition, Adorama charges sales tax for NY & NJ residents... Read more
Apple Watch Series 3 GPS models on sale for l...
Amazon has Apple Watch Series 3 GPS models on sale starting at only $179. There prices are the lowest we’ve ever seen for these models from any Apple reseller. Choose Amazon as the seller rather than... Read more
iOS Bug In Facebook News Feed Lets Device Ca...
NEWS: 11.15.19- Users of the Facebook social media platform’s mobile app running on iOS devices won’t, like, this piece of news one bit in where a bug in the News Feed gave access to the camera... Read more
16″ MacBook Pros on sale! Preorder at Amazon...
Apple’s new 16″ MacBook Pros were only introduced yesterday, but Amazon is already offering a $100 discount on preorders. Prices for the base 6-Core 16″ MacBook Pros start at $2299: – 2019 16″ 2.6GHz... Read more
Use our exclusive MacBook Price Trackers to f...
Our Apple award-winning MacBook price trackers are the best place to look for the best sales & lowest prices on new and clearance MacBook Airs and MacBook Pros–including Apple’s new 16″ MacBook... Read more
New November Verizon iPhone deal: Get an iPho...
Verizon has the 64GB iPhone Xr on sale for 50% off for a limited time, plus they will include a free $200 prepaid MasterCard and a free Amazon Echo Dot. That reduces their price for the 64GB iPhone... Read more
Apple cuts prices on clearance, refurbished 2...
Apple has clearance 2018 15″ 6-Core Touch Bar MacBook Pros, Certified Refurbished, now available starting at only $1829. Each model features a new outer case, shipping is free, and an Apple 1-year... Read more
Up to $450 price drop on clearance 15″ MacBoo...
B&H Photo has dropped prices Apple’s 2019 15″ 6-Core and 8-Core MacBook Pros by $400-$450 off original MSRP, starting at $1999, with free overnight shipping available to many addresses in the US... Read more
Here’s how to save $200 on Apple’s new 16″ Ma...
Apple has released details of their Education discount associated with the new 2019 16″ 6-Core and 8-Core MacBook Pros. Take $200 off the price of the new 8-Core model (now $2599) and $200 off the 16... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**746887BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001512-Ankeny-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**746836BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 000341-Scranton-Store **Job Description:** **What Read more
QA Manager, *Apple* - CBS Corporation (Unit...
# QA Manager, Apple **REF#:** 35331 **CBS BUSINESS UNIT:** CBS Interactive **JOB TYPE:** Full-Time Staff **JOB SCHEDULE:** **JOB LOCATION:** Burbank, CA **ABOUT Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744315BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000662-Auburn AL-Store **Job Description:** At Best Read more
Nurse Practitioner - Field Based (San Bernard...
Nurse Practitioner - Field Based (San Bernardino, CA, Apple Valley, Hesperia) **Location:** **United States** **New** **Requisition #:** PS30312 **Post Date:** 4 Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.