|
 | |
Doing Objects Right: Adding Modular Objects
©1990-1997 Andrew C. Stone All Rights Reserved
Tue Dec 9 14:39:23 MST 1997
One of the most compelling features of writing software is that there are many ways to accomplish the same thing. This gives you a large latitude for creativity, but also “the power to run off into the weeds” (I overheard an Apple Engineer using this phrase). In this article I present some guidelines for creating usable and reusable objects, and provide source for a search and replace panel.
Our Rhapsody object draw and web authoring app, Create(TM), has 550 classes, and about 100 user-interface nib (NeXT InterfaceBuilder) files. This highly modular structure makes it trivial and speedy to change one component, and since the nib files are only loaded when needed, speeds application launching.
There is always a temptation to add objects directly to your main nib file because its easy to make object connections. But this bloats the main nib and causes the app to take longer to launch. Moreover, it makes multiple documents almost impossible because sometimes you need more than one. You also want to take advantage of loading the nib files only when needed. This article will show you how to write an object with its own independent interface file, and how to write the glue needed to have a menu item bring up that interface. Code is included for a universal text find and replace object, “TextFinder”, which can be added to the rather simplistic Word Processor from the November Issue 1997 of MACTECH.
// The entire source of sWord, our simple rich text & graphics wordprocessor:
#import <AppKit/AppKit.h>
@interface WordDelegate : NSObject
{
id theText;
}
- (void)newText:(id)sender;
- (void)openText:(id)sender;
- (void)saveText:(id)sender;
@end
#import “WordDelegate.h”
@implementation WordDelegate
- (void)newText:(id)sender
{
[theText setString:@””];
}
- (void)openText:(id)sender
{
NSOpenPanel *openPanel = [NSOpenPanel openPanel];
if ([openPanel runModalForTypes:[NSArray arrayWithObjects:@”rtf”,@”rtfd”,NULL]]) {
[theText readRTFDFromFile:[openPanel filename]];
}
}
- (void)saveText:(id)sender
{
NSSavePanel *savePanel = [NSSavePanel savePanel];
[savePanel setRequiredFileType:@”rtfd”];
if ([savePanel runModal]) {
[theText writeRTFDToFile:[savePanel filename] atomically:NO];
}
}
@end
This article won’t go into style issues - that’s a topic for holy wars! However, here are some basic guidelines in developing stand alone objects that are truly reusable:
1] Every .nib file should have an owner object which you say “+ new:” to.
This means that a client needs to know only the object’s class name: this presents a simple calling interface. By separating the details of the class (such as the nib name) from its use, you obtain a cushion from changes in the object. Then your client code looks like this:
id aCoolObject = [CoolObject new:(NSZone *)zone];
Note that the client determines the memory allocation zone, the NSZone, in which to create the new object by passing it in as an argument. You can always pass in “NSDefaultMallocZone()”, a function which returns the default memory allocation zone, or “[self zone]”, which returns the zone of the calling object.
In your CoolObject’s + new: method, you would have:
+ new:(NSZone *)zone
{
self = [[CoolObject allocWithZone:zone] init];
return self; /* don’t ever forget this! */
}
In its -init method, you would load the user interface file:
- init
{
[super init];
[NSBundle loadNibNamed:@”CoolObject.nib” owner:self];
/* place initialization code here:*/
return self; /* don’t ever forget this! */
}
Many objects require only one instance per class. For example, Create uses just one TextFinder object, which brings up the same panel each time. For these type of objects, it’s more appropriate to create a class method named “+ sharedInstance” , which might look like this:
+ (id)sharedInstance {
// subclasses need their own instance if both classes are needed:
static id sharedFindObject = nil;
// get the real McCoy the first time through:
if (!sharedFindObject) {
sharedFindObject = [[self allocWithZone:[[NSApplication sharedApplication] zone]] init];
}
return sharedFindObject;
}
2] Name your .nib file the same as the owner’s class
For each object which has a visual representation, your project directory will have three associated files: the .h, .m, and .nib (although if the .nib is localizable, it will reside in English.proj, German.proj, French.proj, etc).
If the owner’s class name coincides with the nib file name, the following generic code will load a nib file based on that class name, using the NSStringFromClass() function:
#import <AppKit/AppKit.h> /* Everything you need */
- init
{
// Continue the designated initializer chain:
[super init];
// here’s a fuller invocation of “loadNibNamed:” which shows the loading of the dictionary
// with the key-value pair NSOwner, which has a value of “self”.
[NSBundle loadNibFile:[[NSBundle mainBundle] pathForResource:
NSStringFromClass([self class]) ofType:@”nib”]
externalNameTable:[NSDictionary dictionaryWithObjectsAndKeys:self, @”NSOwner”, nil]
withZone:[self zone]];
// place other initialization code here
return self;
}
By making your object a subclass of an object which has this code to load a nib, you never even have to even write a new line of code - the nib with the name of your subclass will be loaded automatically.
Apt class naming is one of the most important aspects of creating comprehensible, not reprehensible, code; the name should clearly and concisely describe the object’s function. If my custom class is a subclass of an NS object, I like to include the superclass name in my class name. For example, SliderDualActing descends from NSSlider. Usually, nib owners will descend from NSObject, so they can have more succinct descriptive names, such as “AlignPanel”, “TextFinder”, or “OpenAccessory”.
3] Use the power of Objective C
We would like any text object to be able to use our TextFinder’s search and replace functionality, not just our own custom subclasses. Objective C allows us to add methods to existing classes via Categories. This allows us to extend NSTextView with a category TextFinderMethods, which contains the search and replace methods. Now any NSTextView in our application will be able to respond to methods like findNext: or findPrevious:.
One note of caution about categories: if you add multiple categories to a class and define a method in more than one category, it is undetermined which method will be used at runtime. So be sure to use categories carefully. They may someday be thought of as the Object Oriented GOTO, but they reveal the power of a dynamic runtime system. The full set of methods that we extend the NSTextView class are found in “NSTextViewTextFinder.m”.
Objective C also provides the ability to subclass, which allows us to reuse classes by modifying their functionality to fit specific applications. For example, for specific text objects, we might want to provide the capability to use regular expressions in our search strings. We could subclass TextFinder and modify a few of its methods without having to rework the whole object.
@implementation NSTextView(TextFinderMethods)
- (void)orderFrontFindPanel:(id)sender {
// no variable is used - instead, we grab the sharedInstance:
[[TextFinder sharedInstance] orderFrontFindPanel:sender];
}
...
4] Use the power of the AppKit
Your interface depends on being able to cause various controls (buttons, menu items) to trigger actions in your code. This is easy with the TextFinder object and the TextFinder nib; you can easily create the necessary connections in the Interface Builder. But now that you’ve followed my advice to use modular design and have created many individual nib files, how do you connect the menu items defined in the main nib file to targets in other nib files? And how do you connect menu items for finding text to the methods defined in the TextFinderMethods category?
The solution is the use of the AppKit’s “First Responder” hierarchy. In AppKit programs, if a menu item is connected to the “First Responder” stand-in object, then when the menu item is clicked, it sends its message up a hierarchy until it reaches an object which responds to that method. If no object in the hierarchy responds to that message, the menu item will automatically be disabled. Each NSWindow in your application keeps track of the object in its view hierarchy that has first responder status. This object gets the first chance to handle messages sent to First Responder. From there, the message is passed to the first responder’s superview, through the view hierarchy to the window and then to the window’s delegate. If the message has not yet been handled, it then goes to the NSApplication and finally to the NSApplication’s delegate.
So, all you need to do is add the method’s name (also called “action”) to your main nib’s First Responder, and connect the menu item to that action. The rest is done automatically by the AppKit objects and the runtime system. Full instructions on adding the TextFinder to an application follow the article.
5] Document the object.
Document what your object does and how it should be called. If you commented as you went, the documentation is mostly written. Make your API understandable by clearly explaining instance variables and methods.
6] Don’t Panic
I guess this belongs in every list of guidelines! Happy Hacking.
<<SIDEBAR OF ADDING THE TEXTFINDER TO THE WORD PROCESSOR WE BUILT IN NOV 97>>
Adding the Text Finder to your application
Adding the TextFinder to an existing project, like the simple word processor we built in November 97, is as easy as adding the TextFinder.subproj to your project, adding the more complete Edit menu available in Interface Builder’s Menu palette, and then connecting these menu items with the method names that we have added to the NSTextView. Here’s a step-by-step guide:
0. Download or type in the TextFinder.subproj files (see code below).
1. Open the pWord PB.project file in ProjectBuilder.
2. Double-Click “Subprojects” which brings up a Open Panel.
3. Select the “TextFinder.subproj” to add this subproject.
4. Double-Click Interfaces->sWord.nib to launch InterfaceBuilder and load the main nib file.
5. Select the “Edit” menu item, and choose Delete. <<04_EditMenuBefore.tiff>>
6. Choose the “Menu” section of IB’s Palette.
7. Drag over the “Edit” menu item onto your main menu
8. Now, you must add the new methods that the NSTextView understands to the First Responder stand in object.
(that is, the methods we defined in NSTextViewTextFinder.m such as orderFrontFindPanel:, findNext:, findPrevious:, jumpToSelection:, and scrollToSelection:)
a. Double-click the First Responder icon to load the Classes subpanel
b. Click on the crossed “Action” icon to reveal the list of actions understood by the First Responder
c. Choose Classes->New Action, or type <RETURN> to open a new, untitled action
d. Rename “myAction:” to, e.g., “orderFrontFindPanel:”
e. repeat a-d for each of the other actions.
f. Save your interface file to update the First Responder completely.
9. Connect the menu items to their corresponding First Responder action by control-dragging from the menu item to the First Responder icon, and then selecting the correct action in IB’s
10. Recompile, and you are done! Type in some words and try out the find/replace.
The Code
TextFinder.subproj contains TextFinder.h in Headers, TextFinder.m in Classes, NSTextViewTextFinder.m in Other Sources, and TextFinder.nib in Interfaces.
** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * NSTextViewTextFinder.m ** * ** * ** * ** * ** * ** * ** * ** * ** *
// This is the glue which makes every text object able to do search and replace
// These methods extend the original functionality of the NSTextView in order
// to talk to our TextFinder object
// Now, you can add the complete “Edit” menu in InterfaceBuilder
// which contains the Find submenu, and it will just work....
#import <AppKit/AppKit.h>
#import “TextFinder.h”
@implementation NSTextView(TextFinderMethods)
- (void)orderFrontFindPanel:(id)sender {
[[TextFinder sharedInstance] orderFrontFindPanel:sender];
}
- (void)findNext:(id)sender {
[[TextFinder sharedInstance] findNext:sender];
}
- (void)findPrevious:(id)sender {
[[TextFinder sharedInstance] findPrevious:sender];
}
- (void)enterSelection:(id)sender {
NSRange range = [self selectedRange];
if (range.length) {
[[TextFinder sharedInstance] setFindString:[[self string] substringWithRange:range]];
} else {
NSBeep();
}
}
- (void)jumpToSelection:(id)sender {
[self scrollRangeToVisible:[self selectedRange]];
}
- (void)doFindSelection:sender
{
[self enterSelection:self];
}
@end
** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * TextFinder.h ** * ** * ** * ** * ** * ** * ** * ** * ** *
#import <AppKit/AppKit.h>
#define Forward YES
#define Backward NO
@interface TextFinder : NSObject {
NSString *findString;
id findTextField;
id replaceTextField;
id ignoreCaseButton;
id findNextButton;
id replaceAllScopeMatrix;
id statusField;
BOOL findStringChangedSinceLastPasteboardUpdate;
BOOL lastFindWasSuccessful;
}
/* Common way to get a text finder. One instance of TextFinder per app is good enough. */
+ (id)sharedInstance;
/* Main method for external users; does a find in the first responder. Selects found range or beeps. */
- (BOOL)find:(BOOL)direction;
/* Loads UI lazily */
- (NSPanel *)findPanel;
/* Gets the first responder and returns it if it’s an NSTextView */
- (NSTextView *)textObjectToSearchIn;
/* Get/set the current find string. Will update UI if UI is loaded */
- (NSString *)findString;
- (void)setFindString:(NSString *)string;
/* Misc internal methods */
- (void)appDidActivate:(NSNotification *)notification;
- (void)addWillDeactivate:(NSNotification *)notification;
- (void)loadFindStringFromPasteboard;
- (void)loadFindStringToPasteboard;
/* Methods sent from the find panel UI */
- (void)findNext:(id)sender;
- (void)findPrevious:(id)sender;
- (void)findNextAndOrderFindPanelOut:(id)sender;
- (void)replace:(id)sender;
- (void)replaceAndFind:(id)sender;
- (void)replaceAll:(id)sender;
- (void)orderFrontFindPanel:(id)sender;
@end
@interface NSString (NSStringTextFinding)
- (NSRange)findString:(NSString *)string selectedRange:(NSRange)selectedRange options:(unsigned)mask wrap:(BOOL)wrapFlag;
@end
** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * TextFinder.m ** * ** * ** * ** * ** * ** * ** * ** * ** *
/*
* TextFinder.m
* Author: Ali Ozer
* Created: Feb 21, 1995 for TextEdit
* Modified: Jan 96 for Yap
* Comments: Dec 97 by Andrew Stone
* Generic Find/Replace functionality for text. Uses new text API
* You may freely copy, distribute and reuse the code in this example.
* NeXT disclaims any warranty of any kind, expressed or implied,
* as to its fitness for any particular use.
*/
#import <AppKit/AppKit.h>
#import “TextFinder.h”
@implementation TextFinder
- (id)init {
// if there are memory allocation problems, we bail and return nil:
if (!(self = [super init])) return nil;
// in order share find strings among applications,
// we’ll register for notifications when the app activates or deactivates:
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(appDidActivate:) name:NSApplicationDidBecomeActiveNotification object:[NSApplication sharedApplication]];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(addWillDeactivate:) name:NSApplicationWillResignActiveNotification object:[NSApplication sharedApplication]];
// initialize ourselves to the empty string:
[self setFindString:@””];
// here we grab the last used findstring from other apps:
[self loadFindStringFromPasteboard];
return self;
}
// these are the methods called whenever we get an activate or deactivate notification:
- (void)appDidActivate:(NSNotification *)notification {
[self loadFindStringFromPasteboard];
}
- (void)addWillDeactivate:(NSNotification *)notification {
[self loadFindStringToPasteboard];
}
// and here is the workhorse code for sharing the findstrings among apps:
- (void)loadFindStringFromPasteboard {
NSPasteboard *pasteboard = [NSPasteboard pasteboardWithName:NSFindPboard];
if ([[pasteboard types] containsObject:NSStringPboardType]) {
NSString *string = [pasteboard stringForType:NSStringPboardType];
if (string && [string length]) {
[self setFindString:string];
findStringChangedSinceLastPasteboardUpdate = NO;
}
}
}
- (void)loadFindStringToPasteboard {
NSPasteboard *pasteboard = [NSPasteboard pasteboardWithName:NSFindPboard];
if (findStringChangedSinceLastPasteboardUpdate) {
[pasteboard declareTypes:[NSArray arrayWithObject:NSStringPboardType] owner:nil];
[pasteboard setString:[self findString] forType:NSStringPboardType];
findStringChangedSinceLastPasteboardUpdate = NO;
}
}
// Only one of the TextFinder objects is ever required:
static id sharedFindObject = nil;
+ (id)sharedInstance {
if (!sharedFindObject) {
sharedFindObject = [[self allocWithZone:[[NSApplication sharedApplication] zone]] init];
}
return sharedFindObject;
}
- (void)loadUI {
// we check to see if the findTextField ivar is nil, if so, we load the nib:
if (!findTextField) {
if (![NSBundle loadNibNamed:@”TextFinder” owner:self]) {
NSLog(@”Failed to load TextFinder.nib”);
NSBeep();
}
// here we automatically remember the user’s last location of the find panel:
if (self == sharedFindObject) [[findTextField window] setFrameAutosaveName:@”Find”];
}
// now update the search string:
[findTextField setStringValue:[self findString]];
}
- (void)dealloc {
// don’t litter
if (self != sharedFindObject) {
[findString release];
[super dealloc];
}
}
- (NSString *)findString {
return findString;
}
- (void)setFindString:(NSString *)string {
// only change if different:
if ([string isEqualToString:findString]) return;
// careful memory management is what makes a good programmer!
[findString autorelease];
// keep a copy around:
findString = [string copyWithZone:[self zone]];
if (findTextField) {
[findTextField setStringValue:string];
[findTextField selectText:nil];
}
// here we note that we haven’t set the global pasteboard string yet:
findStringChangedSinceLastPasteboardUpdate = YES;
}
// this method tries to find the NSText object that is active
// it will return nil if none is active:
- (NSTextView *)textObjectToSearchIn {
id obj = [[NSApp mainWindow] firstResponder];
return (obj && [obj isKindOfClass:[NSText class]]) ? obj : nil;
}
- (NSPanel *)findPanel {
if (!findTextField) [self loadUI];
return (NSPanel *)[findTextField window];
}
/* The primitive for finding; this ends up setting the status field (and beeping if necessary)...
*/
- (BOOL)find:(BOOL)direction {
NSTextView *text = [self textObjectToSearchIn];
lastFindWasSuccessful = NO;
if (text) {
NSString *textContents = [text string];
unsigned textLength;
if (textContents && (textLength = [textContents length])) {
NSRange range;
unsigned options = 0;
if (direction == Backward) options |= NSBackwardsSearch;
if ([ignoreCaseButton state]) options |= NSCaseInsensitiveSearch;
range = [textContents findString:[self findString] selectedRange:[text selectedRange] options:options wrap:YES];
if (range.length) {
[text setSelectedRange:range];
[text scrollRangeToVisible:range];
lastFindWasSuccessful = YES;
}
}
}
if (!lastFindWasSuccessful) {
NSBeep();
[statusField setStringValue:NSLocalizedStringFromTable(@”Not found”, @”FindPanel”, @”Status displayed in find panel when the find string is not found.”)];
} else {
[statusField setStringValue:@””];
}
return lastFindWasSuccessful;
}
- (void)orderFrontFindPanel:(id)sender {
NSPanel *panel = [self findPanel];
[findTextField selectText:nil];
[panel makeKeyAndOrderFront:nil];
}
/** * ** * Action methods for gadgets in the find panel; these should all end up setting or clearing the status field ** * ** * /
- (void)findNextAndOrderFindPanelOut:(id)sender {
[findNextButton performClick:nil];
if (lastFindWasSuccessful) {
[[self findPanel] orderOut:sender];
} else {
[findTextField selectText:nil];
}
}
- (void)findNext:(id)sender {
if (findTextField) [self setFindString:[findTextField stringValue]]; /* findTextField should be set */
(void)[self find:Forward];
}
- (void)findPrevious:(id)sender {
if (findTextField) [self setFindString:[findTextField stringValue]]; /* findTextField should be set */
(void)[self find:Backward];
}
- (void)replace:(id)sender {
NSTextView *text = [self textObjectToSearchIn];
if (!text) {
NSBeep();
} else {
[[text textStorage] replaceCharactersInRange:[text selectedRange] withString:[replaceTextField stringValue]];
[text didChangeText];
}
[statusField setStringValue:@””];
}
- (void)replaceAndFind:(id)sender {
[self replace:sender];
[self findNext:sender];
}
#define ReplaceAllScopeEntireFile 42
#define ReplaceAllScopeSelection 43
- (void)replaceAll:(id)sender {
NSTextView *text = [self textObjectToSearchIn];
if (!text) {
NSBeep();
} else {
NSString *textContents = [text string];
BOOL entireFile = replaceAllScopeMatrix ? ([replaceAllScopeMatrix selectedTag] == ReplaceAllScopeEntireFile) : YES;
NSRange replaceRange = entireFile ? NSMakeRange(0, [[text textStorage] length]) : [text selectedRange];
unsigned options = NSBackwardsSearch | ([ignoreCaseButton state] ? NSCaseInsensitiveSearch : 0);
unsigned replaced = 0;
if (findTextField) [self setFindString:[findTextField stringValue]];
[[text textStorage] beginEditing];
while (1) {
NSRange foundRange = [textContents rangeOfString:[self findString] options:options range:replaceRange];
if (foundRange.length == 0) break;
replaced++;
[[text textStorage] replaceCharactersInRange:foundRange withString:[replaceTextField stringValue]];
replaceRange.length = foundRange.location - replaceRange.location;
}
[[text textStorage] endEditing];
[text didChangeText];
if (replaced == 0) {
NSBeep();
[statusField setStringValue:NSLocalizedStringFromTable(@”Not found”, @”FindPanel”, @”Status displayed in find panel when the find string is not found.”)];
} else {
[statusField setStringValue:[NSString localizedStringWithFormat:NSLocalizedStringFromTable(@”%d replaced”, @”FindPanel”, @”Status displayed in find panel when indicated number of matches are replaced.”), replaced]];
}
}
}
@end
@interface NSString (StringTextFinding)
- (NSRange)findString:(NSString *)string selectedRange:(NSRange)selectedRange options:(unsigned)options wrap:(BOOL)wrap;
@end
@implementation NSString (StringTextFinding)
- (NSRange)findString:(NSString *)string selectedRange:(NSRange)selectedRange options:(unsigned)options wrap:(BOOL)wrap {
BOOL forwards = (options & NSBackwardsSearch) == 0;
unsigned length = [self length];
NSRange searchRange, range;
if (forwards) {
searchRange.location = NSMaxRange(selectedRange);
searchRange.length = length - searchRange.location;
range = [self rangeOfString:string options:options range:searchRange];
if ((range.length == 0) && wrap) { /* If not found look at the first part of the string */
searchRange.location = 0;
searchRange.length = selectedRange.location;
range = [self rangeOfString:string options:options range:searchRange];
}
} else {
searchRange.location = 0;
searchRange.length = selectedRange.location;
range = [self rangeOfString:string options:options range:searchRange];
if ((range.length == 0) && wrap) {
searchRange.location = NSMaxRange(selectedRange);
searchRange.length = length - searchRange.location;
range = [self rangeOfString:string options:options range:searchRange];
}
}
return range;
}
@end
** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * *
|
|
