---

NSPathCell Class Reference

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.

Tasks

Displaying Hidden Components

• – mouseEntered:withFrame:inView:
• – mouseExited:withFrame:inView:

Setting the Allowed Types

• – allowedTypes
• – setAllowedTypes:

Setting the Control Style

• – pathStyle
• – setPathStyle:
• – setControlSize:

Setting the Object Value

• – setObjectValue:

Setting Cell Appearance

• – placeholderAttributedString
• – setPlaceholderAttributedString:
• – setPlaceholderString:
• – placeholderString
• – setBackgroundColor:
• – backgroundColor

Managing Path Components

• + pathComponentCellClass
• – rectOfPathComponentCell:withFrame:inView:
• – pathComponentCellAtPoint:withFrame:inView:
• – clickedPathComponentCell
• – pathComponentCells
• – setPathComponentCells:

Setting the Double-Click Action

• – doubleAction
• – setDoubleAction:

Setting the Path

• – URL
• – setURL:

Setting the Delegate

• – delegate
• – setDelegate:

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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

See Also

• – setPathStyle:
• – pathStyle

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 Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

See Also

• – pathStyle
• – setControlSize:

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

Para

Availability

• Available in Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

Declared in NSPathCell.h.

Declared In

NSPathCell.h

---