NSSplitView Class Reference

Inherits from
NSView : NSResponder : NSObject
Conforms to
NSAnimatablePropertyContainer (NSView)
NSUserInterfaceItemIdentification (NSView)
NSDraggingDestination (NSView)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSSplitView.h
Companion guides
Scroll View Programming Guide for Mac
View Programming Guide
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.

In OS X v10.5 and earlier adjustSubviews did not invalidate the split view’s cursor. This made it difficult to correctly animate divider positioning by sending setFrameSize: to the animator proxy of the subviews on either side of the divider and letting adjustSubviews to be invoked repeatedly during the animation. In OS X v10.6 and later adjustSubviews now invalidates its cursor so the cursor over the divider is always correct during and after such an animation.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
See Also
Declared In
NSSplitView.h

delegate

Returns the receiver’s delegate.

- (id < NSSplitViewDelegate >)delegate
Return Value

The receiver’s delegate object.

Availability
  • Available in OS X v10.0 and later.
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 of the divider drawn between the subviews.

Discussion

The default implementation of this method returns clearColor when dividerStyle returns NSSplitViewDividerStyleThick or when dividerStyle returns NSSplitViewDividerStylePaneSplitter and the receiver 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
  • Available in OS X v10.5 and later.
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
  • Available in OS X v10.5 and later.
See Also
Declared In
NSSplitView.h

dividerThickness

Returns the thickness of the divider.

- (CGFloat)dividerThickness
Return Value

The thickness of the divider.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSplitView.h

drawDividerInRect:

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

- (void)drawDividerInRect:(NSRect)aRect
Parameters
aRect

The entire divider rectangle in the receiver’s coordinate system, which is flipped.

Discussion

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
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSplitView.h

holdingPriorityForSubviewAtIndex:

Returns the priority of the subview’s width or height when resizing.

- (NSLayoutPriority)holdingPriorityForSubviewAtIndex:(NSInteger)subviewIndex
Parameters
subviewIndex

The index of the subview.

Return Value

Returns the layout priority of the subview at the index.

Discussion

The priority is the manner under which split view subviews hold their widths (for a vertical split view) or height (for a horizontal split view). The view with the lowest priority will be the first to take on additional width if the split view grows or shrinks.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSSplitView.h

isSubviewCollapsed:

Returns whether the specified view is collapsed.

- (BOOL)isSubviewCollapsed:(NSView *)subview
Parameters
subview

The subview in the split view.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSplitView.h

isVertical

Returns whether the split bars are vertical.

- (BOOL)isVertical
Return Value

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).

Discussion

By default, split bars are vertical.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
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
  • Available in OS X v10.5 and later.
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
  • Available in OS X v10.5 and later.
See Also
Declared In
NSSplitView.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSSplitViewDelegate >)theDelegate
Parameters
theDelegate

The receiver’s delegate object.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
See Also
Declared In
NSSplitView.h

setHoldingPriority:forSubviewAtIndex:

Sets the priority under which split view subviews maintain their width or height.

- (void)setHoldingPriority:(NSLayoutPriority)priority forSubviewAtIndex:(NSInteger)subviewIndex
Parameters
priority

The priority.

subviewIndex

The index of the subview

Discussion

Sets the priority under which split view subviews hold their widths (for a vertical split view) or height (for a horizontal split view). The view with the lowest priority will be the first to take on additional width if the split view grows or shrinks.

The default is NSLayoutPriorityDefaultLow. There is no reason to use the default, but you should use priorities less than NSLayoutPriorityDragThatCannotResizeWindow.

Availability
  • Available in OS X v10.8 and later.
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
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSSplitView.h

setVertical:

Sets whether the split bars are vertical.

- (void)setVertical:(BOOL)flag
Parameters
flag

If YES, the split bars are vertical (views are side by side); if NO, they’re horizontal (views are one on top of the other).

Discussion

Split bars are horizontal by default.

Availability
  • Available in OS X v10.0 and later.
See Also
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,
   NSSplitViewDividerStylePaneSplitter = 3,
};
typedef NSInteger NSSplitViewDividerStyle;
Constants
NSSplitViewDividerStyleThick

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

Available in OS X v10.5 and later.

Declared in NSSplitView.h.

NSSplitViewDividerStyleThin

A thin style divider is displayed between subviews.

Available in OS X v10.5 and later.

Declared in NSSplitView.h.

NSSplitViewDividerStylePaneSplitter

A thick style divider with a 3D appearance is displayed between subviews.

Available in OS X v10.6 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.
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.
Availability
See Also
Declared In
NSSplitView.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...