TweetFollow Us on Twitter

Safe Haquery Volume Number: 17 (2001)
Issue Number: 2
Column Tag: Mac OS X

The Art of Safe Haquery, Categorically Speaking

By Andrew Stone

The Subtitle in Italics

The Cocoa newcomer is constantly barraged with enthusiasm and praise of the Cocoa APIs by the early Cocoa adopters. These lofty feelings are indeed merited by the powerful and easy to use Cocoa development environment. Although Cocoa comes in both Java and Objective-C flavors, it's Objective-C which shines for ease of adding new functionality to existing classes through the Objective-C language mechanism known as Categories. This article will show you how to add and change functionality of an existing Cocoa class, the NSSavePanel, by using a category, a subclass and a tool which reveals all the methods in a class, classdump.

First, I must explain the spelling of haque and haquery, and how that came to be. In the field of Computer Science, we lovingly refer to the art of clever programming as hacking. But alas, the free press (albeit, controlled by only 5 men) has taken to using the term "hacker" for people engaged in unlawful computer cracking. Take back our term! By adding a slightly continental twist, voilà, le haque!

Before we embark on how to go below the API to accomplish tasks unaccomplishable through normal means, I am required by the unwritten laws of the unformed guild of responsible programmers to give my short lecture on using undocumented, unexposed API: Don't do it - you'll regret it - your program will break in a future release. The lecture always sounds better in the positive: if you strictly adhere to the Cocoa API, then not only will your application continue to function in future releases, it will actually run better as the dynamically loaded frameworks it depends on receive bug fixes from Apple.

That said, when you've decided that the only way to obtain behavior you desire is by using undocumented API, you need to make that code as safe as possible by assuming that the Apple implementation will change underneath you. We'll go over the tricks and tips when we look at the code below.

First, I wanted the ability to let the user create a new directory in a preset folder. I wanted to reuse the NSSavePanel because it knows how to get the name of a new directory and run as a sheet, Cocoa style. But the SavePanel is designed to allow the user to browse the directory structure and I don't want to allow that. When the SavePanel is in its "minimum" state with the File browser hidden, it's almost perfect for my needs. By disabling both the "reveal the browser" button and the Favorites popup, the panel is perfect for my needs:


Figure 1. This save panel has been tweaked to allow the user to create a new folder in the current folder only - there is no way for the user to navigate to other folders.

Unfortunately, there is no API to make the SavePanel not display the browser, New Folder button, Favorites popup, and other interface items which allow the user to leave the directory explicitly set by the program. So - how the heck can one programmatically shrink up the save panel? The best place to start looking is inside the NSSavePanel.nib file - which lives in /System/Library/Frameworks/AppKit.framework/Resources/English.lproj. Double-click that file to launch InterfaceBuilder.

We notice that the UI objects we need to mess with have outlets in the NSSavePanel class:

  • _favoritesPopup is the popup we need to disable
  • _expandButton is the button which makes the browser come and go

We also note that the expandButton's target is the SavePanel, and its action is: _expandPanel:. Right away, the leading underscore tips us off that this is an undocumented method. We do not want to call this directly; its name may change. Here's the trick: simply ask the expandButton to performClick:! That way, should Apple change the method which that button sends, our code will still work correctly. We are only in trouble if they remove _expandButton or change its name. Further safety could be had by noting the tag of the _expandButton in InterfaceBuilder, and using NSView's "viewWithTag" to find the button - thus never referring to the button by name. However, the creator of the nib file didn't assign a tag to either the expand button or the favorites popup, so that technique is useless here. You could also do a recursive search of the panel's contentView's subviews for a view of class NSPopUpButton to find the _favoritesPopup, but that would break if Apple added another popup to the panel.

Now, open the header file for NSSavePanel, found in:

/System/Library/Frameworks/AppKit.framework//Headers/NSSavePanel.h

You'll see the whole API - but here's what's interesting for us:

@interface NSSavePanel : NSPanel
{
    /*All instance variables are private*/
// Apple is telling you NOT TO RELY ON ANYTHING HERE!

    NSBrowser      *_browser;
    ...
    id                  _expandButton;
    ...
    id                  _favoritesPopup;
    ...
    struct __spFlags {
    ...
        unsigned int       collapsed:1;
    ...
    }                   _spFlags;
    ...
}

So, it looks like there is a way to determine if the panel is collapsed (_spFlags.collapsed), and we can disable the favorites button (_favoritesPopup) as well as ask the expandButton (_expandButton) to pretend the user clicked it.

We'll write a simple method to use in our application which checks the collapsed state of the panel, collapses it if it is expanded, and disables the folder navigation buttons. Because we're adding functionality and don't need to change any existing NSSavePanel methods, we'll use a category.

A category looks similar to class implementations, except:

  1. a category name comes after the class name
  2. no new instance variables can be declared

Here's our interface declaration:

@interface NSSavePanel(SuperTrickyStuff)
- (void)prepareToDisplayOnlyName;
@end

So a client of our SavePanel, who wants the collapsed version, will use calling code similar to this:

- (IBAction)newGalleryAction:(id)sender {

  // save panel configured for only creating new folders in the current one
  // Because we mess with this panel, we want our own copy so this doesn't
  // affect normal save panels used in the rest of the application:

    static NSSavePanel *savepanel = nil;
    if (!savepanel) {
        // If the save panel is to be reused, you must retain it!
        savepanel = [[NSSavePanel savePanel]retain];
    }
   // establish the folder where you want users to create a new folder:
   // note how subclasses could redefine where the saveDirectory is:
    [savepanel setDirectory:[self saveDirectory]];

   // Make the savepanel not require a filetype
   //  (directories don't require a path extension)
    [savepanel setRequiredFileType:@""];
    
    // Here's our invocation of our new category method
    // see explanation below as to why we use performSelector:withObject:afterDelay:
    [savepanel performSelector:@selector(prepareToDisplayOnlyName) withObject:nil afterDelay:.01];

   // following the Cocoa model of running save sheets, use NSSavePanel's
   // new API to run the save panel window modally:
   // This establishes the callback method, delegate, and context information
  // for use when, and if, the user ever finishes running the save panel:

    [savepanel beginSheetForDirectory:[self saveDirectory] file:@""
modalForWindow:[_controller window] modalDelegate:self
didEndSelector:@selector(didEndGallerySheet:returnCode:contextInfo:) contextInfo:NULL];

}

The only tricky part about calling our new category method is that we want it to happen AFTER the window has already come up on screen. And since the call to beginSheetForDirectory:file:modalForWindow:modalDelegate:didEndSelector: returns immediately, we need to schedule our call to prepareToDisplayOnlyName to occur AFTER the sheet appears on the window. Ideally you would do it before the window comes up so the user won't see the window collapse before her eyes - but it turns out that the Save panel does its own setting of the collapsed state if the user last collapsed another Save panel in the application. Once the save panel is displayed, then the programmatic "clicking" of the expand button will work correctly. NSObject defines a method, performSelector:withObject:afterDelay: for times when you need to schedule a call to happen after the current event loop goes around. If I tried to collapse it too early, it would further collapse and disappear!

Our implemenation of our Save panel category is also very straighforward - 8 lines of code:

@implementation NSSavePanel(SuperTrickyStuff)

// the user must be unable to use the Favorites popup 
// and the expand button, so we disable them:

- (void)disableButtons {
   [_favoritesPopup setEnabled:NO];
   [_expandButton setEnabled:NO];
}

// we temporarily enable the expand button just so we can send it the method
// performClick:

- (void)collapse:(id)sender {
   [_expandButton setEnabled:YES];
   [_expandButton performClick:nil];
   [self disableButtons];
}

// this is the only method we expose - and 
// all you need to call to set up the panel:

- (void)prepareToDisplayOnlyName {
    if (!_spFlags.collapsed) {
        [self collapse:nil];
    } else [self disableButtons];  
   // if it's already collapsed, we want the buttons disabled
}

Note that we need to call this every time we run the panel, because if the user sets another SavePanel into full file browser mode, the next time we run our save panel, it will once again try to set itself to the expanded state because of the inner workings of the NSSavePanel.

My next SavePanel challenge arose when the behavior of NSSavePanel changed for the worse in Public Beta. Now, when you go to save a file, all existing files are "disabled" and dimmed, so it's very hard to overwrite an existing file - you have to painstakingly and correctly type the exact name of the preexisting file. It used to be that you could simply double-click an existing file to save over it, and that behavior is what we want to restore to the panel. When outputting HTML, users may tweak something and then want to output the new version to a preexisting directory, essentially writing over the previous files. Since users complained about the apparent inability to write over old files, I decided it was time to peer deeper into the API.


Figure 2. This save panel has been tweaked to allow the user to select existing files - normally, they are disabled and unselectable.

After finding no available API to do what I wanted, I approached this by researching the private methods of NSSavePanel to try and deduce how this enabling/disabling was occurring. A piece of perennial software that has been companion to NeXTStep and OpenStep developers for years is now available for Cocoa: class-dump. This command line tool takes advantage of the Objective-C runtime to spit out all the instance and class methods in a program, bundle or framework. My friends at www.stepwise.com have a version via SoftTrak updated for OS X by James McIlrae: http://www.stepwise.com/SoftTrak/ and search for "class-dump". Once again, let me repeat that any developer who uses undocumented API deserves the headaches thus incurred! By using class-dump on the AppKit framework and searching for NSSavePanel, I found two methods that seemed extremely related to what I was trying to do:

- _itemHit:fp12;
- (BOOL)_enableLeaf:(id)fp12 container:(id)fp16 {

Moreover, from the nib file, I learned that the filename field is actually an NSForm. I also guessed correctly that the browser sends the method _itemHit: to the NSSavePanel when you click an item in the browser. To do what we want to do, we need to change _itemHit. Because we have absolutely no idea what the original implementation of _itemHit: is, we need to be able to call the original implementation. Because of this, we can't use a category, which would hide the original implementation. Instead, we create a subclass of NSSavePanel, SaveOverPanel, which allows us to call super's implementation to get the real work done, and then afterwards, monkey with the UI to obtain the behavior we desire.

How can we be safe in this instance? First off, our implementation is totally passive. By passive, I mean we are not assuming that NSSavePanel will respond to any undocumented method. Instead, if and only if the NSSavePanel calls _itemHit:, we call super to let the panel do the work. If Apple takes out this method, our subclass's implementation will not get called. Moreover, we'll test each of our UI elements to see if they are still the same class using isKindOfClass:. If their class changes, our code will simply call super's implementation. So all we really need to do is return YES for whether any particular node is enabled, and then when a user clicks on an item, transfer that string to the filename field.

// define a subclass of NSSavePanel with no new instance variables:
@interface SaveOverPanel : NSSavePanel

@end

// reveal the secret method so the compiler will not complain:
@interface NSSavePanel(superSecret)
- _itemHit:fp12;
@end

// the few lines of code needed to do what we want:

@implementation SaveOverPanel

- (BOOL)_enableLeaf:(id)fp12 container:(id)fp16 {
   // we want every cell to be enabled:
   // should Apple take out this method, then it will never be called
   // and our program continues to work, but without our new functionality
   return YES;
}

// the NSBrowser is the sender:
- _itemHit:fp12 {
    // first be absolutely sure we know what kinds of objects we think we have:
    if ([fp12 isKindOfClass:[NSBrowser class]] && [_form isKindOfClass:[NSForm class]]) {
        NSBrowserCell *cell = [fp12 selectedCell];

        // by calling super, we insure any internal work is done right:
        id returnValue = [super _itemHit:fp12];

        // if we have a leaf node, ie file, transfer that to filename field:
        if ([cell isLeaf]) [[_form cellAtIndex:0] setStringValue:[cell stringValue]];

        // return what we got back from super, whatever it is ;-) :
        return returnValue;
    } else return [super _itemHit:fp12];
}

@end

To use this type of Savepanel, just include the new class when you create the panel:

- (IBAction)createWebPagesAction:(id)sender {
        static SaveOverPanel * savepanel = nil;
        if (!savepanel)  {
            savepanel = [[SaveOverPanel savePanel]retain];
        }
        ...
}

Conclusion

There are many good programming practices, but using undocumented API is not one of them! However, if your users demand certain functionality and no exposed API exists for that functionality, you might want to tread this dangerous ground. If you apply certain preventative techniques to your haquery, you can minimize side effects and future problems.


Andrew Stone, <andrew@stone.com>, is Chief Executive Haquer of Stone Design Corp - a New Mexican software house in its 13th year of producing Cocoa software.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

BetterTouchTool 2.07 - Customize Multi-T...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
BetterTouchTool 2.07 - Customize Multi-T...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
PDFpen 8.3.2 - $74.95
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
DiskCatalogMaker 6.5.20 - Catalog your d...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Things 2.8.9 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
PDFpenPro 8.3.2 - $124.95
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Create fillable forms and tables of content... Read more
Things 2.8.9 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
DiskCatalogMaker 6.5.20 - Catalog your d...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
PDFpenPro 8.3.2 - $124.95
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Create fillable forms and tables of content... Read more
PDFpen 8.3.2 - Edit and annotate PDFs wi...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more

Latest Forum Discussions

See All

Pokémon GO Generation 2 evolution guide
At long last, Niantic Labs finally unleashed the Generation 2 Pokémon into the wild. Pokémon GO trainers are scrambling to grab up this new set of 80 Pokémon. There are some special new tricks required to catch all of these new beasties, though.... | Read more »
The best new games we played this week
It feels as though the New Year got off to a creaking start as far as mobile games go, but that's changed over the past few weeks. The last few days alone have seen the debut of a number of wonderful games, so we thought we'd take the time to... | Read more »
Recruit more scallywags and discover new...
Get ready to show off your sea legs all over again in Oceans & Empires’ new grand update, which aims to make the act of rising to the role of seven seas ruler even more fresh and appealing, thanks to a richness of new content on both iOS and... | Read more »
Mage the Ascension: Refuge (Games)
Mage the Ascension: Refuge 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The groundbreaking roleplaying game Mage: The Ascension manifests in our turbulent present with Refuge, an... | Read more »
Vampire: Prelude (Games)
Vampire: Prelude 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The classic roleplaying game Vampire: The Masquerade returns to digital games with a Prelude of things to come. Experience a... | Read more »
Digby Forever Guide: How to dig to the d...
Digby Forever is a sparkling homage to arcade classics, and while you may be tiring of the number of arcade games being thrown at you, this endless digger finds many ways to stand out from the rest of the pack. The game manages to be challenging... | Read more »
The best sales on the App Store this wee...
It's been quite the week in mobile games, but if the latest releases(there were some pretty darn good ones, in case you missed out) aren't really doing the trick, perhaps some of these discounted games will. Many of these premium games had their... | Read more »
Why the new Fire Emblem Heroes update sh...
It’s exciting to see Nintendo delving into the mobile sphere, regardless of whether it’s to give fans another platform to enjoy their fans or simply a sound business venture. Two of the company's announced mobile games have finally come to... | Read more »
New Fire Emblem Heroes update adds new h...
Fire Emblem Heroes received a sizeable update first thing this morning. The update features a batch of fresh content along with a few updates to the game's systems. [Read more] | Read more »
The Deep Paths (Games)
The Deep Paths 1.0 Device: iOS iPhone Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: 25% off launch sale!!! The Deep Paths: Labyrinth Of Andokost is a first-person, dungeon crawling RPG, with traditional grid-based... | Read more »

Price Scanner via MacPrices.net

12-inch 1.1GHz Retina MacBooks on sale for $1...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1149 $150 off MSRP - 12″ 1.1GHz... Read more
InTouch Health Expands iOS And Windows Produc...
Specialty telehealth enterprise provider InTouch Health has announced an expanded range of FDA Class I listed medical devices and software solutions for ambulatory, non-acute and non-emergent... Read more
iMobie Airs World’s 1st iCloud Manager with M...
iMobie Inc., an Apple-related software company, announced their newly-updated iPhone manager AnyTrans with exclusive feature to sync and manage contents across multiple iCloud accounts. With it,... Read more
New Proactive Apple Support Professional Cert...
Watchman Monitoring has announced Proactive Support Professional Certification at MacTech Pro. Watchman Monitoring is a premier Proactive Support Software as a Service (SaaS) tool for IT... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $100 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more
Back in stock: Apple refurbished 13-inch Reti...
Apple has Certified Refurbished 2015 13″ Retina MacBook Pros available for up to $360 off original MSRP, starting at $1099. An Apple one-year warranty is included with each model, and shipping is... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
2.6GHz Mac mini on sale for $559, $140 off MS...
Guitar Center has the 2.6GHz Mac mini (MGEN2LL/A) on sale for $559.99 including free shipping. Their price is $140 off MSRP, and it’s the lowest price available for this model. Read more
21-inch Apple iMacs on sale for $100-$150 off...
B&H Photo has 21″ iMacs on sale for up to $150 off MSRP, each including free shipping plus NY sales tax only: - 21″ 3.1GHz iMac 4K: $1349 $150 off MSRP - 21″ 2.8GHz iMac: $1189 $110 off MSRP - 21... Read more
Type Nine Keyboard 2.0 for iOS – World’s Firs...
Copenhagen, Denmark based indie developer Rasmus Porsager has released Type Nine Keyboard 2.0, an update to his keyboard utility for iOS devices. Type Nine Keyboard combines a t9 keypad layout with... Read more

Jobs Board

*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* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Lead Senior *Apple* (Mac) Administrator - S...
…but also to protect them. Position Summary: SC3 is actively seeking a Senior Apple (Mac) Administrator that will be responsible for providing Apple Mac Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.