---

NSDrawer Class Reference

Overview

An NSDrawer object is a user interface element that contains and displays view objects including NSTextView, NSScrollView, NSBrowser, and other classes that inherit from NSView. A drawer is associated with a window, called its parent, and can appear only while its parent is visible onscreen. A drawer cannot be moved or ordered independently of a window, but is instead attached to one edge of its parent and moves along with it.

Tasks

Creating an NSDrawer

• – initWithContentSize:preferredEdge:

Opening and Closing Drawers

• – close
• – close:
• – open
• – open:
• – openOnEdge:
• – toggle:

Managing Drawer Size

• – contentSize
• – leadingOffset
• – maxContentSize
• – minContentSize
• – setContentSize:
• – setLeadingOffset:
• – setMaxContentSize:
• – setMinContentSize:
• – setTrailingOffset:
• – trailingOffset

Managing Drawer Edges

• – edge
• – preferredEdge
• – setPreferredEdge:

Managing a Drawer’s Views

• – contentView
• – parentWindow
• – setContentView:
• – setParentWindow:

Accessing Other Drawer Information

• – delegate
• – setDelegate:
• – state

Opening a drawer

• – drawerDidOpen:  delegate method
• – drawerShouldOpen:  delegate method
• – drawerWillOpen:  delegate method

Resizing a drawer

• – drawerWillResizeContents:toSize:  delegate method

Closing a drawer

• – drawerDidClose:  delegate method
• – drawerShouldClose:  delegate method
• – drawerWillClose:  delegate method

Instance Methods

close

If the receiver is open, this method closes it.

- (void)close

Discussion

Calling close on a closed drawer does nothing. You can get the state of a drawer by sending it state.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – open

Declared In

NSDrawer.h

close:

An action method to close the receiver.

- (void)close:(id)sender

Parameters

sender

A user interface element, such as a button or menu item, that invokes the action method.

Discussion

This method is an action method and likely would not be invoked programatically. Rather, it is an action that each drawer comes with in Interface Builder.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – open:

Declared In

NSDrawer.h

contentSize

Returns the size of the receiver’s content area.

- (NSSize)contentSize

Return Value

The size of the receiver’s content area.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setContentSize:
• – setMaxContentSize:
• – setMinContentSize:

Declared In

NSDrawer.h

contentView

Returns the receiver’s content view.

- (NSView *)contentView

Return Value

The receiver’s content view.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setContentView:

Declared In

NSDrawer.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver’s delegate.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Declared In

NSDrawer.h

edge

Returns the edge of the window that the receiver is connected to.

- (NSRectEdge)edge

Return Value

The edge of the parent window at which the drawer is attached. See “Constants” for a list of edge constants and locations.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

initWithContentSize:preferredEdge:

Creates a new drawer with the given size on the specified edge of the parent window.

- (id)initWithContentSize:(NSSize)contentSize preferredEdge:(NSRectEdge)edge

Parameters

contentSize

The size of the new drawer.

edge

The edge to which to attach the new drawer.

Discussion

You must specify the parent window and content view of the drawer using the methods in this class. When you create a drawer in Interface Builder, this constructor is invoked. The NSDrawer Inspector in Interface Builder allows you to set the edge, and you can specify the size by changing the content view in Interface Builder.

See “Positioning and Sizing a Drawer” for additional detail on content size and drawer positioning.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

leadingOffset

Returns the receiver’s leading offset.

- (CGFloat)leadingOffset

Return Value

The receiver’s leading offset. This is the distance from the top or left edge of the parent window to the drawer.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setLeadingOffset:

Declared In

NSDrawer.h

maxContentSize

Returns the maximum allowed size of the receiver’s content area.

- (NSSize)maxContentSize

Return Value

The maximum size of the receiver’s content area. This is useful for determining if an opened drawer would fit onscreen given the current window position.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMaxContentSize:

Declared In

NSDrawer.h

minContentSize

Returns the minimum allowed size of the receiver’s content area.

- (NSSize)minContentSize

Return Value

The minimum size of the receiver’s content area.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMinContentSize:

Declared In

NSDrawer.h

open

If the receiver is closed, this method opens it.

- (void)open

Discussion

Calling open on an open drawer does nothing. You can get the state of a drawer by sending it state. If an edge is not specified, an attempt will be made to choose an edge based on the space available to display the drawer onscreen. If you need to ensure that a drawer opens on a particular edge, use openOnEdge:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – close

Declared In

NSDrawer.h

open:

An action method to open the drawer.

- (void)open:(id)sender

Parameters

sender

A user interface element, such as a button or menu item, that invokes the action method.

Discussion

This method is an action method and likely would not be invoked programatically. Rather, it is an action that each drawer comes with in Interface Builder.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – close:

Declared In

NSDrawer.h

openOnEdge:

Causes the receiver to open on the specified edge of the parent window.

- (void)openOnEdge:(NSRectEdge)edge

Parameters

edge

The edge of the parent window on which to open the receiver. See “Constants” for a list of edge constants and locations.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

parentWindow

Returns the receiver’s parent window.

- (NSWindow *)parentWindow

Return Value

The receiver’s parent window. By definition, a drawer can appear onscreen only if it has a parent.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setParentWindow:

Declared In

NSDrawer.h

preferredEdge

Returns the receiver’s preferred, or default, edge.

- (NSRectEdge)preferredEdge

Return Value

The receiver’s preferred edge. If a drawer is told to open and an edge is not specified at that time, it opens on its preferred edge. When you a create a drawer with Interface Builder, the preferred edge is set to the left by default.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setPreferredEdge:

Declared In

NSDrawer.h

setContentSize:

Sets the size of the receiver’s content area.

- (void)setContentSize:(NSSize)size

Parameters

size

The new size of the receiver’s content area. See “Positioning and Sizing a Drawer” for additional detail.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – contentSize
• – setMaxContentSize:
• – setMinContentSize:

Declared In

NSDrawer.h

setContentView:

Sets the receiver’s content view.

- (void)setContentView:(NSView *)aView

Parameters

aView

The content view of the receiver. Rather than connect a drawer to its content view in Interface Builder, you can specify it programatically with this method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – contentView

Declared In

NSDrawer.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters

anObject

The object to assign as the receiver’s delegate.

Discussion

You may find it useful to associate a delegate with a drawer, especially since drawers do not open and close instantly. A drawer’s delegate can better regulate drawer behavior. However, a drawer can be used without a delegate.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – delegate

Declared In

NSDrawer.h

setLeadingOffset:

Sets the receiver’s leading offset.

- (void)setLeadingOffset:(CGFloat)offset

Parameters

offset

The leading offset of the receiver. This is the distance from the top or left edge of the parent window to the drawer. See “Positioning and Sizing a Drawer” for additional detail.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – leadingOffset
• – setTrailingOffset:

Declared In

NSDrawer.h

setMaxContentSize:

Specifies the maximum size of the receiver’s content area.

- (void)setMaxContentSize:(NSSize)size

Parameters

size

The new maximum size of the receiver’s content area. See “Positioning and Sizing a Drawer” for additional detail.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – maxContentSize

Declared In

NSDrawer.h

setMinContentSize:

Specifies the minimum size of the receiver’s content area.

- (void)setMinContentSize:(NSSize)size

Parameters

size

The new minimum size of the receiver’s content area. See “Positioning and Sizing a Drawer” for additional detail.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – minContentSize

Declared In

NSDrawer.h

setParentWindow:

Sets the receiver’s parent window.

- (void)setParentWindow:(NSWindow *)parent

Parameters

parent

The parent window of the receiver. Every drawer must be associated with a parent window for a drawer to appear onscreen. If this argument is nil, the drawer is removed from its parent.

Discussion

Changes in a drawer’s parent window do not take place while the drawer is onscreen; they are delayed until the drawer next closes.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – parentWindow

Declared In

NSDrawer.h

setPreferredEdge:

Sets the receiver’s preferred, or default, edge.

- (void)setPreferredEdge:(NSRectEdge)preferredEdge

Parameters

preferredEdge

The edge on which the receiver should open by default. A drawer can be told to open on a specific edge; if an edge is not specified, however, it opens on the preferred edge.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – preferredEdge

Declared In

NSDrawer.h

setTrailingOffset:

Sets the receiver’s trailing offset.

- (void)setTrailingOffset:(CGFloat)offset

Parameters

offset

The receiver’s trailing offset. This is the distance to the right or bottom edge of the drawer from the right or bottom edge of the parent window. See “Positioning and Sizing a Drawer” for additional detail.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – leadingOffset

Declared In

NSDrawer.h

state

Returns the state of the receiver.

- (NSInteger)state

Return Value

The drawer's state. Refer to NSDrawerState for a list of possible values.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

toggle:

Toggles the drawer open or closed.

- (void)toggle:(id)sender

Parameters

sender

The sender of the message.

Discussion

If the receiver is closed, or in the process of either opening or closing, it is opened. Otherwise, the drawer is closed.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

trailingOffset

Returns the receiver’s trailing offset.

- (CGFloat)trailingOffset

Return Value

The receiver’s trailing offset. This is the distance to the right or bottom edge of the drawer from the right or bottom edge of the parent window.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTrailingOffset:

Declared In

NSDrawer.h

Delegate Methods

drawerDidClose:

Notifies the delegate that the drawer has closed.

- (void)drawerDidClose:(NSNotification *)notification

Parameters

notification

An NSDrawerDidCloseNotification notification sent by the default notification center immediately after the drawer has closed.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerDidOpen:

Notifies the delegate that the drawer has opened.

- (void)drawerDidOpen:(NSNotification *)notification

Parameters

notification

An NSDrawerDidOpenNotification notification, sent by the default notification center immediately after the drawer has opened.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerShouldClose:

Requests permission for a drawer to close.

- (BOOL)drawerShouldClose:(NSDrawer *)sender

Parameters

sender

The drawer being closed.

Return Value

YES to allow the drawer to close; NO to prevent it from closing.

Discussion

This method is invoked on user-initiated attempts to close a drawer by dragging it or when the close: method is called.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerShouldOpen:

Requests permission for a drawer to open.

- (BOOL)drawerShouldOpen:(NSDrawer *)sender

Parameters

sender

The drawer requesting permission to open.

Return Value

YES if the drawer should open; NO to prevent the drawer from opening.

Discussion

This method is invoked on user-initiated attempts to open a drawer by dragging it or when the open: method is called.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerWillClose:

Notifies the delegate the the drawer will close.

- (void)drawerWillClose:(NSNotification *)notification

Parameters

notification

An NSDrawerWillCloseNotification notification sent by the default notification center immediately before the drawer is closed.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerWillOpen:

Notifies the delegate that the drawer will open.

- (void)drawerWillOpen:(NSNotification *)notification

Parameters

notification

An NSDrawerWillOpenNotification notification, sent by the default notification center immediately before the drawer is opened.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

drawerWillResizeContents:toSize:

Invoked when the user resizes the drawer or parent.

- (NSSize)drawerWillResizeContents:(NSDrawer *)sender toSize:(NSSize)contentSize

Parameters

sender

The drawer being resized.

contentSize

The proposed new size of the drawer.

Return Value

The size that the drawer should be resized to. To resize to a different size, simply return the desired size from this method; to avoid resizing, return the current size.

Discussion

The receiver’s minimum and maximum size constraints have already been applied when this method is invoked. While the user is resizing an NSDrawer or its parent, the delegate is sent a series of windowWillResize messages as the NSDrawer or parent window is dragged.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

Constants

NSDrawerState

These constants specify the possible states of a drawer.

typedef enum _NSDrawerState {
   NSDrawerClosedState  = 0,
   NSDrawerOpeningState = 1,
   NSDrawerOpenState    = 2,
   NSDrawerClosingState = 3
} NSDrawerState;

Constants

NSDrawerClosedState

The drawer is closed (not visible onscreen).

Available in Mac OS X v10.0 and later.

Declared in NSDrawer.h

NSDrawerOpeningState

The drawer is in the process of opening.

Available in Mac OS X v10.0 and later.

Declared in NSDrawer.h

NSDrawerOpenState

The drawer is open (visible onscreen).

Available in Mac OS X v10.0 and later.

Declared in NSDrawer.h

NSDrawerClosingState

The drawer is in the process of closing.

Available in Mac OS X v10.0 and later.

Declared in NSDrawer.h

Discussion

These constants are returned by state.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

Notifications

NSDrawerDidCloseNotification

Posted whenever the drawer is closed.

The notification object is the NSDrawer object that closed. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

NSDrawerDidOpenNotification

Posted whenever the drawer is opened.

The notification object is the NSDrawer object that opened. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

NSDrawerWillCloseNotification

Posted whenever the drawer is about to close.

The notification object is the NSDrawerobject about to close. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

NSDrawerWillOpenNotification

Posted whenever the drawer is about to open.

The notification object is the NSDrawer object about to open. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDrawer.h

---