Mac Developer Library

Developer

AppKit Framework Reference NSPathCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSPathCell

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 YEStrue (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 YEStrue (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.

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.
  • Displays the cell component over which the mouse is hovering.

    Declaration

    Swift

    func mouseEntered(_ event: NSEvent, withFrame frame: NSRect, inView view: NSView)

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Hides the cell component over which the mouse is hovering.

    Declaration

    Swift

    func mouseExited(_ event: NSEvent, withFrame frame: NSRect, inView view: NSView)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var allowedTypes: [AnyObject]?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var allowedTypes: [AnyObject]?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the receiver’s object value.

    Declaration

    Swift

    func setObjectValue(_ obj: NSCopying?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the placeholder attributed string.

    Declaration

    Swift

    @NSCopying var placeholderAttributedString: NSAttributedString?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the value of the placeholder attributed string.

    Declaration

    Swift

    @NSCopying var placeholderAttributedString: NSAttributedString?

    Objective-C

    @property(copy) NSAttributedString *placeholderAttributedString

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the value of the placeholder string.

    Declaration

    Swift

    var placeholderString: String?

    Objective-C

    @property(copy) NSString *placeholderString

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the placeholder string.

    Declaration

    Swift

    var placeholderString: String?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the receiver’s background color.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *backgroundColor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the current background color of the receiver.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *backgroundColor

    Return Value

    The background color.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    class func pathComponentCellClass() -> AnyClass

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func rectOfPathComponentCell(_ cell: NSPathComponentCell, withFrame frame: NSRect, inView view: NSView) -> NSRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func pathComponentCellAtPoint(_ point: NSPoint, withFrame frame: NSRect, inView view: NSView) -> NSPathComponentCell?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the clicked cell.

    Declaration

    Swift

    var clickedPathComponentCell: NSPathComponentCell? { get }

    Objective-C

    @property(readonly, strong) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of the NSPathComponentCell objects currently being displayed.

    Declaration

    Swift

    var pathComponentCells: [AnyObject]

    Objective-C

    @property(copy) NSArray *pathComponentCells

    Return Value

    The array of NSPathComponentCell objects.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the array of NSPathComponentCell objects currently being displayed.

    Declaration

    Swift

    var pathComponentCells: [AnyObject]

    Objective-C

    @property(copy) NSArray *pathComponentCells

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the receiver’s double-click action method.

    Declaration

    Swift

    var doubleAction: Selector

    Objective-C

    @property SEL doubleAction

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the receiver’s double-click action.

    Declaration

    Swift

    var doubleAction: Selector

    Objective-C

    @property SEL doubleAction

    Parameters

    action

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the path displayed by the receiver.

    Declaration

    Swift

    @NSCopying var URL: NSURL?

    Objective-C

    @property(copy) NSURL *URL

    Return Value

    The path value.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • setURL: - setURL: Available in OS X v10.5 through OS X v10.9

    Sets the value of the path displayed by the receiver.

    Declaration

    Objective-C

    - (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 YEStrue 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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 through OS X v10.9.

  • Returns the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSPathCellDelegate?

    Objective-C

    @property(assign) id<NSPathCellDelegate> delegate

    Return Value

    The receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSPathCellDelegate?

    Objective-C

    @property(assign) id<NSPathCellDelegate> delegate

    Parameters

    delegate

    the object to set as the receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    enum NSPathStyle : Int { case Standard case PopUp case NavigationBar }

    Objective-C

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

    Constants

    • Standard

      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.

    • NavigationBar

      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.

      Deprecated in OS X v10.7.

    • PopUp

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.