BWToolkit is a library of code for Cocoa development.

Actually, it’s more than just a library of code. It comes with an Interface Builder (version 3) plugin that simplifies development and use of the framework. BWToolkit is open source under the generous BSD license, and you can obtain it as source code or you can obtain it as a nice “drop and play” package.

I’ve stumbled across BWToolkit a few times in my development work, but it wasn’t until recently that I could begin using it (seems to have a requirement of Mac OS X 10.5 as a minimum…. doesn’t state that explicitly, but you can see it in some of what it does plus examining the source code). In my use of it so far, it’s been really well done and a real joy to development. Having been an engineer of the PowerPlant C++ Mac application framework back in the day, I know what it can be like to write reusable code modules like this, and BWToolkit has a lot of spit and polish.

Some things I like about it:

• Drop and play. Just download the distribution, install the IB plugin, ensure the framework is added to your project (link to it, copy it into your resulting bundle) and that’s it. So simple.
• Use is very simple, because there’s no extra work. Just edit merrily away in Interface Builder.
• It’s got a lot of those widgets that you commonly want to use but there’s nothing standard from the OS for you to use. Oh sure you could make the widgets, but BWToolkit makes things like the BWAnchoredButtonBar, BWAnchoredPopUpButton, BWUnanchoredButtonContainer and so on… it just helps round out those commonly used widgets so all you have to do in IB is just drag and drop and get on with your work.
• I love the BWSheetController. I wish I had thought of that class! It’s so common to have a xib with a main window (e.g. document) and then you need to display a sheet on the window. To display the sheet, there’s a lot of infrastructure code you have to write every time, and it’s the same code over and over — perfect candidate for a reusable class to factor that out. With BWSheetController it’s even better because it’s just adding an instance of the controller to the xib, hooking up some outlets, and viola… functional sheet with just a few clicks. Wonderful!
• Most of the classes are based upon Cocoa classes. For instance, BWSplitView is an NSSplitView, the button classes are typically just aggregates of other NSButton’s. It’s good to subclass where it makes sense, instead of fully recreating from scratch.
• The use of the BSD license pretty much means there’s little reason NOT to use BWToolkit. It makes your life a lot easier, little restriction upon use, it’s free (beer and speech). What’s not to like?

Some things I don’t like:

• I found a bug (BWSplitView’s show up in initial random locations if the host window’s “visible upon launch” setting is not on). I reported the bug via email but have received no reply from the author (it’s been long enough). Granted, it seems he’d prefer filing it in his bug tracking system, but I don’t have the cycles right now to do that so I wanted to at least email to ensure the bug didn’t slip through the cracks. So, I’m not sure how active the project is right now. *shrug*
• There’s not much documentation. Granted, there’s enough to get you going, and eventually you can figure things out. But to make a well-rounded distribution, full documentation of the classes/widgets and an accompanying sample application that shows everything off would make for a better final product.
• Some of where documentation would be very useful would be things like bottom bars…. you can do bottom bars now so, what’s the point of this class? What advantage does it provide? Or is it a holdover from long ago when the OS provided no means whatsoever? In which case, is the bottom bar class smart about the OS version? Again, one could figure it out from reading code, but formal documentation is better.

All in all, a nice little toolkit.

If you’re not a Mac programmer, you can stop reading now. 🙂

Apple has this cool new widget called NSRuleEditor, introduced in Mac OS X 10.5. A lot of the software I’ve written over the past some years involves searching for things and often the user needs to provide you with rules by which to search. I’ve always had to invent my own solutions, and it’s a non-trivial thing to do. So when I finally heard about NSRuleEditor some years ago I was most excited to finally have an OS-provided solution.

The way Apple implement the widget is pretty cool. They realize people will use it to display whatever arbitrary data model they have, so they structured it that way. The NSRuleEditor iself is a single control, the contents of which are opaque to you… mostly. There’s your data model objects, which NSRuleEditor calls your criteria (that bugs me, as “criteria” is plural and the API uses it in a singular sense, but oh well… I can understand why they did that). The criteria can be whatever you want them to be, it doesn’t matter. But each criteria object then has a “display value”, which is how the criteria is displayed and/or worked with in the GUI, such as a string or a menu item or a text field or date picker. Thus I can have a LabelObject, an OperatorObject, and a TextObject which represent my data model. The LabelObject would have a display value of “name” and a predicate value of “left hand expression” and kMDItemDisplayName, the OperatorObject would have a value of “contains” and a predicate operator value of  “IN”, and the TextObject would have a display value of an NSTextField and a predicate value of the “right hand expression”. Thus I could get the GUI to display “name contains <foo>” and create a query string like “kMDItemDisplayName IN <foo>”.

It’s a little obtuse to wrap around at first, but once you figure it out, it’s actually pretty well done. Apple has to make a generic control that anyone can use, and rule display/editing is non-trivial. Really, they did a pretty good job with this.

One thing to realize is the displayValues are not necessarily what is displayed in the GUI. Yes they generally are, but when you do this there is no localization. However, NSRuleEditor has a way you can provide a dictionary of formatting strings that allow you to change the displayed format. You see, the criteria objects are truly the data model. The displayValues aren’t truly the view… they can be, but they’re like “one step back” from being the view. Really, you should be using the formatting strings to get the real view… and then it’s like the displayValues are a “view model” for the view. Confusing? I know, but this is how it is. The formatting strings are your way to localize the display, but of course you don’t need to use it for localizing… you could just use them to change what is truly displayed to something other than the strict “view model”. There’s flexibility in the mapping the formatting strings provide.

So for instance I want to do a name criteria. The formatting strings are a key-value pair. The key is a pattern that matches the labels of your criteria objects. For instance:

%[Name]@ %[matches, contains, is, begins with, ends with]@ %@

Provides the formatting key. The %@ groups demarcate special identifiers, so that in your value, you’d have something like:

%1$[Name]@ %2$[matches, contains, is, begins with, ends with]@ %$3@

As the formatting value is parsed, it picks up the “x$” identifiers and knows this affects the ordering of the elements in the string, so you could shuffle things around. As well then, the items within the brackets are also ordered. So for instance if I had a value string like:

%1$[Name]@ %2$[ends with, begins with, is, contains, matches]@ %$3@

then when my data model said “matches” the GUI would present “ends with” to the user. Of course, this would be highly confusing to the user thinking they were doing an “ends with” search but the actual search ended up doing a “matches” search. But it shows what you can do.

Of course, the real benefit of this is localization. Let’s say we were converting “name contains foo” to Japanese. The key is the same as above, but the value then becomes:

%1$[お名前は]@ %$3@ %2$[が入っている]@

Which is “name contains”.

All of this is good and great. But where it falls flat? You have no way to know what NSRuleEditor is displaying. What if you wanted to get that that information? You can’t. You can get the -criteriaForRow: to get the row’s criteria objects. You can get the -displayValuesForRow:, which gets the raw display values. But you can’t get the formatted display values, like a -formattedDisplayValuesForRow:

*sigh*

This put a big crimp in things for me and the code I’m presently working on. Granted, I can get all the elements myself, of the criteria, the display values, and the formatting strings, but to apply the formatting strings to the display values is a non-trivial task. IMHO, a bug/shortcoming in the NSRuleEditor API. Bug filed: rdar://problem/7741182.

NSPredicate trick

That all said, there is a cool NSPredicate trick.

This comes from blacktree-alchemy’s code for QSMDPredicate. It’s basically a way you can shove a MDQuery syntax string into an NSPredicate and have it all work out. Handy because NSRuleEditor is based upon NSPredicate, but since NSPredicate and the MDQuery syntax don’t have a perfect one-to-one correspondence (or maybe you’re using MDQuery instead of NSMetadataQuery), it’s handy.

In case the QSMDPredicate code ever goes away, here it is. Again, this is NOT mine, just someone thankful for it’s existence and release under the Apache License 2.0.

QSMDPredicate.h

//
// QSMDPredicate.h
// QSSpotlightPlugIn
//
// Created by Alcor on 5/6/05.

//

#import

 

@interface QSMDQueryPredicate : NSPredicate {
NSString *query;
}
+ (id)predicateWithString:(NSString *)aQuery;
- (NSString *)query;
- (void)setQuery:(NSString *)aQuery;
@end


QSMDPredicate.m


//
// QSMDPredicate.m
// QSSpotlightPlugIn
//
// Created by Alcor on 5/6/05.

//

#import "QSMDPredicate.h"

@implementation QSMDQueryPredicate
- (id)generateMetadataDescription{
return query;
}
+ (id)predicateWithString:(NSString *)aQuery{
QSMDQueryPredicate *predicate=[[[self alloc]init]autorelease];
[predicate setQuery:aQuery];
return predicate;
}
- (NSString *)predicateFormat{
return query;
}
- (NSString *)query { return [[query retain] autorelease]; }
- (void)setQuery:(NSString *)aQuery
{
if (query != aQuery) {
[query release];
query = [aQuery copy];
}
}
- (id)copyWithZone:(NSZone *)zone
{
id copy = [[QSMDQueryPredicate allocWithZone:zone]init];
[copy setQuery:[self query]];
return copy;
}
@end

 

(Wow… I just realized my current WordPress.com theme is crappy at handling blocks. I need to learn more CSS so I can tweak that).