NSPathCell Class Reference

Inherits from
NSActionCell : NSCell : NSObject
Conforms to
NSOpenSavePanelDelegate
NSCoding (NSCell)
NSCopying (NSCell)
NSUserInterfaceItemIdentification (NSCell)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.5 and later.
Declared in
NSPathCell.h

Overview

NSPathCell implements the user interface of an NSPathControl object. It maintains a collection of NSPathComponentCell objects that represent a particular path to be displayed to the user.

The path shown can be set with the setURL: method. Doing so removes all displayed NSPathComponentCell objects and automatically fills the control with NSPathComponentCell objects set to have the appropriate icons, display titles, and NSURL values for the particular path component they represent. Alternatively, you can fill the control manually by setting the cell array or directly modifying existing cells.

Both an action and double-click action can be set for the path control. To find out what path component cell was clicked in the action, you can read the value of clickedPathComponentCell. When the style is set to NSPathStylePopUp, the action is still sent, and the clickedPathComponentCell value for the represented menu item is correctly set. The clickedPathComponentCell value is valid only when the action is being sent. It is also valid when the keyboard is used to invoke the action.

Automatic animated expansion of partially hidden NSPathComponentCell objects happens if you correctly call mouseEntered: and mouseExited: for each NSPathComponentCell in the NSPathCell object. This is not required if the pathStyle is set to NSPathStylePopUp, or if you wish to not have the animation.

NSPathCell supports several path display styles. NSPathStyleStandard has a light blue background with arrows indicating the path. NSPathStyleNavigationBar has more defined arrows (chevrons) and looks a little like a segmented button. NSPathStylePopUp looks and works like an NSPopUpButton object to display the full path, or, if the cell is editable, select a new path.

If the cell’s isEditable method returns YES (the default), you can drag and drop into the cell to change the value. You can constrain what can be dropped using UTIs (Uniform Type Identifiers) with setAllowedTypes: or the appropriate delegate methods on NSPathControl.

If the cell’s isSelectable method returns YES (the default), the cell's contents can automatically be dragged out. The proper UTI, filename, and URL are placed on the pasteboard. You can further control or limit this by using the appropriate delegate methods on NSPathControl.

If the cell is editable and has the path style set to NSPathStylePopUp, an additional item in the pop-up menu allows selecting another location. By default, an NSOpenPanel object is configured based on the allowed types. The NSOpenPanel object can be customized with a delegate method.

Tasks

Displaying Hidden Components

Setting the Allowed Types

Setting the Control Style

Setting the Object Value

Setting Cell Appearance

Managing Path Components

Setting the Double-Click Action

Setting the Path

Setting the Delegate

Class Methods

pathComponentCellClass

Returns the class used to create pathComponentCell objects when automatically filling up the control.

+ (Class)pathComponentCellClass;
Return Value

The class used to create NSPathComponentCell objects.

Discussion

Subclasses can override this method to return a custom cell class that is automatically used. By default, the method returns [NSPathComponentCell class], or a specialized subclass thereof.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

Instance Methods

allowedTypes

Returns the component types allowed in the path when the cell is editable.

- (NSArray *)allowedTypes;
Return Value

An array of strings representing either file extensions or UTIs. Can be nil, the default value, allowing all types, or an empty array, allowing nothing.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

backgroundColor

Returns the current background color of the receiver.

- (NSColor *)backgroundColor
Return Value

The background color.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

clickedPathComponentCell

Returns the clicked cell.

- (NSPathComponentCell *)clickedPathComponentCell
Return Value

The component cell that was clicked, or nil, if no cell has been clicked.

Discussion

The value returned is generally valid only when the action or double-click action is being sent.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

delegate

Returns the receiver’s delegate.

- (id)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

doubleAction

Returns the receiver’s double-click action method.

- (SEL)doubleAction
Return Value

The action method invoked when the user double-clicks the receiver.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

mouseEntered:withFrame:inView:

Displays the cell component over which the mouse is hovering.

- (void)mouseEntered:(NSEvent *)event withFrame:(NSRect)frame inView:(NSView *)view;
Parameters
event

The mouse-entered event.

frame

The frame in which the cell is located.

view

The view in which the cell is located.

Discussion

The NSPathCell object dynamically animates to display the component that the mouse is hovering over using mouse-entered and mouse-exited events. The control should call these methods to correctly display the hovered component to the user. The control can acquire rectangles to track using rectOfPathComponentCell:withFrame:inView:.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

mouseExited:withFrame:inView:

Hides the cell component over which the mouse is hovering.

- (void)mouseExited:(NSEvent *)event withFrame:(NSRect)frame inView:(NSView *)view;
Parameters
event

The mouse-exited event.

frame

The frame in which the cell is located.

view

The view in which the cell is located.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

pathComponentCellAtPoint:withFrame:inView:

Returns the cell located at the given point within the given frame of the given view.

- (NSPathComponentCell *)pathComponentCellAtPoint:(NSPoint)point withFrame:(NSRect)frame inView:(NSView *)view;
Parameters
point

The point within the returned cell.

frame

The frame within which the point is located.

view

The view within which the frame is located.

Return Value

The component cell within which the given point is located, or nil if no cell exists at that location.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

pathComponentCells

Returns an array of the NSPathComponentCell objects currently being displayed.

- (NSArray *)pathComponentCells
Return Value

The array of NSPathComponentCell objects.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

pathStyle

Returns the receiver’s path style.

- (NSPathStyle)pathStyle
Return Value

The style of the path.

Availability
  • Available in OS X v10.5 and later.
See Also
  • – setPathStyle:
Declared In
NSPathCell.h

placeholderAttributedString

Returns the placeholder attributed string.

- (NSAttributedString *)placeholderAttributedString;
Return Value

The placeholder attributed string.

Discussion

If the NSPathCell object contains no NSPathComponentCell objects, the placeholder attributed string is drawn in their place, if it is not nil. If the placeholder attributed string is nil, the (non-attributed) placeholder string is drawn with default attributes, if it is not nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

placeholderString

Returns the placeholder string.

- (NSString *)placeholderString;
Return Value

The placeholder string.

Discussion

If the NSPathCell object contains no NSPathComponentCell objects, the placeholder attributed string is drawn in their place, if it is not nil. If the placeholder attributed string is nil, the (non-attributed) placeholder string is drawn with default attributes, if it is not nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

rectOfPathComponentCell:withFrame:inView:

Returns the current rectangle being displayed for a given path component cell, with respect to a given frame in a given view.

- (NSRect)rectOfPathComponentCell:(NSPathComponentCell *)cell withFrame:(NSRect)frame inView:(NSView *)view;
Parameters
cell

The path component cell.

frame

The frame of the view in which the cell appears.

view

The view in which the cell appears.

Return Value

The rectangle occupied by the path component cell. NSZeroRect is returned if cell is not found or is not currently visible.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setAllowedTypes:

Sets the component types allowed in the path when the cell is editable.

- (void)setAllowedTypes:(NSArray *)allowedTypes;
Parameters
allowedTypes

An array of strings representing either file extensions or UTIs. Can be nil, the default value, allowing all types.

Discussion

The allowedTypes array can contain file extensions (without the period that begins the extension) or UTIs. To allow folders, include the public.folder identifier. To allow any type, use nil. If the value of allowedTypes is an empty array, nothing is allowed. The default value is nil, allowing all types.

If the cell is editable and its type is NSPathStylePopUp, a Choose item is included to enable selection of a different path by invoking an Open panel. The allowed types are passed to the Open panel to filter out other types. The allowed types are also used with drag and drop to indicate if a drop is allowed.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setBackgroundColor:

Sets the receiver’s background color.

- (void)setBackgroundColor:(NSColor *)color
Parameters
color

The color to be drawn.

Discussion

By default, the background is set to a light blue color for NSPathStyleStandard, and nil for the other styles. You can use [NSColor clearColor] to make the background transparent.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setControlSize:

Sets the receiver’s control size.

- (void)setControlSize:(NSControlSize)size
Parameters
size

The new control size.

Discussion

NSPathCell properly respects the control size for the NSPathStyleStandard and NSPathStylePopUp styles. When the control size is set, the new size is propagated to subcells. When the path style is set to NSPathStyleNavigationBar, you cannot change the control size, and it is always set to NSSmallControlSize. Attempting to change the control size when the path style is NSPathStyleNavigationBar causes an assertion. Setting the path style to NSPathStyleNavigationBar forces the control size to be NSSmallControlSize.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSPathCell.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)delegate
Parameters
delegate

the object to set as the receiver’s delegate.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setDoubleAction:

Sets the receiver’s double-click action.

- (void)setDoubleAction:(SEL)action
Parameters
action

The action method to invoke when the receiver is double-clicked.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setObjectValue:

Sets the receiver’s object value.

- (void)setObjectValue:(id <NSCopying>)obj;
Parameters
obj

The new object value for the cell.

Discussion

If setObjectValue: is called with an NSURL object, setURL: is automatically called. The objectValue method returns the most recently set URL value. The setObjectValue: method can also take a string value, with the items separated by the path separator (/). Any other value is a programming error and will cause an assertion.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setPathComponentCells:

Sets the array of NSPathComponentCell objects currently being displayed.

- (void)setPathComponentCells:(NSArray *)cells
Parameters
cells

An array of NSPathComponentCell objects.

Discussion

Each item in the array must be an instance of NSPathComponentCell or a subclass thereof. You cannot set this value to nil, but you can set it to an empty array using, for example, [NSArray array].

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setPathStyle:

Sets the receiver’s path style.

- (void)setPathStyle:(NSPathStyle)style
Parameters
style

The new path style.

Discussion

See setControlSize: for information about path style and control size dependencies.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSPathCell.h

setPlaceholderAttributedString:

Sets the value of the placeholder attributed string.

- (void)setPlaceholderAttributedString:(NSAttributedString *)string;
Parameters
string

The string to set for the placeholder attributed string.

Discussion

If the NSPathCell object contains no NSPathComponentCell objects, the placeholder attributed string is drawn in their place, if it is not nil. If the placeholder attributed string is nil, the (non-attributed) placeholder string is drawn with default attributes, if it is not nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setPlaceholderString:

Sets the value of the placeholder string.

- (void)setPlaceholderString:(NSString *)string;
Parameters
string

The string to set for the placeholder.

Discussion

If the NSPathCell object contains no NSPathComponentCell objects, the placeholder attributed string is drawn in their place, if it is not nil. If the placeholder attributed string is nil, the (non-attributed) placeholder string is drawn with default attributes, if it is not nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

setURL:

Sets the value of the path displayed by the receiver.

- (void)setURL:(NSURL *)url
Parameters
url

The new path value to display.

Discussion

When setting, an array of NSPathComponentCell objects is automatically set, based on the path in url. The type of NSPathComponentCell objects created can be controlled by subclassing NSPathCell and overriding pathComponentCellClass.

If url is a file URL (returns YES from isFileURL), the images are automatically filled with file icons, if the path exists. The URL value itself is stored in the objectValue property of the cell.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

URL

Returns the path displayed by the receiver.

- (NSURL *)URL
Return Value

The path value.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPathCell.h

Constants

NSPathStyle

NSPathStyle constants represent the different visual and behavioral styles an NSPathControl or NSPathCell object can have.

enum {
   NSPathStyleStandard,
   NSPathStyleNavigationBar,
   NSPathStylePopUp,
};
typedef NSInteger NSPathStyle;
Constants
NSPathStyleStandard

The standard display style and behavior. All path component cells are displayed with an icon image and component name. If the path can not fully be displayed, the middle parts are truncated as required.

Available in OS X v10.5 and later.

Declared in NSPathCell.h.

NSPathStyleNavigationBar

The navigation bar display style and behavior. Similar to the NSPathStyleStandard with the navigation bar drawing style. Also known as the breadcrumb style.

Available in OS X v10.5 and later.

Declared in NSPathCell.h.

NSPathStylePopUp

The pop-up display style and behavior. Only the last path component is displayed with an icon image and component name. The full path is shown when the user clicks on the cell. If the cell is editable, a Choose item is included to enable selecting a different path.

Available in OS X v10.5 and later.

Declared in NSPathCell.h.

Declared In
NSPathCell.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-06-09)

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