PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

NSSplitView


Inherits from:
NSView : NSResponder : NSObject
Conforms to:
NSCoding
(NSResponder)
NSObject (NSObject)
Declared in:
AppKit/NSSplitView.h




Class Description


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. To have vertical split bars (so the views are side by side), use the method setVertical:. The rest of this section assumes you have horizontal split bars and gives information on vertical split bars in parentheses.

The NSSplitView resizes its subviews so that each subview is the same width (or height) as the NSSplitView, and the total of the subviews' heights (or widths), plus the total of the dividers' thicknesses, is equal to the height (or width) of the NSSplitView. The NSSplitView positions its subviews so that the first subview is at the top (or left) of the NSSplitView, and each successive subview is positioned below (or to the right of) the previous one. The user can set the height (or width) of two subviews by moving a horizontal (or vertical) bar called the divider, which makes one subview smaller and the other larger. Programmatically, you adjust the relative height of subviews simply by modifying the frame of each of the subviews.

Generally, you'll create an NSSplitView in Interface Builder by selecting the subviews and choosing the Group in Split View command. To add and remove subview to an NSSplitView programmatically, use the NSView methods addSubview: and removeFromSuperview.

When a mouse-down occurs in an NSSplitView's divider, the NSSplitView determines the limits of the divider's travel and tracks the mouse to allow the user to drag the divider within these limits. With the following mouse-up, the NSSplitView resizes the two affected subviews, informs the delegate that the subviews were resized, and displays the affected views and divider. The NSSplitView's delegate can constrain the travel of specific dividers by implementing the method splitView:constrainMaxCoordinate:ofSubviewAt:, splitView:constrainMinCoordinate:ofSubviewAt:, or splitView:constrainSplitPosition:ofSubviewAt:

When the NSSplitView is displayed-whether it's being displayed for the first time or redisplayed because the user resized the NSSplitView's window-it checks to see if its subviews are properly tiled. If not, it invokes the delegate method splitView:resizeSubviewsWithOldSize:, allowing the delegate to specify the heights (or widths) of specific subviews. If the delegate doesn't implement this method, the NSSplitView sends adjustSubviews to itself to resize the subviews proportionately. Note that the NSSplitView doesn't call the delegate methods splitView:constrainMaxCoordinate:ofSubviewAt:, splitView:constrainMinCoordinate:ofSubviewAt:, or splitView:constrainSplitPosition:ofSubviewAt: and may resize its subviews in a way that isn't allowed by these delegate methods.




Method Types


Managing component views
- adjustSubviews
- dividerThickness
- drawDividerInRect:
Managing orientation
- isVertical
- setVertical:
Assigning a delegate
- delegate
- setDelegate:


Instance Methods



adjustSubviews

- (void)adjustSubviews

Adjusts the sizes of the NSSplitView's subviews so they (plus the dividers) fill the NSSplitView. The subviews are resized proportionally; the size of a subview relative to the other subviews doesn't change.

See Also: - setDelegate:, setFrame: (NSView)



delegate

- (id)delegate

Returns the NSSplitView's delegate.

dividerThickness

- (float)dividerThickness

Returns the thickness of the divider. You can subclass NSSplitView and override this method to change the divider's size, if necessary.

See Also: - drawDividerInRect:



drawDividerInRect:

- (void)drawDividerInRect:(NSRect)aRect

Draws the divider between two of the NSSplitView's subviews. aRect describes the entire divider rectangle in the NSSplitView's coordinates, which are flipped. The default implementation draws a default "dimple" image to the center of aRect; if you override this method and use a different icon to identify the divider, you may want to change the size of the divider.

See Also: - dividerThickness, - compositeToPoint:operation: (NSImage)



isVertical

- (BOOL)isVertical

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

See Also: - setVertical:



setDelegate:

- (void)setDelegate:(id)anObject

Makes anObject the NSSplitView's delegate. 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.

setVertical:

- (void)setVertical:(BOOL)flag

Sets whether the split bars are vertical. 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.

See Also: - isVertical




Methods Implemented By the Delegate


splitView:canCollapseSubview:

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

Allows the delegate to determine whether the user can collapse and un-collapse subview. If this method returns NO or is undefined, 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 un-collapses 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



splitView:constrainMaxCoordinate:ofSubviewAt:

- (float)splitView:(NSSplitView *)sender constrainMaxCoordinate:(float)proposedMax ofSubviewAt:(int)offset

Lets delegate constrain the maximum coordinate limit of a divider when the user drags it. Invoke this method 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).

See Also: - isVertical



splitView:constrainMinCoordinate:ofSubviewAt:

- (float)splitView:(NSSplitView *)sender constrainMinCoordinate:(float)proposedMin ofSubviewAt:(int)offset

Lets delegate constrain the minimum coordinate limit of a divider when the user drags it. Invoke this method 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. 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).

See Also: - isVertical



splitView:constrainSplitPosition:ofSubviewAt:

- (float)splitView:(NSSplitView *)splitView constrainSplitPosition:(float)proposedPosition ofSubviewAt:(int)offset

Allows the delegate to constrain the divider to certain positions. 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 mouse'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.



splitView:resizeSubviewsWithOldSize:

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

Allows the delegate to specify custom sizing behavior for the subviews of the NSSplitView. 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.

See Also: adjustSubviews, setFrame: (NSView)



splitViewDidResizeSubviews:

- (void)splitViewDidResizeSubviews:(NSNotification *)aNotification

Sent by the default notification center to the delegate; aNotification is always an NSSplitViewDidResizeSubviewsNotification. 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.

splitViewWillResizeSubviews:

- (void)splitViewWillResizeSubviews:(NSNotification *)aNotification

Sent by the default notification center to the delegate; aNotification is always an NSSplitViewWillResizeSubviewsNotification. 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.


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

This notification contains a notification object but no userInfo dictionary. The notification object is the NSSplitView that resized its subviews.

Posted after the NSSplitView changes the sizes of some or all of its subviews.

See Also: - splitViewDidResizeSubviews:

NSSplitViewWillResizeSubviewsNotification

This notification contains a notification object but no userInfo dictionary. The notification object is the NSSplitView object that is about to resize its subviews.

Posted before the NSSplitView changes the sizes of some or all of its subviews.

See Also: splitViewWillResizeSubviews:



Table of Contents