Timelapse – The City Limits from Dominic on Vimeo.

Via Jonathan Woods at MSNBC.

TestRunner itself is now managed with Git as well. You may clone the master repository at git://programerror.com/testrunner.git, or fork the mirror at GitHub.

Setting View Size

NSScrollViews will automatically adjust scroll bar positions and sizes to the accommodate the document view that they encapsulate. This behavior is controlled by monitoring the frame size of the content NSView-subclass instance. Whenever the desired size of the document changes, simply set the frame size appropriately:

NSSize desiredSize;
desiredSize.width = 500.0;
desiredSize.height = 500.0;
[theDocumentView setFrameSize:desiredSize];

Centering the Document

This bit is somewhat more complicated. The default behavior of NSScrollView revolves around document views with layout that flows from the origin, bottom left by default. Whenever the content view is smaller the scroll view, the position is locked to the origin. In my case, however, I want the enclosed view to be centered whenever it is small enough to fit. There is no means to do this out of the box, though.

The general consensus of forums and mailing lists seems to be that this is best accomplished by subclassing NSClipView and replacing the content view of the scroll view with this subclass. The basic idea is to catch frame size changes and trigger the centering behavior under appropriate conditions. The following interface comes from my implementation of such a clip view subclass in Avida : Mac OS Viewer (BSD-style license):

@interface CenteringClipView : NSClipView {
  NSPoint viewPoint;
}
- (id) initWithFrame:(NSRect)frame;
- (void) centerView;
// NSClipView Method Overrides
- (NSPoint) constrainScrollPoint:(NSPoint)proposedNewOrigin;
- (void) viewBoundsChanged:(NSNotification*)notification;
- (void) viewFrameChanged:(NSNotification*)notification;
- (void) setFrame:(NSRect)frameRect;
- (void) setFrameOrigin:(NSPoint)newOrigin;
- (void) setFrameSize:(NSSize)newSize;
- (void) setFrameRotation:(CGFloat)angle;
@end

The implementation consists of two core methods that handle most of the work, centerView and constrainScrollPoint:(NSPoint). The centerView method finds the appropriate origin point for the clipping rect given the size of the document. When the document is small enough to fit, the origin will center the document. When the document is larger than the scroll view, it will adjust the origin relative to the last scroll point of the view. The constrainScrollPoint:(NSPoint) method is a core NSClipView method that may be used to constrain scrolling behavior in subclasses. In CenteringClipView, the method keeps the scroll point fixed in any direction that is smaller than the scroll view size, otherwise bounding scrolling within the document. It also stashes the current scroll point in self.viewPoint for use in centerView.

- (void) centerView {
  NSRect docRect = [[self documentView] frame];
  NSRect clipRect = [self bounds];
  // Center the clipping rect origin x
  if (docRect.size.width < clipRect.size.width) {
    clipRect.origin.x = roundf((docRect.size.width - clipRect.size.width) / 2.0);
  } else {
    clipRect.origin.x = roundf(viewPoint.x * docRect.size.width - (clipRect.size.width / 2.0));
  }
  // Center the clipping rect origin y
  if (docRect.size.height < clipRect.size.height) {
    clipRect.origin.y = roundf((docRect.size.height - clipRect.size.height) / 2.0);
  } else {
    clipRect.origin.y = roundf(viewPoint.y * docRect.size.width - (clipRect.size.height / 2.0));
  }
  // Scroll the document to the selected center point
  NSScrollView* scrollView = (NSScrollView*)[self superview];
  [self scrollToPoint:[self constrainScrollPoint:clipRect.origin]];
  [scrollView reflectScrolledClipView:self];
}
- (NSPoint) constrainScrollPoint:(NSPoint)proposedNewOrigin {
  NSRect docRect = [[self documentView] frame];
  NSRect clipRect = [self bounds];
  CGFloat maxX = docRect.size.width - clipRect.size.width;
  CGFloat maxY = docRect.size.height - clipRect.size.height;
  clipRect.origin = proposedNewOrigin;
  if (docRect.size.width < clipRect.size.width) {
    clipRect.origin.x = roundf(maxX / 2.0);
  } else {
    clipRect.origin.x = roundf(MAX(0, MIN(clipRect.origin.x, maxX)));
  }
  if (docRect.size.height < clipRect.size.height) {
    clipRect.origin.y = roundf(maxY / 2.0);
  } else {
    clipRect.origin.y = roundf(MAX(0, MIN(clipRect.origin.y, maxY)));
  }
  viewPoint.x = NSMidX(clipRect) / docRect.size.width;
  viewPoint.y = NSMidY(clipRect) / docRect.size.height;
  return clipRect.origin;
}

The last bits of the implementation simply catch frame size changes. The methods are forwarded to the superclass (NSClipView), then followed by a call to centerView ensuring that the document stays centered as desired.

- (void) viewBoundsChanged:(NSNotification*)notification {
  [super viewBoundsChanged:notification];
  [self centerView];
}
- (void) viewFrameChanged:(NSNotification*)notification {
  [super viewBoundsChanged:notification];
  [self centerView];
}
- (void) setFrame:(NSRect)frameRect {
  [super setFrame:frameRect];
  [self centerView];
}
- (void) setFrameOrigin:(NSPoint)newOrigin {
  [super setFrameOrigin:newOrigin];
  [self centerView];
}
- (void) setFrameSize:(NSSize)newSize {
  [super setFrameSize:newSize];
  [self centerView];
}
- (void) setFrameRotation:(CGFloat)angle {
  [super setFrameRotation:angle];
  [self centerView];
}

Once you have a clip view that handles the behavior you want, you need to set it up for use in your scroll view. Unfortunately, this cannot be done through Interface Builder. Rather, you will need a few lines in your initialization code for the view. In my case, I used the windowDidLoad method of my window controller, so that I can be sure that the view has been loaded fully.

- (void) windowDidLoad {
  ...
  // Replace NSClipView of scrollView with a CenteringClipView
  id docView = [scrollView documentView];
  NSClipView* clipView = [[CenteringClipView alloc] initWithFrame:[docView frame]];
  [scrollView setContentView:clipView];
  [scrollView setDocumentView:docView];
  ...
}

Strange Document Frame Origin Behavior

If you have implemented a custom clip view as described above, you may observe some strange behavior when resizing the enclosing scroll view. My document view would shift away from to origin, occasionally snapping back to the correct position. It may have been an result of my set original set up in Interface Builder, but the root cause appears to have been artifacts in automatic subview resizing. The solution was to explicitly disable subview resizing in CenteringClipView.

- (id) initWithFrame:(NSRect)frame {
  self = [super initWithFrame:frame];
  if (self) {
    viewPoint = NSMakePoint(0, 0);
    [self setAutoresizesSubviews:NO];
  }
  return self;
}

Handling Scroller Visibility

If you want the scrollers of the scroll view to disappear when not in use, you should be able to set automatic scroller hiding on the NSScrollView class. However, in my experience, the automatic behavior was not triggered properly by my clip view. The prevailing solution to this appears to entail taking scroll bar handling into your own hands. I disabled automatic scroll bar hiding and wrote my own code to do it. I won't go into details here, but rather refer you to my implementation in Avida : Mac OS Viewer's CenteringClipView class for details.

Conclusion

These tidbits are, of course, not intended to be a detailed tutorial for using NSScrollViews. However, since it took quite a bit of search, debugging, and head scratching to solve them, I thought it be worth jotting them down. Hopefully they will make it into Google and be useful for others new to Cocoa. If you are more familiar with Cocoa, please let me know if there is a better way to do any of the above.

Great film by Errol Morris for IBM (via John Gruber).

As logically follows, Wednesday will be last day working for the MSU Libraries. After six years I have accumulated quite a bit of experience and have appreciated the opportunities and support for my education that the Libraries afforded me. I wish them well.