NSBrowserDelegate Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Browser Programming Topics
Declared in
NSBrowser.h
Related sample code

Overview

The NSBrowserDelegate protocol defines the method that a delegate of NSBrowser should implement.

Tasks

Getting Browser Information

Managing Selection Behavior

Managing Selection

Accessing Components

Managing Columns

Scrolling

Dragging

Sizing

Displaying Cell Content

Instance Methods

browser:acceptDrop:atRow:column:dropOperation:

Sent to the delegate during a dragging session to determine whether to accept the drop.

- (BOOL)browser:(NSBrowser *)browser acceptDrop:(id <NSDraggingInfo>)info atRow:(NSInteger)row column:(NSInteger)column dropOperation:(NSBrowserDropOperation)dropOperation
Parameters
browser

The browser.

info

The drag session information.

row

The drop row.

column

The drop column.

dropOperation

The drop location relative to row.

Return Value

YES to accept the drop; NO to decline it.

Discussion

This method is required for a browser to be a drag destination. It is invoked after the browser:validateDrop:proposedRow:column:dropOperation: method allows the drop.

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

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 specified rows for the specified event.

- (BOOL)browser:(NSBrowser *)browser canDragRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)column withEvent:(NSEvent *)event
Parameters
browser

The browser.

rowIndexes

The rows the user is dragging.

column

The column containing the rows the user is dragging.

event

The drag event.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:child:ofItem:

Asks the delegate to return the child of the specified item at the specified index.

- (id)browser:(NSBrowser *)browser child:(NSInteger)index ofItem:(id)item
Parameters
browser

The browser.

index

The child’s index.

item

The item containing the child.

Return Value

The child at the specified index.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSBrowser.h

browser:createRowsForColumn:inMatrix:

Creates a row in the given matrix for each row of data 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 in which the rows are located.

matrix

The matrix in which the rows are created.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:didChangeLastColumn:toColumn:

Tells the delegate that the browser’s last column changed.

- (void)browser:(NSBrowser *)browser didChangeLastColumn:(NSInteger)oldLastColumn toColumn:(NSInteger)column
Parameters
browser

The browser.

oldLastColumn

The index of the old last column.

column

The index of the new last column.

Availability
  • Available in OS X v10.6 and later.
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 *)browser draggingImageForRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)column withEvent:(NSEvent *)event offset:(NSPointPointer)dragImageOffset
Parameters
browser

The browser.

rowIndexes

The indexes of the rows the user is dragging.

column

The column containing the rows the user is dragging.

event

The drag event.

dragImageOffset

The offset for the returned image:

  • NSZeroPoint: Centers the image under the pointer.

Return Value

An image representing the visible rows identified by rowIndexes.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:headerViewControllerForItem:

Asks the delegate for a controller that provides a header view for the specified column item.

- (NSViewController *)browser:(NSBrowser *)browser headerViewControllerForItem:(id)item
Parameters
browser

The browser.

item

The column item.

Return Value

A view controller that provides a header view, or nil to omit the header view.

Discussion

The returned controller’s represented object will be set to the column item. This method is called only if the delegate implements the item data source methods.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSBrowser.h

browser:heightOfRow:inColumn:

Specifies the height of the specified row in the specified column.

- (CGFloat)browser:(NSBrowser *)browser heightOfRow:(NSInteger)row inColumn:(NSInteger)columnIndex
Parameters
browser

The browser.

row

The index of the row.

columnIndex

The index of the column.

Return Value

The height to set for the specified row, which must be greater than 0.

Discussion

The values returned for this method may be cached. Therefore, you should call noteHeightOfRowsWithIndexesChanged:inColumn: to invalidate a row’s height before changing it.

Availability
  • Available in OS X v10.6 and later.
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 containing the column to validate.

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 the validateVisibleColumnsmethod of NSBrowser being sent to sender.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSBrowser.h

browser:isLeafItem:

Asks the delegate whether the specified item is a leaf item (an item that cannot be expanded).

- (BOOL)browser:(NSBrowser *)browser isLeafItem:(id)item
Parameters
browser

The browser.

item

The item to be checked.

Return Value

YES if the specified item is a leaf item; otherwise, NO.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSBrowser.h

browser:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:inColumn:

Implements file promise drag operations.

- (NSArray *)browser:(NSBrowser *)browser namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination forDraggedRowsWithIndexes:(NSIndexSet *)rowIndexes inColumn:(NSInteger)column
Parameters
browser

The browser.

dropDestination

The drop filesystem location.

rowIndexes

The indexes of the rows the user is dropping.

column

The index of the column containing 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 that file promise drag operation support requires adding the data type NSFilesPromisePboardType to the pasteboard in the browser:writeRowsWithIndexes:inColumn:toPasteboard: method.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Related Sample Code
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 *)browser nextTypeSelectMatchFromRow:(NSInteger)startRow toRow:(NSInteger)endRow inColumn:(NSInteger)column forString:(NSString *)searchString
Parameters
browser

The browser.

startRow

The beginning of the row set to search.

endRow

The end of the row set to search. This value can be less than startRowIndex when the search wraps around to the beginning.

column

The column containing the rows being searched.

searchString

The keyboard-based selection string. It is nil when no keyboard-based selection has begun.

Return Value

The index of the first row that matches searchString between startRowIndex and endRowIndex - 1, or -1 if there is no match.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:numberOfChildrenOfItem:

Asks the delegate for the number of children the given item has.

- (NSInteger)browser:(NSBrowser *)browser numberOfChildrenOfItem:(id)item
Parameters
browser

The browser.

item

The item that has some number of children.

Return Value

The number of children.

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

Return Value

The number of rows of data.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:objectValueForItem:

Returns the object that the specified item uses to draw its contents.

- (id)browser:(NSBrowser *)browser objectValueForItem:(id)item
Parameters
browser

The browser.

item

The item in question.

Return Value

The item’s object.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSBrowser.h

browser:previewViewControllerForLeafItem:

Asks the delegate for a controller that provides a preview column for the specified leaf item.

- (NSViewController *)browser:(NSBrowser *)browser previewViewControllerForLeafItem:(id)item
Parameters
browser

The browser.

item

The leaf item.

Return Value

A view controller that provides a preview column, or nil to suppress the preview column.

Discussion

The returned controller’s represented object is set to the specified leaf item. This method is called only if the delegate implements the item data source methods.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSBrowser.h

browser:selectCellWithString:inColumn:

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

- (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 cell was successfully selected; otherwise, NO.

Discussion

Invoked in response to the setPath: method of NSBrowser being received by sender.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:selectionIndexesForProposedSelection:inColumn:

Asks the delegate for a set of indexes to select when the user changes the selection in the browser with the keyboard or mouse.

- (NSIndexSet *)browser:(NSBrowser *)browser selectionIndexesForProposedSelection:(NSIndexSet *)proposedSelectionIndexes inColumn:(NSInteger)column
Parameters
browser

The browser.

proposedSelectionIndexes

The set of indexes of the items in the proposed selection.

column

The column index of the column containing the selection.

Return Value

The set of indexes of the items that should be selected.

Discussion

This method may be called multiple times, with one new index added to the previous selection, to see whether a particular index can be selected when the user is extending the selection with the keyboard or mouse. The proposedSelectionIndexes parameter contains the entire selection, and you can return the existing selection if you do not want to change it. This method works only for item-based browsers.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSBrowser.h

browser:selectRow:inColumn:

Asks the delegate to select the cell 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

YES if the cell was selected; otherwise, NO.

Discussion

Invoked in response to selectRow:inColumn: of NSBrowser being received by sender.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:setObjectValue:forItem:

Sets the object that the specified item uses to draw its contents to the specified object.

- (void)browser:(NSBrowser *)browser setObjectValue:(id)object forItem:(id)item
Parameters
browser

The browser.

object

The object to set.

item

The item whose object is set.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSBrowser.h

browser:shouldEditItem:

Asks the delegate whether the browser may start an editing session for the specified item.

- (BOOL)browser:(NSBrowser *)browser shouldEditItem:(id)item
Parameters
browser

The browser.

item

The item to edit.

Return Value

YES to allow the editing session to begin; NO to disallow it.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSBrowser.h

browser:shouldShowCellExpansionForRow:column:

Invoked to allow the delegate to control cell expansion for a specific row and column.

- (BOOL)browser:(NSBrowser *)browser shouldShowCellExpansionForRow:(NSInteger)row column:(NSInteger)column
Parameters
browser

The browser.

row

The index of the row requesting an expansion tooltip.

column

The index of the column containing the requesting row.

Return Value

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

Discussion

Cell expansion can occur when the mouse hovers over the specified cell and the cell contents are unable to be fully displayed within the cell. If this method returns YES, the full cell contents will be shown in a special floating tool tip view, otherwise the content is truncated.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSBrowser.h

browser:shouldSizeColumn:forUserResize:toWidth:

Used to determine 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

Currently, this is always 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 the size you requested.

Discussion

This method applies only to browsers with resize type NSBrowserNoColumnResizing or NSBrowserUserColumnResizing (see NSBrowserColumnResizingType).

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 *)browser shouldTypeSelectForEvent:(NSEvent *)event withCurrentSearchString:(NSString *)searchString
Parameters
browser

The browser.

event

The keyboard event being processed.

searchString

The keyboard-based selection string. It is nil when no keyboard-based selection has begun.

Return Value

YES to allow the selection; NO to disallow it.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 -1, the result is used to resize all columns.

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

Returning a value of -1 allows you to opt-out of providing a width for the requested column.

Discussion

This method applies only to browsers with resize type NSBrowserUserColumnResizing.

It is assumed that the implementation may be expensive, so it will be called only when necessary.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 the column to be titled.

Return Value

The title of the specified column.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:typeSelectStringForRow:inColumn:

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

- (NSString *)browser:(NSBrowser *)browser typeSelectStringForRow:(NSInteger)row inColumn:(NSInteger)column
Parameters
browser

The browser.

row

The row index.

column

The column index.

Return Value

The keyboard-based selection string.

Discussion

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

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 column and row.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:validateDrop:proposedRow:column:dropOperation:

Sent to the delegate during a dragging session to determine whether a drop should be accepted and to obtain the drop location. This method is required for a browser to be a drag destination.

- (NSDragOperation)browser:(NSBrowser *)browser validateDrop:(id <NSDraggingInfo>)info proposedRow:(NSInteger *)row column:(NSInteger *)column dropOperation:(NSBrowserDropOperation *)dropOperation
Parameters
browser

The browser.

info

The drag session information.

row

On input, the proposed drop row. On output, the drop row.

column

On input, the proposed drop column. On output, the drop column.

dropOperation

On input, the proposed drop location. On output, the drop location.

Return Value

The drag operation that the data source is to perform. For the browser to accept the drop, it must not be NSDragOperationNone.

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 row than to either of its vertical sides.

NSBrowserDropAbove

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

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

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
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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 location before the browser displays it.

- (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
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browser:writeRowsWithIndexes:inColumn:toPasteboard:

Determines whether a drag operation can proceed. This method is required for a browser to be a drag source.

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

The browser.

rowIndexes

The indexes of the rows the user is dragging.

column

The index of the column containing the dragged rows.

pasteboard

The pasteboard containing the 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

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

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSBrowser.h

browserColumnConfigurationDidChange:

Used by clients to implement their own column width persistence.

- (void)browserColumnConfigurationDidChange:(NSNotification *)notification
Parameters
notification

A notification named NSBrowserColumnConfigurationDidChangeNotification.

Discussion

This method applies only to browsers with resize type NSBrowserUserColumnResizing. It is invoked when the setWidth:ofColumn: method of NSBrowser 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
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSBrowser.h

browserDidScroll:

Notifies the delegate when the browser has scrolled.

- (void)browserDidScroll:(NSBrowser *)sender
Parameters
sender

The browser sending the message.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSBrowser.h

browserWillScroll:

Notifies the delegate when the browser will scroll.

- (void)browserWillScroll:(NSBrowser *)sender
Parameters
sender

The browser sending the message.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSBrowser.h

rootItemForBrowser:

Asks the delegate to return the root item of the browser.

- (id)rootItemForBrowser:(NSBrowser *)browser
Parameters
browser

The browser.

Return Value

The browser’s root item.

Discussion

By default, nil identifies the root item. This method can specify a different root item. To reload the previously set root item, call loadColumnZero, and rootItemForBrowser: will be called again.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSBrowser.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-01-25)

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