ADC Home > Reference Library > Reference > Cocoa > User Experience > NSSplitView Class Reference >

Next Page > Hide TOC

NSSplitView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSSplitView.h
Related sample code

Overview

An NSSplitView object stacks several subviews within one view so that the user can change their relative sizes. By default, the split bars between the views are horizontal, so the views are one on top of the other.

Divider indices are zero-based, with the topmost (in horizontal split views) or leftmost (vertical) divider having an index of 0.

Tasks

Managing Subviews

Managing Split View Orientation

Assigning a Delegate

Configuring and Drawing View Dividers

Saving Subview Positions

Configuring Pane Splitters

Constraining Split Position

Instance Methods

adjustSubviews

Adjusts the sizes of the receiver’s subviews so they (plus the dividers) fill the receiver.

- (void)adjustSubviews

Discussion

The subviews are resized proportionally; the size of a subview relative to the other subviews doesn’t change.

Availability
See Also
Related Sample Code
Declared In
NSSplitView.h

autosaveName

Returns the name under which receiver’s divider position is automatically saved.

- (NSString *)autosaveName

Return Value

The name used to save the receiver’s state.

Availability
See Also
Declared In
NSSplitView.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Availability
See Also
Declared In
NSSplitView.h

dividerColor

Return the color of the dividers that the split view is drawing between subviews.

- (NSColor *)dividerColor

Return Value

The color drawn between the subviews.

Discussion

The default implementation of this method returns clearColor when dividerStyle returns NSSplitViewDividerStyleThick. It will also return clearColor when dividerStyle returns NSSplitViewDividerStyleThin if the split view is in a textured window. All other thin dividers are drawn with a color that looks good between two white panes.

You can override this method to change the color of dividers.

Availability
Declared In
NSSplitView.h

dividerStyle

Returns the style of the divider drawn between subviews.

- (NSSplitViewDividerStyle)dividerStyle

Return Value

The current divider style. The possible values are described in “Split View Divider Styles.”

Availability
See Also
Declared In
NSSplitView.h

dividerThickness

Returns the thickness of the divider.

- (CGFloat)dividerThickness

Discussion

You can subclass NSSplitView and override this method to change the divider’s size, if necessary.

Availability
See Also
Declared In
NSSplitView.h

drawDividerInRect:

Draws the divider between two of the receiver’s subviews.

- (void)drawDividerInRect:(NSRect)aRect

Discussion

aRect describes the entire divider rectangle in the receiver’s coordinates, which are flipped. If you override this method and use a custom icon to identify the divider, you may need to change the size of the divider.

Availability
See Also
Declared In
NSSplitView.h

isPaneSplitter

Returns YES if the receiver’s splitter is a bar that goes across the split view. Returns NO if the splitter is a thumb on the regular background pattern.

- (BOOL)isPaneSplitter

Availability
See Also
Declared In
NSSplitView.h

isSubviewCollapsed:

Returns YES if subview is in a collapsed state, NO otherwise.

- (BOOL)isSubviewCollapsed:(NSView *)subview

Availability
Declared In
NSSplitView.h

isVertical

Returns YES if the split bars are vertical (subviews are side by side), NO if they are horizontal (views are one on top of the other).

- (BOOL)isVertical

Discussion

By default, split bars are vertical.

Availability
See Also
Declared In
NSSplitView.h

maxPossiblePositionOfDividerAtIndex:

Returns the maximum possible position of the divider at the specified index.

- (CGFloat)maxPossiblePositionOfDividerAtIndex:(NSInteger)dividerIndex

Parameters
dividerIndex

The index of the divider.

Return Value

A CGFloat specifying the maximum possible position of the divider.

Discussion

The position is "possible" in that it is dictated by the bounds of the receiver and the current position of other dividers. "Allowable" positions are those that result from letting the delegate apply constraints to the possible positions.

You can invoke this method to determine the range of values that can be usefully passed to setPosition:ofDividerAtIndex:.

You can also invoke it from delegate methods like splitView:constrainSplitPosition:ofSubviewAt: to implement relatively complex behaviors that depend on the current state of the split view.

The results of invoking this method when adjustSubviews has not been invoked, and the subview frames are invalid, is undefined.

Availability
Declared In
NSSplitView.h

minPossiblePositionOfDividerAtIndex:

Returns the minimum possible position of the divider at the specified index.

- (CGFloat)minPossiblePositionOfDividerAtIndex:(NSInteger)dividerIndex

Parameters
dividerIndex

The index of the divider.

Return Value

A CGFloat specifying the minimum possible position of the divider.

Discussion

The position is "possible" in that it is dictated by the bounds of the receiver and the current position of other dividers. "Allowable" positions are those that result from letting the delegate apply constraints to the possible positions.

You can invoke this method to determine the range of values that can be usefully passed to setPosition:ofDividerAtIndex:.

You can also invoke it from delegate methods like splitView:constrainSplitPosition:ofSubviewAt: to implement relatively complex behaviors that depend on the current state of the split view.

The results of invoking this method when adjustSubviews has not been invoked, and the subview frames are invalid, is undefined.

Availability
Declared In
NSSplitView.h

setAutosaveName:

Sets the name under which receiver’s divider position is automatically saved.

- (void)setAutosaveName:(NSString *)autosaveName

Parameters
autosaveName

The name used to save the receiver’s state.

Discussion

If this value is nil or the string is empty no autosaving is done.

Availability
See Also
Declared In
NSSplitView.h

setDelegate:

Makes anObject the receiver’s delegate.

- (void)setDelegate:(id)anObject

Discussion

The notification messages the delegate can expect to receive are listed in “Notifications.” The delegate doesn’t need to implement all of the delegate methods.

Availability
See Also
Declared In
NSSplitView.h

setDividerStyle:

Sets the style of divider drawn between subviews.

- (void)setDividerStyle:(NSSplitViewDividerStyle)dividerStyle

Parameters
dividerStyle

The divider style. Possible values are described in “Split View Divider Styles.”

Availability
See Also
Declared In
NSSplitView.h

setIsPaneSplitter:

Sets the type of splitter.

- (void)setIsPaneSplitter:(BOOL)flag

Discussion

If flag is YES, the receiver’s splitter is a bar that goes across the split view. If flag is NO, the splitter is a thumb on the regular background pattern.

Availability
See Also
Declared In
NSSplitView.h

setPosition:ofDividerAtIndex:

Sets the position of the divider at the specified index.

- (void)setPosition:(CGFloat)position ofDividerAtIndex:(NSInteger)dividerIndex

Parameters
position

The position of the divider

dividerIndex

The index of the divider.

Discussion

The default implementation of this method behaves as if the user were attempting to drag the divider to the proposed position, so the constraints imposed by the delegate are applied and one of the views adjacent to the divider may be collapsed.

This method is not invoked by NSSplitView itself.

Availability
Declared In
NSSplitView.h

setVertical:

Sets whether the split bars are vertical.

- (void)setVertical:(BOOL)flag

Discussion

If flag is YES, they’re vertical (views are side by side); if it’s NO, they’re horizontal (views are one on top of the other). Split bars are horizontal by default.

Availability
See Also
Declared In
NSSplitView.h

Delegate Methods

splitView:additionalEffectiveRectOfDividerAtIndex:

Allows the delegate to return an additional rectangle in which mouse clicks will initiate divider dragging.

- (NSRect)splitView:(NSSplitView *)splitView additionalEffectiveRectOfDividerAtIndex:(NSInteger)dividerIndex

Parameters
splitView

The split view that sent the message.

dividerIndex

The index of the divider.

Return Value

An additional rectangle in which mouse clicks should initiate divider dragging. The rectangle should be expressed in the coordinate system defined by splitView. Returning NSZeroRect indicates no additional dragging rectangle is desired.

Discussion

If a split view has no delegate, or if its delegate does not respond to this message, only mouse clicks within the effective frame of a divider initiate divider dragging.

Availability
Declared In
NSSplitView.h

splitView:canCollapseSubview:

Allows the delegate to determine whether the user can collapse and uncollapse subview.

- (BOOL)splitView:(NSSplitView *)sender canCollapseSubview:(NSView *)subview

Discussion

If this method returns NO or is not implemented, subview can’t be collapsed. If this method returns YES, subview collapses when the user drags a divider beyond the halfway mark between its minimum size and its edge. subview uncollapses when the user drags the divider back beyond that point. To specify the minimum size, define the methods splitView:constrainMaxCoordinate:ofSubviewAt: and splitView:constrainMinCoordinate:ofSubviewAt:. Note that a subview can collapse only if you also define splitView:constrainMinCoordinate:ofSubviewAt:.

A collapsed subview is hidden but retained by the NSSplitView object, with the same size it had before it was collapsed.

Availability
Declared In
NSSplitView.h

splitView:constrainMaxCoordinate:ofSubviewAt:

Allows the delegate for sender to constrain the maximum coordinate limit of a divider when the user drags it.

- (CGFloat)splitView:(NSSplitView *)sender constrainMaxCoordinate:(CGFloat)proposedMax ofSubviewAt:(NSInteger)offset

Discussion

This method is invoked before the NSSplitView begins tracking the mouse to position a divider. You may further constrain the limits that have been already set, but you cannot extend the divider limits. proposedMax is specified in the NSSplitView’s flipped coordinate system. If the split bars are horizontal (views are one on top of the other), proposedMax is the bottom limit. If the split bars are vertical (views are side by side), proposedMax is the right limit. The initial value of proposedMax is the bottom (or right side) of the subview after the divider. offset specifies the divider the user is moving, with the first divider being 0 and going up from top to bottom (or left to right).

Availability
See Also
Declared In
NSSplitView.h

splitView:constrainMinCoordinate:ofSubviewAt:

Allows the delegate for sender to constrain the minimum coordinate limit of a divider when the user drags it.

- (CGFloat)splitView:(NSSplitView *)sender constrainMinCoordinate:(CGFloat)proposedMin ofSubviewAt:(NSInteger)offset

Discussion

This method is invoked before the NSSplitView begins tracking the cursor to position a divider. You may further constrain the limits that have been already set, but you cannot extend the divider limits. proposedMin is specified in the NSSplitView’s flipped coordinate system. If the split bars are horizontal (views are one on top of the other), proposedMin is the top limit. If the split bars are vertical (views are side by side), proposedMin is the left limit. The initial value of proposedMin is the top (or left side) of the subview before the divider. offset specifies the divider the user is moving, with the first divider being 0 and going up from top to bottom (or left to right).

Availability
See Also
Declared In
NSSplitView.h

splitView:constrainSplitPosition:ofSubviewAt:

Allows the delegate for sender to constrain the divider to certain positions.

- (CGFloat)splitView:(NSSplitView *)sender constrainSplitPosition:(CGFloat)proposedPosition ofSubviewAt:(NSInteger)offset

Discussion

If the delegate implements this method, the NSSplitView calls it repeatedly as the user moves the divider. This method returns where you want the divider to be, given proposedPosition, the cursor’s current position. offset is the divider the user is moving, with the first divider being 0 and going up from top to bottom (or from left to right).

For example, if a subview’s height must be a multiple of a certain number, use this method to return the multiple nearest to proposedPosition.

Availability
Declared In
NSSplitView.h

splitView:effectiveRect:forDrawnRect:ofDividerAtIndex:

Allows the delegate to modify the rectangle in which mouse clicks initiate divider dragging.

- (NSRect)splitView:(NSSplitView *)splitView effectiveRect:(NSRect)proposedEffectiveRect forDrawnRect:(NSRect)drawnRect ofDividerAtIndex:(NSInteger)dividerIndex

Parameters
splitView

The split view that sent the message.

proposedEffectiveRect

The proposed rectangle in which mouse clicks should initiate divider dragging. The rectangle is expressed in the coordinate system defined by splitView.

drawnRect

The frame of the divider, expressed in the coordinate system defined by splitView.

dividerIndex

The index of the divider.

Return Value

The rectangle in which mouse clicks should initiate divider dragging. The rectangle should be expressed in the coordinate system defined by splitView.

Discussion

A split view with thick dividers proposes the drawn frame as the effective frame. A split view with thin dividers proposes an effective frame that's a little larger than the drawn frame, to make it easier for the user to actually grab the divider.

If a split view has no delegate, or if its delegate does not respond to this message, the split view behaves as if it has a delegate that returns proposedEffectiveRect when sent this message.

Availability
Declared In
NSSplitView.h

splitView:resizeSubviewsWithOldSize:

Allows the delegate to specify custom sizing behavior for the subviews of the NSSplitView sender.

- (void)splitView:(NSSplitView *)sender resizeSubviewsWithOldSize:(NSSize)oldSize

Discussion

If the delegate implements this method, splitView:resizeSubviewsWithOldSize: is invoked after the NSSplitView is resized. The size of the NSSplitView before the user resized it is indicated by oldSize; the subviews should be resized such that the sum of the sizes of the subviews plus the sum of the thickness of the dividers equals the size of the NSSplitView’s new frame. You can get the thickness of a divider through the dividerThickness method.

Note that if you implement this delegate method to resize subviews on your own, the NSSplitView does not perform any error checking for you. However, you can invoke adjustSubviews to perform the default sizing behavior.

Availability
See Also
Declared In
NSSplitView.h

splitView:shouldCollapseSubview:forDoubleClickOnDividerAtIndex:

Invoked to allow a delegate to determine if a subview should collapse in response to a double click.

- (BOOL)splitView:(NSSplitView *)splitView shouldCollapseSubview:(NSView *)subview forDoubleClickOnDividerAtIndex:(NSInteger)dividerIndex

Parameters
splitView

The splitview that sent the message.

subview

The subview to collapse.

dividerIndex

The index of the divider.

Return Value

YES if the subview should collapse, NO otherwise.

Discussion

If implemented, the delegate will receive this message once for the subview before a divider when the user double-clicks on that divider, and again for the subview after the divider, but only if the delegate returned YES when sent splitView:canCollapseSubview: for the subview in question. When the delegate indicates that both subviews should be collapsed NSSplitView's behavior is undefined.

Availability
Declared In
NSSplitView.h

splitView:shouldHideDividerAtIndex:

Allows the delegate to determine whether a divider can be dragged or adjusted off the edge of the split view.

- (BOOL)splitView:(NSSplitView *)splitView shouldHideDividerAtIndex:(NSInteger)dividerIndex

Parameters
splitView

The split view that sent the message.

dividerIndex

The zero-based index of the divider.

Return Value

YES if the divider should allow dragging off the edge of the split view, resulting in it not being visible.

Discussion

If a split view has no delegate, or if its delegate does not respond to this message, the split view behaves as if it has a delegate that returns NO when sent this message.

Availability
Declared In
NSSplitView.h

splitViewDidResizeSubviews:

Invoked by the default notification center to notify the delegate that the splitview did resize its subviews.

- (void)splitViewDidResizeSubviews:(NSNotification *)aNotification

Parameters
aNotification

An NSSplitViewDidResizeSubviewsNotification notification.

Discussion

If the delegate implements this method, the delegate is automatically registered to receive this notification.

This method is invoked after the NSSplitView resizes two of its subviews in response to the repositioning of a divider.

Availability
Declared In
NSSplitView.h

splitViewWillResizeSubviews:

Invoked by the default notification center to notify the delegate that the splitview will resize its subviews.

- (void)splitViewWillResizeSubviews:(NSNotification *)aNotification

Parameters
aNotification

An NSSplitViewWillResizeSubviewsNotification notification.

Discussion

If the delegate implements this method, the delegate is automatically registered to receive this notification.

This method is invoked before the NSSplitView resizes two of its subviews in response to the repositioning of a divider.

Availability
Declared In
NSSplitView.h

Constants

Split View Divider Styles

These constants specify the possible divider styles used by dividerStyle and setDividerStyle:.

enum {
   NSSplitViewDividerStyleThick = 1,
   NSSplitViewDividerStyleThin = 2,
};
typedef NSInteger NSSplitViewDividerStyle;

Constants
NSSplitViewDividerStyleThick

A thick style divider is displayed between subviews. This is the default.

Available in Mac OS X v10.5 and later.

Declared in NSSplitView.h.

NSSplitViewDividerStyleThin

A thin style divider is displayed between subviews.

Available in Mac OS X v10.5 and later.

Declared in NSSplitView.h.

Notifications

NSSplitView declares and posts the following notifications. In addition, it posts notifications declared by its superclass, NSView. See the NSView class specification for more information.

NSSplitViewDidResizeSubviewsNotification

Posted after an NSSplitView changes the sizes of some or all of its subviews. The notification object is the NSSplitView that resized its subviews.

Note: In Mac OS X v10.5 and later if the notification is sent because the user is dragging a divider, the userInfo dictionary contains a key @"NSSplitViewDividerIndex" containing an NSInteger-wrapped NSNumber that is the index of the divider being dragged. Earlier versions of Mac OS X do not return a user info dictionary in any situation.

Availability
See Also
Declared In
NSSplitView.h

NSSplitViewWillResizeSubviewsNotification

Posted before an NSSplitView changes the sizes of some or all of its subviews. The notification object is the NSSplitView object that is about to resize its subviews.

Note: In Mac OS X v10.5 and later if the notification is sent because the user is dragging a divider, the userInfo dictionary contains a key @"NSSplitViewDividerIndex" containing an NSInteger-wrapped NSNumber that is the index of the divider being dragged. Earlier versions of Mac OS X do not return a user info dictionary in any situation.

Availability
See Also
Declared In
NSSplitView.h

Next Page > Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-04-08)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.