Quickies for Bindings

Borkware »
Quickies »
Quickies for Bindings

General

Binding to your AppController [permalink]
If you have an AppController object in your nib file, and it's not File's Owner, but you want to use bindings with it, you can use an NSObjectController :
1. Make an IBOutlet in your controller to point to the NSObjectController
2. Drag an NSObjectController into the nib
3. Add the names of the properties you're going to be binding with
4. in AppController's awakeFromNib method, do [objController setContent: self];
By setting the content value in awakeFromNib helps prevent a retain cycle which can lead to memory leaks.
Changing the "Not Applicable" text in tableviews [permalink]
Sometimes you want to bind a tableview column to objects that might not support that particular binding (like having an uber-overview tableview for core data entities that don't all share the same attributes). If your column has a numeric formatter, IB won't let you specify a string for the "not applicable" value, so you end up with a really ugly tableview covered in "Not Applicable"s
Put this in a convenient place:
```
+ (void) initialize
{
    [NSTextFieldCell setDefaultPlaceholder: @""
                               forMarker: NSNotApplicableMarker
                             withBinding: NSValueBinding];

} // initialize
```
Handling KVO with arrays [permalink]
When you insert or remove objects in a KVO compliant manner, your observer is informed of the specifics of the change via the change dictionary:
```
- (void) observeValueForKeyPath: (NSString *) keyPath
                       ofObject: (id) object
                         change: (NSDictionary *) change
                        context: (void *) context
```
The NSKeyValueChangeKindKey key in the dictionary tells you if the change was an insertion (NSKeyValueMinusSetMutation) or a deletion (NSKeyValueIntersectSetMutation)
If it is an insertion, the NSKeyValueChangeIndexesKey is an index set that contains the index of the inserted object. You can query the collection for the object at that index to get the new object.
if it a deletion, the NSKeyValueChangeIndexesKey tells you the index where the object was deleted from, and the NSKeyValueChangeOldKey contains an NSArray of objects which were removed, in case you want to hang on to it, or use it to clean out some of your data structures.
Handling unknown keys with KVC [permalink]
Override valueForUndefinedKey::
```
- (id) valueForUndefinedKey: (NSString *) key
{
    id value;
    value = [self lookUpValueUsingSomeOtherMechanism: key];

    if (value == nil) {
        value = [super valueForUndefinedKey: key];
    }

    return (value);

} // valueForUndefinedKey
```
Some handy uses for this is using the user defaults for storing values (you can use the key directly to [NSUserDefaults stringForKey:], or use it to query the contents of an NSDictionary
The counterpart for this is
- (void) setValue: (id) value forUndefinedKey: (NSString *) key, which you can use to stash stuff into user prefs or a dictionary.

Hooking up a search box to your array controller [permalink]
Tiger supposedly does this for us. If you're having to support Panther as well, here's a way to have a search box filter the contents managed by an NSArrayController.

In the header file

#import <Cocoa/Cocoa.h>

@interface BWSearchArrayController : NSArrayController
{
    NSString *searchString;
}

- (IBAction) search: (id) sender;

@end // BWSearchArrayController

and then in the implementation:

// returns an array containing the content of the objects arranged
// with the user's critera entered into the search box thingie

- (NSArray *) arrangeObjects: (NSArray *) objects
{
    // result of the filtering
    NSArray *returnObjects = objects;

    // if there is a search string, use it to compare with the
    // search field string

    if (searchString != nil) {

        // where to store the filtered
        NSMutableArray *filteredObjects;
        filteredObjects = [NSMutableArray arrayWithCapacity: [objects count]];

        // walk the enumerator
        NSEnumerator *enumerator = [objects objectEnumerator];

        id item; // actully BWFileEntries
        while (item = [enumerator nextObject]) {

            // get the filename from the entry
            NSString *filename;
            filename = [item valueForKeyPath: @"fileName"];

            // see if the file name matches the search string
            NSRange range;
            range = [filename rangeOfString: searchString
                              options: NSCaseInsensitiveSearch];

            // found the search string in the file name, add it to
            // the result set
            if (range.location != NSNotFound) {
                [filteredObjects addObject: item];
            }
        }

        returnObjects = filteredObjects;
    }

    // have the superclass arrange them too, to pick up NSTableView sorting
    return ([super arrangeObjects:returnObjects]);

} // arrangeObjects

and then to set the search string:

- (void) setSearchString: (NSString *) string
{
    [searchString release];

    if ([string length] == 0) {
        searchString = nil;
    } else {
        searchString = [string copy];
    }

} // setSearchString


- (void) search: (id) sender
{
    [self setSearchString: [sender stringValue]];
    [self rearrangeObjects];

} // search

KVO Array controller gotcha [permalink]
If you're doing KVO and don't override observeValueForKeyPath:ofObject:change:context:, (or you do override it but don't handle your callbacks) you'll generally get an exception. This trains you to do it right and never call super for the callbacks you're handling, or you'll get an exception.
Except if you've added KVO to a subclass of NSArrayController (and possibly all controller types), and don't call super's observeValueForKeyPath:ofObject:change:context:, bindings won't work at all, with no warning/notice/nothing. (Courtesy of Duncan Wilcox)
Manually creating a binding [permalink]
```
[imageView bind: @"valuePath"
           toObject: imagesController
           withKeyPath: @"selection.fullPath"
           options: nil];
```
In Interface Builder, "Bind To" corresponds to imagesController, "Controller Key" would be selection, and "Model Key Path would be fullPath.
Use
```
    [imageView unbind: @"valuePath"];
```
to remove a binding.

Minimal KVC accessors for arrays [permalink]
For an attribute named "layers", here are the KVC accessors to write to let observers react to object addition and removal:

- (NSArray *) layers
{
    return (layers);
} // layers


- (void) insertObject: (id) obj
      inLayersAtIndex: (unsigned) index
{
    [layers insertObject: obj  atIndex: index];
} // insertObjectInLayers


- (void) removeObjectFromLayersAtIndex: (unsigned) index
{
    [layers removeObjectAtIndex: index];
} // removeObjectFromLayersAtIndex

Monitoring one array from two controllers [permalink]
If you're wanting to use two NSArrayControllers to monitor one NSMutableArray, you'll need to use each of the controller's contentArray binding. Just using the content outlet (or setContent: call), you'll only get arrangedObjects updates from one controller. (thanks to Duncan Wilcox for this one)
NSSearchField filtering for an NSArrayController [permalink]
In Tigger, NSSearchField can now automagically filter an array via IB magic.
In Interface Builder, drag over the NSSearchField, and bind the predicate like this:
- Bind To: your array controller
- Controller Key: filterPredicate
- Predicate Format: what contains[c] $value (assuming the attribute you're filtering is called what)
If you're wanting to be able to filter on multiple attributes, make additional predicate bindings. Doing the CoreData option-drag of an entity into IB is really handy - take a peek at how it configures the search field for filtering multiple columns.

Observing using KVO [permalink]
Register an observer with something like:

    [searchArrayController addObserver: self
                           forKeyPath: @"selectionIndexes"
                           options: NSKeyValueObservingOptionNew
                           context: NULL];

This makes self an observer of the searchArrayController. We'll get notified when the selectionIndexes value changes, and we'll be notified with the new value.

When the notification happens, this method (invoked against the self used earlier) is invoked:

- (void) observeValueForKeyPath: (NSString *) keyPath
                       ofObject: (id) object
                         change: (NSDictionary *) change
                        context: (void *) context
{
} // observeValueForKeyPath

and you can poke around the arguments to see wha'happened.

Registering default user defaults [permalink]
Here is one way to register the "factory settings" for your user defaults (preferences / configurations). You will pick up these values automagically via bindings to the Shared Defaults.

- (void) setDefaultPrefs
{
    NSMutableDictionary *dictionary = [NSMutableDictionary dictionary];

    [dictionary setObject: NSLocalizedString(@"BorkDown", nil)
                forKey: @"menuTitle"];

    [dictionary setObject: NSLocalizedString(@"Time has run out.", nil)
                forKey: @"alertWindowText"];

    // and any other preferences you might have

    [[NSUserDefaults standardUserDefaults]
        registerDefaults: dictionary];

} // setDefaultPrefs

Using KVO for whole-object observation [permalink]
I've got an object that has a bunch of individual attributes that are controlled by an inspector, and another object (a view that holds that object) which needs to redraw when something changes in the object, but it doesn't care which individual attribute it is. Rather than having the view observe each of the individual attributes, KVO provides a way to automatically trigger another observation when any dependent attribute changes.
First, in the +initialize for the class that's going to be observed:
```
+ (void) initialize
{
    NSArray *keys;
    keys = [NSArray arrayWithObjects: @"showMajorLines", @"minorWeight",
                    @"minorColor", @"minorWeightIndex", @"minorColorIndex",
                    @"majorWeightIndex", @"majorColorIndex", nil];

    [BWGridAttributes
        setKeys: keys
        triggerChangeNotificationsForDependentKey: @"gridAttributeChange"];

} // initialize
```
So now when "showMajorLines" changes, "gridAttributeChange" will also be observed. KVO requires there actually must exist a gridAttributeChange method (or ivar I presume) before it'll do the notification to observing objects, so there needs to be a do-nothing method:
```
- (BOOL) gridAttributeChange
{
    return (YES);
} // gridAttributeChange
```
So now the view can do this:
```
- (void) setGridAttributes: (BWGridAttributes *) a
{
    [attributes removeObserver: self
                forKeyPath: @"gridAttributeChange"];

    [a retain];
    [attributes release];
    attributes = a;

    [a addObserver: self
       forKeyPath: @"gridAttributeChange"
        options: NSKeyValueObservingOptionNew
        context: NULL];

} // setGridAttributes
```
And will get updated whenever an individual attribute changes.

View with bindings [permalink]
ThumbBorker has a custom view class that updates a selection rectangle when the user finished dragging the mouse. It uses setValue:forKeyPath: to stick the value back into the bound object.

The bindings and path are ivars:

     id selectionRectBinding;
     NSString *selectionRectKeyPath;

In bind:toObject:withKeyPath:options: hang on to the binding object and the key path and set up observing:

         // hold on to the binding info
         selectionRectBinding = observableObject;
         selectionRectKeyPath = [observableKeyPath copy];

         // connect KVO
         [valuePathBinding addObserver: self
                           forKeyPath: selectionRectKeyPath
                           options: nil
                           context: NULL];

         // new binding, needs to redraw
         [self setNeedsDisplay: YES];

And in the mouseUp: handler, set the value back into the bound object:

     // figure out the selection rectangle
     NSRect selectionRect = [self normalizedSelectionRect];

     // wrap in a value and tell the bound object the new value

     NSValue *value;
     value = [NSValue valueWithRect: selectionRect];

     [selectionRectBinding setValue: value
                           forKeyPath: selectionRectKeyPath];

Hacks

Fixing Bindings-related memory leak [permalink]
If you have bindings hooked up to File's Owner in some circumstances (like with an NSWindowController-based nib file), a retain cycle is created, and so the window controller will never get released (having an extra retain for each binding to File's Owner). An easy way to work around this is to;
- Add an NSObjectController (I call it "Fake FIle's Owner") to the nib file and the window controller class.
- Point the bindings to the controller rather than file's owner
- Hook up the window controller's outlet to point to the object controller
- [fakeFileOwner setContent: self]
Then again, this all might be Wrong. jkp_ in #macdev points out that the setContent:self will retain self twice more, with no release in sight. The only wayd that would really work is if you provided a subclass of NSObjectController that released after it setContent: and also in _startObservingObject: That might be the cleanest solution - provide a custom proxy object that doesnt retain the filesOwner and bind to that....same thing, only you have to do the overrides. So this one's in limbo(e) for now. wheeee! He's come up with a hack to work around things:
```
- (oneway void) release;
{
    // special case when count is 3, we are being retained twice by the object controller...
    if ( [self retainCount] == 3 )
    {
        [super release];
        [filesOwnerProxy setContent:nil];
        return;
    }
    
    [super release];
}
```

NSTableView

Enabling buttons based on tableview selection [permalink]
Bind to your array controller selection, using @count.
Reacting to TableView selection changes when using bindings [permalink]
You're using bindings to handle the tableview, but now you have some code that needs to do something when the selection changes (in my case I was disabling a sheet's OK button if the selection in two tableviews was the same). The way to track that change is to add yourself as an observer of the array controller that's driving the tableview, and then do the work in the observeValueForKeyPath: method. Register your observer like this:
```
    [searchArrayController addObserver: self
                           forKeyPath: @"selectionIndexes"
                           options: NSKeyValueObservingOptionNew
                           context: NULL];
```
So now self's observeValue method will get invoked when selectionIndexes changes in the array controller.