ADC Home > Reference Library > Reference > Cocoa > Events & Other Input > NSBrowser Class Reference >

Next Page > Hide TOC

NSBrowser Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSBrowser.h
Related sample code

Overview

This class provides a user interface for displaying and selecting items from a list of data or from hierarchically organized lists of data such as directory paths. Instances of this class are known as browsers. When working with a hierarchy of data, the levels are displayed in columns, which are indexed from left to right.

This class uses the NSBrowserCell class to implement its user interface.

Browsers have the following components:

To the user, browsers display data in columns and rows within each column. These components are arranged in the following component hierarchy:

Browser
|---Columns [1..*]
    |---Scroll view
       |---Matrix
           |---Rows [0..*]

Tasks

Configuring Browsers

Getting Browser Information

Managing Component Types

Managing Selection Behavior

Managing Selection

Accessing Components

Managing the Path

Managing Columns

Accessing Column Titles

Scrolling

Dragging

Getting Column Frames

Managing Actions

Handling Mouse-Click Events

Sizing

Displaying Expansion Tooltips

Class Methods

cellClass

Returns the NSBrowserCell class.

+ (Class)cellClass

Return Value

Always returns the NSBrowserCell class (even if the developer has sent a setCellClass: message to a particular instance).

Discussion

This method is used by NSControl during initialization and is not meant to be used by applications.

Availability
See Also
Declared In
NSBrowser.h

removeSavedColumnsWithAutosaveName:

Removes the column configuration data stored under the given name from the application’s user defaults.

+ (void)removeSavedColumnsWithAutosaveName:(NSString *)name

Parameters
name

The name of the column configuration data to remove.

Availability
See Also
Declared In
NSBrowser.h

Instance Methods

acceptsArrowKeys

Returns a Boolean value indicating whether the browser allows navigation using the arrow keys.

- (BOOL)acceptsArrowKeys

Return Value

YES if the arrow keys are enabled; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

addColumn

Adds a column to the right of the last column.

- (void)addColumn

Availability
See Also
Declared In
NSBrowser.h

allowsBranchSelection

Returns a Boolean value indicating whether the user can select branch items.

- (BOOL)allowsBranchSelection

Return Value

YES if the user can select branch items when multiple selection is enabled; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

allowsEmptySelection

Returns a Boolean value indicating whether there can be nothing selected.

- (BOOL)allowsEmptySelection

Return Value

YES if the browser allows the selection to be empty; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

allowsMultipleSelection

Returns a Boolean value indicating whether the user can select multiple items.

- (BOOL)allowsMultipleSelection

Return Value

YES if the browser allows the user to select multiple items at once; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

allowsTypeSelect

Indicates whether the receiver allows keystroke-based selection (type select).

- (BOOL)allowsTypeSelect

Return Value

YES (default) when the receiver allows keystroke-based selection, NO otherwise.

Availability
See Also
Declared In
NSBrowser.h

backgroundColor

Provides the receiver’s background color. Default: [NSColor whiteColor].

- (NSColor *)backgroundColor

Return Value

The receiver’s background color.

Default: [NSColor whiteColor]

Availability
See Also
Declared In
NSBrowser.h

canDragRowsWithIndexes:inColumn:withEvent:

Indicates whether the receiver can attempt to initiate a drag of the given rows for the given event.

- (BOOL)canDragRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex withEvent:(NSEvent *)dragEvent

Parameters
rowIndexes

Rows the user is dragging

columnIndex

Column containing the rows the user is dragging.

dragEvent

Mouse-drag event.

Return Value

YES when rowIndexes identifies at least one row and all the identified rows are enabled, NO otherwise.

Availability
See Also
Declared In
NSBrowser.h

cellPrototype

Returns the receiver’s prototype NSCell.

- (id)cellPrototype

Return Value

The prototype NSCell. The prototype NSCell instance is copied to display items in the matrices of the browser.

Availability
See Also
Declared In
NSBrowser.h

columnContentWidthForColumnWidth:

Given the column width, returns the content width.

- (CGFloat)columnContentWidthForColumnWidth:(CGFloat)columnWidth

Parameters
columnWidth

The width of the column. This width is the entire scrolling text view.

Return Value

The width of the content for the column. This is the width of the matrix in the column.

Availability
See Also
Declared In
NSBrowser.h

columnOfMatrix:

Returns the column number in which the given matrix is located.

- (NSInteger)columnOfMatrix:(NSMatrix *)matrix

Parameters
matrix

The matrix for which to return the column number.

Return Value

The index of the column in which the specified matrix appears.

Availability
See Also
Declared In
NSBrowser.h

columnResizingType

Returns the receiver’s column resizing type.

- (NSBrowserColumnResizingType)columnResizingType

Return Value

A constant indicating the column resizing type. Possible return values are described in NSBrowserColumnResizingType. The default is NSBrowserAutoColumnResizing

Availability
See Also
Declared In
NSBrowser.h

columnsAutosaveName

Returns the name used to automatically save the receiver’s column configuration.

- (NSString *)columnsAutosaveName

Return Value

The name used to save the column configuration.

Availability
See Also
Declared In
NSBrowser.h

columnWidthForColumnContentWidth:

Given the content width, returns the column width.

- (CGFloat)columnWidthForColumnContentWidth:(CGFloat)columnContentWidth

Parameters
columnContentWidth

The width of the column's content (the width of the the matrix in the column).

Return Value

The width of the column (the width of the entire scrolling text view).

Discussion

For example, to guarantee that 16 pixels of your browser cell are always visible, call:

[browser setMinColumnWidth: [browser columnWidthForColumnContentWidth:16]]
Availability
See Also
Declared In
NSBrowser.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver's delegate.

Availability
See Also
Declared In
NSBrowser.h

displayAllColumns

Updates the receiver to display all loaded columns.

- (void)displayAllColumns

Availability
See Also
Declared In
NSBrowser.h

displayColumn:

Updates the receiver to display the given column.

- (void)displayColumn:(NSInteger)column

Parameters
column

The index of the column to display.

Availability
See Also
Declared In
NSBrowser.h

doClick:

Responds to (single) mouse clicks in a column of the receiver.

- (void)doClick:(id)sender

Availability
See Also
Declared In
NSBrowser.h

doDoubleClick:

Responds to double clicks in a column of the receiver.

- (void)doDoubleClick:(id)sender

Availability
See Also
Declared In
NSBrowser.h

doubleAction

Returns the receiver’s double-click action method.

- (SEL)doubleAction

Return Value

The action method invoked when the user double-clicks on the browser.

Availability
See Also
Declared In
NSBrowser.h

draggingImageForRowsWithIndexes:inColumn:withEvent:offset:

Provides an image to represent dragged rows during a drag operation on the receiver.

- (NSImage *)draggingImageForRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex withEvent:(NSEvent *)dragEvent offset:(NSPointPointer)dragImageOffset

Parameters
rowIndexes

Rows the user is dragging.

columnIndex

Column with the rows the user is dragging.

dragEvent

Mouse drag event.

inout_dragImageOffset

Offset for the returned image:

Return Value

Image representing the visible cells identified by rowIndexes.

Availability
See Also
Declared In
NSBrowser.h

draggingSourceOperationMaskForLocal:

Indicates the types of dragging operations the source object allows on the dragged image’s data.

- (NSDragOperation)draggingSourceOperationMaskForLocal:(BOOL)localDestination

Parameters
localDestination

Indicates the location of the dragging operation’s destination object: YES for this application, NO for another application.

Return Value

NSDragOperationEvery when localDestination is YES.

NSDragOperationNone when localDestination is NO.

Discussion

This method overrides NSDraggingSource draggingSourceOperationMaskForLocal:.

drawTitleOfColumn:inRect:

Draws the title for the specified column within the given rectangle.

- (void)drawTitleOfColumn:(NSInteger)column inRect:(NSRect)aRect

Parameters
column

The index of the column for which to draw the title.

aRect

The rectangle within which to draw the title.

Availability
See Also
Declared In
NSBrowser.h

firstVisibleColumn

Returns the index of the first visible column.

- (NSInteger)firstVisibleColumn

Return Value

The index of the first visible column.

Availability
See Also
Declared In
NSBrowser.h

frameOfColumn:

Returns the rectangle containing the given column.

- (NSRect)frameOfColumn:(NSInteger)column

Parameters
column

The index of the column for which to retrieve the frame.

Return Value

The rectangle containing the specified column.

Availability
Declared In
NSBrowser.h

frameOfInsideOfColumn:

Returns the rectangle containing the specified column, not including borders.

- (NSRect)frameOfInsideOfColumn:(NSInteger)column

Parameters
column

The index of the column for which to retrieve the inside frame.

Return Value

The rectangle containing the column, not including the column borders.

Availability
Declared In
NSBrowser.h

hasHorizontalScroller

Returns a Boolean value indicating whether the browser has a horizontal scroller.

- (BOOL)hasHorizontalScroller

Return Value

YES if the browser uses an NSScroller object to scroll horizontally; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

isLoaded

Returns whether column 0 is loaded.

- (BOOL)isLoaded

Return Value

YES if column 0 is loaded; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

isOpaque

Indicates whether the receiver is opaque.

- (BOOL)isOpaque

Return Value

YES when the receiver doesn’t have a title and its background color’s alpha component is 1.0, NO otherwise.

Discussion

This method overrides NSView isOpaque.

isTitled

Returns a Boolean value indicating whether columns display titles.

- (BOOL)isTitled

Return Value

YES if the columns in a browser display titles; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

lastColumn

Returns the index of the last column loaded.

- (NSInteger)lastColumn

Return Value

The index of the last loaded column.

Availability
See Also
Declared In
NSBrowser.h

lastVisibleColumn

Returns the index of the last visible column.

- (NSInteger)lastVisibleColumn

Return Value

The index of the last visible column.

Availability
See Also
Declared In
NSBrowser.h

loadColumnZero

Loads column 0; unloads previously loaded columns.

- (void)loadColumnZero

Availability
See Also
Declared In
NSBrowser.h

loadedCellAtRow:column:

Loads, if necessary, and returns the NSCell at the specified row and column location.

- (id)loadedCellAtRow:(NSInteger)row column:(NSInteger)column

Parameters
row

The row index of the cell to return.

column

The column index of the cell to return.

Availability
See Also
Declared In
NSBrowser.h

matrixClass

Returns the matrix class used in the receiver’s columns.

- (Class)matrixClass

Return Value

The class of NSMatrix used in the browser's columns.

Availability
See Also
Declared In
NSBrowser.h

matrixInColumn:

Returns the matrix located in the specified column.

- (NSMatrix *)matrixInColumn:(NSInteger)column

Parameters
column

The column index of the matrix to obtain.

Return Value

The matrix located in the column.

Availability
Declared In
NSBrowser.h

maxVisibleColumns

Returns the maximum number of visible columns.

- (NSInteger)maxVisibleColumns

Return Value

The maximum number of visible columns.

Availability
See Also
Declared In
NSBrowser.h

minColumnWidth

Returns the minimum column width.

- (CGFloat)minColumnWidth

Return Value

The minimum column width, in pixels.

Availability
See Also
Declared In
NSBrowser.h

namesOfPromisedFilesDroppedAtDestination:

Provides the names of the files that the receiver promises to create at a specified location.

- (NSArray *)namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination

Return Value

Result of sending browser:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:inColumn: to the delegate.

Discussion

Implementation of NSDraggingSource namesOfPromisedFilesDroppedAtDestination:.

See Also

numberOfVisibleColumns

Returns the number of columns visible.

- (NSInteger)numberOfVisibleColumns

Return Value

The number of visible columns.

Availability
See Also
Declared In
NSBrowser.h

path

Returns a string representing the receiver’s current path.

- (NSString *)path

Return Value

The path representing the current selection. The components of this path are separated with the string returned by pathSeparator.

Discussion

Invoking this method is equivalent to invoking pathToColumn: for all columns.

Availability
See Also
Declared In
NSBrowser.h

pathSeparator

Returns the path separator.

- (NSString *)pathSeparator

Return Value

The path separator. The default is “/”.

Availability
See Also
Declared In
NSBrowser.h

pathToColumn:

Returns a string representing the path from the first column up to, but not including, the column at the given index.

- (NSString *)pathToColumn:(NSInteger)column

Parameters
column

The index of the column at which the path stops.

Return Value

The path of the current selection up to, but not including, the specified column. The components of this path are separated with the string returned by pathSeparator.

Availability
See Also
Declared In
NSBrowser.h

prefersAllColumnUserResizing

Returns a Boolean value indicating if the browser is set to resize all columns simultaneously rather than resizing a single column at a time.

- (BOOL)prefersAllColumnUserResizing

Return Value

YES if the browser is set to resize all columns simultaneously; otherwise NO. The default is NO.

Discussion

This setting applies only to browsers that allow the user to resize columns (see NSBrowserUserColumnResizing. Holding down the Option key while resizing switches the type of resizing used.

Availability
See Also
Declared In
NSBrowser.h

reloadColumn:

Reloads the given column if it exists and sets it to be the last column.

- (void)reloadColumn:(NSInteger)column

Parameters
column

The index of the column to reload.

Availability
See Also
Declared In
NSBrowser.h

reusesColumns

Returns a Boolean value indicating whether the browser reuses NSMatrix objects after their columns are unloaded.

- (BOOL)reusesColumns

Return Value

YES if NSMatrix objects aren't freed when their columns are unloaded; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

scrollColumnsLeftBy:

Scrolls columns left by the specified number of columns.

- (void)scrollColumnsLeftBy:(NSInteger)shiftAmount

Parameters
shiftAmount

The number of columns by which to scroll the browser.

Availability
See Also
Declared In
NSBrowser.h

scrollColumnsRightBy:

Scrolls columns right by the specified number of columns.

- (void)scrollColumnsRightBy:(NSInteger)shiftAmount

Parameters
shiftAmount

The number of columns by which to scroll the browser.

Availability
See Also
Declared In
NSBrowser.h

scrollColumnToVisible:

Scrolls to make the specified column visible.

- (void)scrollColumnToVisible:(NSInteger)column

Parameters
column

The index of the column to scroll to.

Availability
See Also
Declared In
NSBrowser.h

scrollViaScroller:

Scrolls columns left or right based on an NSScroller.

- (void)scrollViaScroller:(NSScroller *)sender

Parameters
sender

The NSScroller object that determines the scrolling of the browser columns.

Availability
See Also
Declared In
NSBrowser.h

selectAll:

Selects all NSCell objects in the last column of the receiver.

- (void)selectAll:(id)sender

Availability
See Also
Declared In
NSBrowser.h

selectedCell

Returns the last (rightmost and lowest) selected NSCell.

- (id)selectedCell

Return Value

The selected cell.

Availability
See Also
Declared In
NSBrowser.h

selectedCellInColumn:

Returns the last (lowest) NSCell selected in the given column.

- (id)selectedCellInColumn:(NSInteger)column

Parameters
column

The column for which to return the last selected cell.

Return Value

The last (or lowest) selected cell.

Availability
See Also
Declared In
NSBrowser.h

selectedCells

Returns all cells selected in the rightmost column.

- (NSArray *)selectedCells

Return Value

An array of NSCell objects representing the selected cells in the rightmost browser column.

Availability
See Also
Declared In
NSBrowser.h

selectedColumn

Returns the index of the last column with a selected item.

- (NSInteger)selectedColumn

Return Value

The index of the last column with a selected item.

Availability
See Also
Declared In
NSBrowser.h

selectedRowInColumn:

Returns the row index of the selected cell in the specified column.

- (NSInteger)selectedRowInColumn:(NSInteger)column

Parameters
column

The column index specifying the column for which to return the selected row.

Return Value

The row index of the selected cell in the specified column.

Availability
See Also
Related Sample Code
Declared In
NSBrowser.h

selectedRowIndexesInColumn:

Provides the indexes of the selected rows in a given column of the receiver.

- (NSIndexSet *)selectedRowIndexesInColumn:(NSInteger)columnIndex

Parameters
columnIndex

Column whose selected rows are provided.

Return Value

Rows selected in column columnIndex.

Availability
See Also
Declared In
NSBrowser.h

selectRow:inColumn:

Selects the cell at the specified row and column index.

- (void)selectRow:(NSInteger)row inColumn:(NSInteger)column

Parameters
row

The row index of the cell to select.

column

The column index of the cell to select.

Availability
See Also
Declared In
NSBrowser.h

selectRowIndexes:inColumn:

Specifies the selected rows in a given column of the receiver.

- (void)selectRowIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex

Parameters
rowIndexes

Rows to be selected in column columnIndex.

columnIndex

Column in which to select rows rowIndexes.

Availability
See Also
Declared In
NSBrowser.h

sendAction

Sends the action message to the target.

- (BOOL)sendAction

Return Value

YES if successful, NO if no target for the message could be found.

Availability
Declared In
NSBrowser.h

sendsActionOnArrowKeys

Returns a Boolean value indicating whether pressing an arrow key causes an action message to be sent.

- (BOOL)sendsActionOnArrowKeys

Return Value

NO if pressing an arrow key only scrolls the receiver, YES if it also sends the action message specified by setAction:.

Availability
See Also
Declared In
NSBrowser.h

separatesColumns

Returns a Boolean value indicating whether columns are separated by bezeled borders.

- (BOOL)separatesColumns

Return Value

YES if the browser's columns are separated by bezeled borders; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setAcceptsArrowKeys:

Specifies whether the browser allows navigation using the arrow keys.

- (void)setAcceptsArrowKeys:(BOOL)flag

Parameters
flag

YES to enable the use of the arrow keys for navigating within and between browsers; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setAllowsBranchSelection:

Sets whether the user can select branch items.

- (void)setAllowsBranchSelection:(BOOL)flag

Parameters
flag

YES if the user can select branch items when multiple selection is enabled; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setAllowsEmptySelection:

Sets whether there can be nothing selected.

- (void)setAllowsEmptySelection:(BOOL)flag

Parameters
flag

YES if the browser allows an empty selection; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setAllowsMultipleSelection:

Sets whether the user can select multiple items.

- (void)setAllowsMultipleSelection:(BOOL)flag

Parameters
flag

YES if the user can select multiple items at once; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setAllowsTypeSelect:

Specifies whether the receiver allows keystroke-based selection.

- (void)setAllowsTypeSelect:(BOOL)allowsTypeSelection

Parameters
allowsTypeSelection

YES to allow type selection, NO to disallow it.

Availability
See Also
Declared In
NSBrowser.h

setBackgroundColor:

Specifies the receiver’s background color.

- (void)setBackgroundColor:(NSColor *)backgroundColor

Parameters
backgroundColor

[NSColor clearColor] specifies a transparent background.

Availability
See Also
Declared In
NSBrowser.h

setCellClass:

Sets the class of NSCell used by the matrices in the columns of the receiver.

- (void)setCellClass:(Class)factoryId

Parameters
factoryId

The class of NSCell used by the matrices in the columns of the browser. This method creates an instance of the class and calls setCellPrototype:.

Availability
See Also
Declared In
NSBrowser.h

setCellPrototype:

Sets the NSCell instance copied to display items in the matrices in the columns of the receiver.

- (void)setCellPrototype:(NSCell *)aCell

Parameters
aCell

The prototype NSCell instance.

Availability
See Also
Declared In
NSBrowser.h

setColumnResizingType:

Sets the receiver’s column resizing type.

- (void)setColumnResizingType:(NSBrowserColumnResizingType)columnResizingType

Parameters
columnResizingType

A constant specifying the column resizing type. Possible values are described in NSBrowserColumnResizingType. The default is NSBrowserAutoColumnResizing. This setting is persistent.

Availability
See Also
Declared In
NSBrowser.h

setColumnsAutosaveName:

Sets the name used to automatically save the receiver’s column configuration.

- (void)setColumnsAutosaveName:(NSString *)name

Parameters
name

The name used to save the column configuration. If name is different from the current name, this method also reads in any column configuration data previously saved under name and applies the values to the browser.

Discussion

Column configuration is defined as an array of column content widths. One width is saved for each level the user has reached. That is, the browser saves column width based on depth, not on unique paths. To do more complex column persistence, you should register for NSBrowserColumnConfigurationDidChangeNotification and handle persistence yourself. This setting is persistent.

Availability
See Also
Declared In
NSBrowser.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters
anObject

The object to set at the receiver's delegate.

Discussion

Raises NSBrowserIllegalDelegateException if the delegate specified by anObject doesn’t respond to browser:willDisplayCell:atRow:column: and either of the methods browser:numberOfRowsInColumn: or browser:createRowsForColumn:inMatrix:.

Availability
See Also
Declared In
NSBrowser.h

setDoubleAction:

Sets the receiver’s double-click action.

- (void)setDoubleAction:(SEL)aSelector

Parameters
aSelector

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

Discussion

For the method to have any effect, the receiver’s action and target must be set to the class in which the selector is declared. See Action Messages for additional information on action messages.

Availability
See Also
Declared In
NSBrowser.h

setDraggingSourceOperationMask:forLocal:

Specifies the drag-operation mask for dragging operations with local or external destinations.

- (void)setDraggingSourceOperationMask:(NSDragOperation)dragOperationMask forLocal:(BOOL)localDestination

Parameters
dragOperationMask

Dragging operation mask to use for either local or external drag operations, as specified by localDestination.

localDestination

Indicates the location of the dragging operation’s destination object:

YES for this application, NO for another application.

Discussion

Important: Do not override this method.

Availability
See Also
Declared In
NSBrowser.h

setHasHorizontalScroller:

Sets whether an NSScroller is used to scroll horizontally.

- (void)setHasHorizontalScroller:(BOOL)flag

Parameters
flag

YES if the browser uses an NSScroller object to scroll horizontally; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setLastColumn:

Sets the last column.

- (void)setLastColumn:(NSInteger)column

Parameters
column

The index of the last column.

Availability
See Also
Declared In
NSBrowser.h

setMatrixClass:

Sets the matrix class used in the receiver’s columns.

- (void)setMatrixClass:(Class)factoryId

Parameters
factoryId

The matrix class (NSMatrix or an NSMatrix subclass) used in the browser's columns.

Availability
See Also
Declared In
NSBrowser.h

setMaxVisibleColumns:

Sets the maximum number of columns displayed.

- (void)setMaxVisibleColumns:(NSInteger)columnCount

Parameters
columnCount

The maximum number of visible columns.

Availability
See Also
Declared In
NSBrowser.h

setMinColumnWidth:

Sets the minimum column width.t

- (void)setMinColumnWidth:(CGFloat)columnWidth

Parameters
columnWidth

The minimum column width, specified in pixels.

Availability
See Also
Declared In
NSBrowser.h

setPath:

Sets the path displayed by the receiver.

- (BOOL)setPath:(NSString *)path

Parameters
path

The path to display. If path is prefixed by the path separator, the path is absolute, containing the full path from the receiver’s first column. Otherwise, the path is relative, extending the receiver’s current path starting at the last column.

Return Value

YES if the given path is valid; otherwise, NO.

Discussion

While parsing path, the receiver compares each component with the entries in the current column. If an exact match is found, the matching entry is selected, and the next component is compared to the next column’s entries. If no match is found for a component, the method exits and returns NO; the final path is set to the valid portion of path. If each component of path specifies a valid branch or leaf in the receiver’s hierarchy, the method returns YES.

Availability
See Also
Declared In
NSBrowser.h

setPathSeparator:

Sets the path separator.

- (void)setPathSeparator:(NSString *)newString

Parameters
newString

The new path separator.

Availability
See Also
Declared In
NSBrowser.h

setPrefersAllColumnUserResizing:

Specifies whether the browser resizes all columns simultaneously rather than resizing a single column at a time.

- (void)setPrefersAllColumnUserResizing:(BOOL)prefersAllColumnResizing

Parameters
prefersAllColumnResizing

YES to cause the browser to resize all columns simultaneously; the default is single column resizing (NO). This setting applies only to browsers that allow the user to resize columns (see NSBrowserUserColumnResizing. Holding down the Option key while resizing switches the type of resizing used. This setting is persistent.

Availability
See Also
Declared In
NSBrowser.h

setReusesColumns:

Specifies whether NSMatrix objects are reused.

- (void)setReusesColumns:(BOOL)flag

Parameters
flag

YES to prevent NSMatrix objects from being freed when their columns are unloaded, so they can be reused; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setSendsActionOnArrowKeys:

Sets whether pressing an arrow key causes the action message to be sent.

- (void)setSendsActionOnArrowKeys:(BOOL)flag

Parameters
flag

YES if pressing an arrow key should send the action message specified by setAction: in addition to scrolling the browser; NO if it should only scroll the browser.

Availability
See Also
Declared In
NSBrowser.h

setSeparatesColumns:

Sets whether to separate columns with bezeled borders.

- (void)setSeparatesColumns:(BOOL)flag

Parameters
flag

YES if the browser's collumns should be separated by bezeled borders; otherwise NO. This value is ignored if isTitled does not return NO

Availability
See Also
Declared In
NSBrowser.h

setTakesTitleFromPreviousColumn:

Sets whether the title of a column is set to the string value of the selected cell in the previous column.

- (void)setTakesTitleFromPreviousColumn:(BOOL)flag

Parameters
flag

YES if the title of a column should be set to the string value of the selected NSCell in the previous column; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setTitle:ofColumn:

Sets the title of the given column.

- (void)setTitle:(NSString *)aString ofColumn:(NSInteger)column

Parameters
aString

The title of the column.

column

The index of the column whose title should be set.

Availability
See Also
Declared In
NSBrowser.h

setTitled:

Sets whether columns display titles.

- (void)setTitled:(BOOL)flag

Parameters
flag

YES if the columns in a browser display titles; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

setWidth:ofColumn:

Sets the width of the specified column.

- (void)setWidth:(CGFloat)columnWidth ofColumn:(NSInteger)columnIndex

Parameters
columnWidth

The new width of the specified column.

columnIndex

The index of the column for which to set the width.

Discussion

This method can be used to set the initial width of browser columns unless the column sizing is automatic; setWidth:ofColumn: does nothing if columnResizingType is NSBrowserAutoColumnResizing. To set the default width for new columns (that don’t otherwise have initial widths from defaults or via the delegate), use a columnIndex of –1. A value set for columnIndex of –1 is persistent. An NSBrowserColumnConfigurationDidChangeNotification notification is posted (not immediately), if necessary, so that the receiver can autosave the new column configuration.

Availability
See Also
Declared In
NSBrowser.h

takesTitleFromPreviousColumn

Returns a Boolean value indicating whether a column takes its title from the selected cell in the previous column.

- (BOOL)takesTitleFromPreviousColumn

Return Value

YES if the title of a column is set to the string value of the selected NSCell in the previous column; otherwise NO.

Availability
See Also
Declared In
NSBrowser.h

tile

Adjusts the various subviews of the receiver—scrollers, columns, titles, and so on—without redrawing.

- (void)tile

Discussion

Your code shouldn’t send this message. It’s invoked any time the appearance of the receiver changes.

Availability
Declared In
NSBrowser.h

titleFrameOfColumn:

Returns the bounds of the title frame for the specified column.

- (NSRect)titleFrameOfColumn:(NSInteger)column

Parameters
column

The index of the column for which to return the title frame.

Return Value

The rectangle specifying the bounds of the column's title frame.

Availability
See Also
Declared In
NSBrowser.h

titleHeight

Returns the height of column titles.

- (CGFloat)titleHeight

Return Value

The height of the column titles for the browser.

Availability
See Also
Declared In
NSBrowser.h

titleOfColumn:

Returns the title displayed for the given column.

- (NSString *)titleOfColumn:(NSInteger)column

Parameters
column

The index of the column for which to get the title.

Return Value

The title of the specified column.

Availability
See Also
Declared In
NSBrowser.h

updateScroller

Updates the horizontal scroller to reflect column positions.

- (void)updateScroller

Availability
See Also
Declared In
NSBrowser.h

validateVisibleColumns

Invokes the delegate method browser:isColumnValid: for visible columns.

- (void)validateVisibleColumns

Availability
See Also
Declared In
NSBrowser.h

widthOfColumn:

Returns the width of the specified column.

- (CGFloat)widthOfColumn:(NSInteger)column

Parameters
column

The index of the column for which to retrieve the width.

Return Value

The width of the column.

Availability
See Also
Declared In
NSBrowser.h

Delegate Methods

browser:acceptDrop:atRow:column:dropOperation:

Sent to the delegate during a dragging session to determine whether to accept the drop. Required for a browser to be a drag destination.

- (BOOL)browser:(NSBrowser *)sender acceptDrop:(id <NSDraggingInfo>)dragInfo atRow:(NSInteger)dropReferenceRowIndex column:(NSInteger)dropColumnIndex dropOperation:(NSBrowserDropOperation)dropRowRelativeLocation

Parameters
sender

Browser querying its delegate.

dragInfo

Drag session information.

dropReferenceRowIndex

The drop row.

dropColumnIndex

The drop column.

dropRowRelativeLocation

Drop location relative to dropRowIndex.

Return Value

YES to accept the drop, NO to decline it.

Discussion

Sent after browser:validateDrop:proposedRow:column:dropOperation: allows the drop.

The delegate should incorporate the pasteboard data from the dragging session (dragInfo.draggingPasteboard)

Availability
Declared In
NSBrowser.h

browser:canDragRowsWithIndexes:inColumn:withEvent:

Sent to the delegate to determine whether the browser can attempt to initiate a drag of the given rows for the given event.

- (BOOL)browser:(NSBrowser *)sender canDragRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex withEvent:(NSEvent *)dragEvent

Parameters
sender

Browser querying its delegate.

rowIndexes

Rows the user is dragging

columnIndex

Column containing the rows the user is dragging.

dragEvent

Mouse-drag event.

Return Value

YES to allow the drag operation, NO to disallow it.

Availability
See Also
Declared In
NSBrowser.h

browser:createRowsForColumn:inMatrix:

Creates a row in the given matrix for each row of data to be displayed in the specified column of the browser.

- (void)browser:(NSBrowser *)sender createRowsForColumn:(NSInteger)column inMatrix:(NSMatrix *)matrix

Parameters
sender

The browser.

column

The index of the column for which to create the rows.

matrix

The NSMatrix object in which to create the rows.

Discussion

Either this method or browser:numberOfRowsInColumn: must be implemented, but not both (or an NSBrowserIllegalDelegateException will be raised).

Availability
See Also
Declared In
NSBrowser.h

browser:draggingImageForRowsWithIndexes:inColumn:withEvent:offset:

Sent to the delegate to obtain an image to represent dragged rows during a drag operation on a browser.

- (NSImage *)browser:(NSBrowser *)sender draggingImageForRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex withEvent:(NSEvent *)dragEvent offset:(NSPointPointer)inout_dragImageOffset

Parameters
sender

Browser querying its delegate.

rowIndexes

Rows the user is dragging.

columnIndex

Column with the rows the user is dragging.

dragEvent

Mouse drag event.

inout_dragImageOffset

Offset for the returned image:

Return Value

Image representing the visible rows identified by rowIndexes.

Availability
See Also
Declared In
NSBrowser.h

browser:isColumnValid:

Returns whether the contents of the specified column are valid.

- (BOOL)browser:(NSBrowser *)sender isColumnValid:(NSInteger)column

Parameters
sender

The browser for which to validate the contents.

column

The index of the column to validate.

Return Value

YES if the column's contents are valid; otherwise NO. If NO is returned, sender reloads the column.

Discussion

This method is invoked in response to validateVisibleColumns being sent to sender.

Availability
Declared In
NSBrowser.h

browser:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:inColumn:

Implements file-promise drag operations.

- (NSArray *)browser:(NSBrowser *)sender namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropURL forDraggedRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex

Parameters
sender

Browser querying its delegate.

dropURL

Drop filesystem location.

rowIndexes

Rows the user is dropping.

columnIndex

Column with the rows the user is dropping.

Return Value

Filenames (not pathnames) for the actual files represented by the rows the user is dropping.

Discussion

Note: File-promise drag operation support requires adding NSFilesPromisePboardType to the pasteboard in browser:writeRowsWithIndexes:inColumn:toPasteboard:-browser:writeRowWithIndexes:inColumn:toPasteboard:

Availability
See Also
Declared In
NSBrowser.h

browser:nextTypeSelectMatchFromRow:toRow:inColumn:forString:

Sent to the delegate to customize a browser’s keyboard-based selection (type select) behavior.

- (NSInteger)browser:(NSBrowser *)sender nextTypeSelectMatchFromRow:(NSInteger)startRowIndex toRow:(NSInteger)endRowIndex inColumn:(NSInteger)columnIndex forString:(NSString *)searchString

Parameters
sender

Browser querying its delegate.

startRowIndex

Beginning of row-set to search.

endRowIndex

End of row-set to to search. Can be less than startRowIndex when the search wraps to the beginning.

columnIndex

Column with the rows being searched.

searchString

Keyboard-based selection string. It’s nil when no keyboard-based selection has begun.

Return Value

Index—between startRowIndex and endRowIndex - 1, inclusive—of the first row that matches searchString.

-1 indicates that there’s no match.

Availability
See Also
Declared In
NSBrowser.h

browser:numberOfRowsInColumn:

Returns the number of rows of data in the specified column.

- (NSInteger)browser:(NSBrowser *)sender numberOfRowsInColumn:(NSInteger)column

Parameters
sender

The browser.

column

The index of the column for which to return the number of rows.

Return Value

The number of rows of data in the specified column.

Discussion

Either this method or browser:createRowsForColumn:inMatrix: must be implemented, but not both.

Availability
See Also
Declared In
NSBrowser.h

browser:selectCellWithString:inColumn:

Asks the delegate to select the NSCell with the given title in the specified column.a

- (BOOL)browser:(NSBrowser *)sender selectCellWithString:(NSString *)title inColumn:(NSInteger)column

Parameters
sender

The browser.

title

The title of the cell to select.

column

The index of the column containing the cell to select.

Return Value

YES if the NSCell was successfully select; otherwise, NO.

Discussion

It is the delegate’s responsibility to select the cell, rather than the browser. Invoked in response to setPath: being received by sender.

Availability
See Also
Declared In
NSBrowser.h

browser:selectRow:inColumn:

Asks the delegate to select the NSCell at the specified row and column location.

- (BOOL)browser:(NSBrowser *)sender selectRow:(NSInteger)row inColumn:(NSInteger)column

Parameters
sender

The browser.

row

The index of the row containing the cell to select.

column

The index of the column containing the cell to select.

Return Value

NO if the NSCell was not selected; otherwise YES.

Discussion

It is the delegate’s responsibility to select the cell, rather than the browser. Invoked in response to selectRow:inColumn: being received by sender.

Availability
See Also
Declared In
NSBrowser.h

browser:shouldShowCellExpansionForRow:column:

Determines whether an expansion tooltip appears for a cell at the given row in the given column.

- (BOOL)browser:(NSBrowser *)sender shouldShowCellExpansionForRow:(NSInteger)rowIndex column:(NSInteger)columnIndex

Parameters
sender

Browser querying its delegate.

rowIndex

Row requesting an expansion tooltip.

columnIndex

Column with the requesting row.

Return Value

YES to allow the cell expansion tooltip, NO to disallow it.

Availability
Declared In
NSBrowser.h

browser:shouldSizeColumn:forUserResize:toWidth:

Used for determining a column’s initial size.

- (CGFloat)browser:(NSBrowser *)browser shouldSizeColumn:(NSInteger)columnIndex forUserResize:(BOOL)forUserResize toWidth:(CGFloat)suggestedWidth

Parameters
browser

The browser.

columnIndex

The index of the column to size.

forUserResize

As currently implemented, this method is always called with forUserResize set to NO.

suggestedWidth

The suggested width for the column.

Return Value

The delegate's desired initial width for a newly added column. If you want to accept the suggested width, return suggestedWidth. If you return 0 or a size too small to display the resize handle and a portion of the column, the actual size used will be larger than you requested.

Discussion

Implementation is optional and applies only to browsers with resize type NSBrowserNoColumnResizing or NSBrowserUserColumnResizing (see NSBrowserColumnResizingType). I

Availability
See Also
Declared In
NSBrowser.h

browser:shouldTypeSelectForEvent:withCurrentSearchString:

Sent to the delegate to determine whether keyboard-based selection (type select) for a given event and search string should proceed.

- (BOOL)browser:(NSBrowser *)sender shouldTypeSelectForEvent:(NSEvent *)keyEvent withCurrentSearchString:(NSString *)searchString

Parameters
sender

Browser querying its delegate.

keyEvent

Keyboard event being processed.

searchString

Keyboard-based selection string. It’s nil when no keyboard-based selection has begun.

Return Value

YES to allow the selection, NO to disallow it.

Availability
See Also
Declared In
NSBrowser.h

browser:sizeToFitWidthOfColumn:

Returns the ideal width for a column.

- (CGFloat)browser:(NSBrowser *)browser sizeToFitWidthOfColumn:(NSInteger)columnIndex

Parameters
browser

The browser.

columnIndex

The index of the column to size. If columnIndex is –1, the result is used for a “right-size-all” operation.

Return Value

The ideal width of the column. This method is used when performing a “right-size” operation; that is, when sizing a column to the smallest width that contains all the content without clipping or truncating.

If columnIndex is –1, you should return a size that can be uniformly applied to all columns (that is, every column will be set to this size). It is assumed that the implementation may be expensive, so it will be called only when necessary.

Discussion

Implementation is optional and is for browsers with resize type NSBrowserUserColumnResizing only.

Availability
Declared In
NSBrowser.h

browser:titleOfColumn:

Asks the delegate for the title to display above the specified column.

- (NSString *)browser:(NSBrowser *)sender titleOfColumn:(NSInteger)column

Parameters
sender

The browser.

column

The index of the column for which to return the title.

Return Value

The title of the specified column.

Availability
See Also
Declared In
NSBrowser.h

browser:typeSelectStringForRow:inColumn:

Sent to the delegate to get the keyboard-based selection (type select) string for a given row and column.

- (NSString *)browser:(NSBrowser *)sender typeSelectStringForRow:(NSInteger)rowIndex inColumn:(NSInteger)columnIndex

Parameters
sender

Browser querying its delegate.

rowIndex

Row being inquired about.

columnIndex

Column with the row being inquired about.

Return Value

Keyboard-based selection string for the identified row and column.

Returning the empty string or nil (for example, when the cell does not contain text) specifies that the [columnIndex, rowIndex] cell has no text to search.

Discussion

If the delegate does not implement this method, all cells with text are searched, and the browser determines the keyboard-based selection text by sending stringValue to the cell specified by columnIndex and rowIndex.

Availability
See Also
Declared In
NSBrowser.h

browser:validateDrop:proposedRow:column:dropOperation:

Sent to the delegate during a dragging session to determine whether to accept a drop, and to obtain the drop location. Required for a browser to be a drag destination.

- (NSDragOperation)browser:(NSBrowser *)sender validateDrop:(id <NSDraggingInfo>)dragInfo proposedRow:(NSInteger *)inout_dropReferenceRowIndex column:(NSInteger *)inout_dropColumnIndex dropOperation:(NSBrowserDropOperation *) inout_dropRowRelativeLocation

Parameters
sender

Browser querying its delegate.

dragInfo

Drag session information.

inout_dropReferenceRowIndex

Together with inout_dropRowRelativeLocation specifies the drop location.

On input, the proposed drop reference row.

On output, the drop reference row.

inout_dropColumnIndex

Column on which the dragged rows are being dropped.

On input, the proposed drop column.

On output, the drop column.

inout_dropRowRelativeLocation

Drop location, within the rows identified in rowIndexes, of the drag operation.

On input, the proposed drop location.

On output, the drop location.

Return Value

Drag operation the data source is to perform. Must not be NSDragOperationNone for sender to accept the drop.

Discussion

The browser proposes a drop column, row, and row-relative location for the drop based on the pointer position, as shown in this table:

Drop relative location

Description

NSBrowserDropOn

Dragging location (dragInfo.draggingLocation) is closer to the middle of inout_dropReferenceRowIndex than to either of its vertical sides.

NSBroserDropAbove

Dragging location is between two rows. Indicates a drop location above inout_dropReferenceRowIndex and below inout_dropReferenceRowIndex - 1.

These are a few examples of how to specify a drop location:

Reference row index

Row-relative location

On row 2

2

NSBrowserDropOn

Between rows 2 and 3

3

NSBrowserDropAbove

Below the last row

[sender numberOfRows]

NSBrowserDropAbove

All rows

-1

NSBrowserDropOn

Availability
See Also
Declared In
NSBrowser.h

browser:willDisplayCell:atRow:column:

Gives the delegate the opportunity to modify the specified cell at the given row and column position before it’s displayed by the NSBrowser.

- (void)browser:(NSBrowser *)sender willDisplayCell:(id)cell atRow:(NSInteger)row column:(NSInteger)column

Parameters
sender

The browser.

cell

The cell to be displayed.

row

The row index of the cell to be displayed.

column

The column index of the cell to be displayed.

Discussion

The delegate should set any state necessary for the correct display of the cell.

Availability
See Also
Declared In
NSBrowser.h

browser:writeRowsWithIndexes:inColumn:toPasteboard:

Determines whether a drag operation can proceed. Required for a browser to be a drag source.

- (BOOL)browser:(NSBrowser *)sender writeRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)columnIndex toPasteboard:(NSPasteboard *)pasteboard

Parameters
sender

Browser querying its delegate.

rowIndexes

Rows the user is dragging.

columnIndex

Column with the dragged rows.

pasteboard

Content from the dragged rows.

Return Value

YES to allow the dragging operation to proceed (see discussion for further details), NO to disallow it.

Discussion

Called after a drag operation has been allowed to start (browser:canDragRowsWithIndexes:inColumn:withEvent: returns YES) but before it actually begins.

Availability
Declared In
NSBrowser.h

browserColumnConfigurationDidChange:

Used by clients to implement their own column width persistence.

- (void)browserColumnConfigurationDidChange:(NSNotification *)notification

Parameters
notification

The notification of the configuration change.

Discussion

Implementation is optional, and used for browsers with resize type NSBrowserUserColumnResizing only. It is called when the method setWidth:ofColumn: is used to change the width of any browser columns or when the user resizes any columns. If the user resizes more than one column, a single notification is posted when the user is finished resizing.

Availability
See Also
Declared In
NSBrowser.h

browserDidScroll:

Notifies the delegate when the NSBrowser has scrolled.

- (void)browserDidScroll:(NSBrowser *)sender

Parameters
sender

The browser sending the message.

Availability
Declared In
NSBrowser.h

browserWillScroll:

Notifies the delegate when the NSBrowser will scroll.

- (void)browserWillScroll:(NSBrowser *)sender

Parameters
sender

The browser sending the message.

Availability
Declared In
NSBrowser.h

Constants

NSBrowserColumnResizingType

Describe types of browser column resizing.

typedef enum _NSBrowserColumnResizingType {
   NSBrowserNoColumnResizing   = 0,
   NSBrowserAutoColumnResizing = 1,
   NSBrowserUserColumnResizing = 2
} NSBrowserColumnResizingType;

Constants
NSBrowserNoColumnResizing

Neither NSBrowser nor the user can change the column width. The developer must explicitly set all column widths.

Available in Mac OS X v10.3 and later.

Declared in NSBrowser.h.

NSBrowserAutoColumnResizing

All columns have the same width, calculated using a combination of the minimum column width and maximum number of visible columns settings. The column width changes as the window size changes. The user cannot resize columns.

Available in Mac OS X v10.3 and later.

Declared in NSBrowser.h.

NSBrowserUserColumnResizing

The developer chooses the initial column widths, but users can resize all columns simultaneously or each column individually.

Available in Mac OS X v10.3 and later.

Declared in NSBrowser.h.

Discussion

These constants are used by the setColumnResizingType: and columnResizingType methods.

Availability
Declared In
NSBrowser.h

NSBrowserDropOperation

This type is used to to specifying the drop type of a drag-and-drop operation. See browser:validateDrop:proposedRow:column:dropOperation for more information.

   
enum {
   NSBrowserDropOn,
   NSBrowserDropAbove
};
typedef NSUInteger NSBrowserDropOperation;

Availability
Declared In
NSBrowser.h

Notifications

NSBrowserColumnConfigurationDidChangeNotification

Notifies the delegate when the width of a browser column has changed. The notification object is the browser whose column sizes need to be made persistent. This notification does not contain a userInfo dictionary. If the user resizes more than one column, a single notification is posted when the user is finished resizing.

Availability
See Also
Declared In
NSBrowser.h

Next Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-04-05)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.