Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

NSBrowser Class Reference

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:

• Columns

• Scroll views

• Matrices

• Browser cells

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

• – reusesColumns
• – setReusesColumns:
• – maxVisibleColumns
• – setMaxVisibleColumns:
• – backgroundColor
• – setBackgroundColor:
• – minColumnWidth
• – setMinColumnWidth:
• – separatesColumns
• – setSeparatesColumns:
• – takesTitleFromPreviousColumn
• – setTakesTitleFromPreviousColumn:
• – tile
• – acceptsArrowKeys
• – setAcceptsArrowKeys:
• – delegate
• – setDelegate:

Getting Browser Information

• – isOpaque
• – browser:isColumnValid:  delegate method
• – browser:numberOfRowsInColumn:  delegate method
• – browser:titleOfColumn:  delegate method

Managing Component Types

• + cellClass
• – setCellClass:
• – cellPrototype
• – setCellPrototype:
• – matrixClass
• – setMatrixClass:

Managing Selection Behavior

• – allowsBranchSelection
• – setAllowsBranchSelection:
• – allowsEmptySelection
• – setAllowsEmptySelection:
• – allowsMultipleSelection
• – setAllowsMultipleSelection:
• – selectedRowIndexesInColumn:
• – selectRowIndexes:inColumn:
• – allowsTypeSelect
• – setAllowsTypeSelect:
• – browser:shouldTypeSelectForEvent:withCurrentSearchString:  delegate method
• – browser:typeSelectStringForRow:inColumn:  delegate method
• – browser:nextTypeSelectMatchFromRow:toRow:inColumn:forString:  delegate method

Managing Selection

• – selectedCell
• – selectedCellInColumn:
• – selectedCells
• – selectAll:
• – selectedRowInColumn:
• – selectRow:inColumn:
• – browser:selectCellWithString:inColumn:  delegate method
• – browser:selectRow:inColumn:  delegate method

Accessing Components

• – loadedCellAtRow:column:
• – matrixInColumn:

Managing the Path

• – path
• – setPath:
• – pathToColumn:
• – pathSeparator
• – setPathSeparator:

Managing Columns

• – addColumn
• – displayAllColumns
• – displayColumn:
• – columnOfMatrix:
• – selectedColumn
• – lastColumn
• – setLastColumn:
• – firstVisibleColumn
• – numberOfVisibleColumns
• – lastVisibleColumn
• – validateVisibleColumns
• – isLoaded
• – loadColumnZero
• – reloadColumn:
• – browser:createRowsForColumn:inMatrix:  delegate method
• – browser:willDisplayCell:atRow:column:  delegate method

Accessing Column Titles

• – titleOfColumn:
• – setTitle:ofColumn:
• – isTitled
• – setTitled:
• – drawTitleOfColumn:inRect:
• – titleHeight
• – titleFrameOfColumn:

Scrolling

• – updateScroller
• – hasHorizontalScroller
• – setHasHorizontalScroller:
• – scrollColumnToVisible:
• – scrollColumnsLeftBy:
• – scrollColumnsRightBy:
• – scrollViaScroller:
• – browserWillScroll:  delegate method
• – browserDidScroll:  delegate method

Dragging

• – draggingSourceOperationMaskForLocal:
• – setDraggingSourceOperationMask:forLocal:
• – canDragRowsWithIndexes:inColumn:withEvent:
• – browser:canDragRowsWithIndexes:inColumn:withEvent:  delegate method
• – draggingImageForRowsWithIndexes:inColumn:withEvent:offset:
• – browser:draggingImageForRowsWithIndexes:inColumn:withEvent:offset:  delegate method
• – browser:validateDrop:proposedRow:column:dropOperation:  delegate method
• – browser:acceptDrop:atRow:column:dropOperation:  delegate method
• – namesOfPromisedFilesDroppedAtDestination:
• – browser:writeRowsWithIndexes:inColumn:toPasteboard:  delegate method
• – browser:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:inColumn:  delegate method

Getting Column Frames

• – frameOfColumn:
• – frameOfInsideOfColumn:

Managing Actions

• – doubleAction
• – setDoubleAction:
• – sendsActionOnArrowKeys
• – setSendsActionOnArrowKeys:
• – sendAction

Handling Mouse-Click Events

• – doClick:
• – doDoubleClick:

Sizing

• + removeSavedColumnsWithAutosaveName:
• – columnsAutosaveName
• – setColumnsAutosaveName:
• – columnContentWidthForColumnWidth:
• – columnWidthForColumnContentWidth:
• – columnResizingType
• – setColumnResizingType:
• – prefersAllColumnUserResizing
• – setPrefersAllColumnUserResizing:
• – widthOfColumn:
• – setWidth:ofColumn:
• – browser:shouldSizeColumn:forUserResize:toWidth:  delegate method
• – browser:sizeToFitWidthOfColumn:  delegate method
• – browserColumnConfigurationDidChange:  delegate method

Displaying Expansion Tooltips

• – browser:shouldShowCellExpansionForRow:column:  delegate method

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

• Available in Mac OS X v10.0 and later.

See Also

• – cellPrototype
• – setCellPrototype:

Declared In

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

• Available in Mac OS X v10.3 and later.

See Also

• – columnsAutosaveName
• – setColumnsAutosaveName:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setAcceptsArrowKeys:

Declared In

addColumn

Adds a column to the right of the last column.

- (void)addColumn

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – columnOfMatrix:
• – displayColumn:
• – selectedColumn

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setAllowsBranchSelection:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setAllowsEmptySelection:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setAllowsMultipleSelection:

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – setAllowsTypeSelect:

Declared In

backgroundColor

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

- (NSColor *)backgroundColor

Return Value

The receiver’s background color.

Default: [NSColor whiteColor]

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setBackgroundColor:
• – isOpaque

Declared In

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

• Available in Mac OS X v10.5 and later.

See Also

• – browser:canDragRowsWithIndexes:inColumn:withEvent:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setCellPrototype:
• – setCellClass:

Declared In

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

• Available in Mac OS X v10.3 and later.

See Also

• – columnWidthForColumnContentWidth:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – matrixInColumn:

Declared In

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

• Available in Mac OS X v10.3 and later.

See Also

• – setColumnResizingType:

Declared In

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

• Available in Mac OS X v10.3 and later.

See Also

• – setColumnsAutosaveName:

Declared In

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

• Available in Mac OS X v10.3 and later.

See Also

• – columnContentWidthForColumnWidth:

Declared In

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver's delegate.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Declared In

displayAllColumns

Updates the receiver to display all loaded columns.

- (void)displayAllColumns

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addColumn
• – validateVisibleColumns

Declared In

displayColumn:

Updates the receiver to display the given column.

- (void)displayColumn:(NSInteger)column

Parameters

column

The index of the column to display.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addColumn
• – validateVisibleColumns

Declared In

doClick:

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

- (void)doClick:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – sendAction

Declared In

doDoubleClick:

Responds to double clicks in a column of the receiver.

- (void)doDoubleClick:(id)sender

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDoubleAction:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setDoubleAction:

Declared In

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:

• NSZeroPoint: The image is centered under the pointer.

Return Value

Image representing the visible cells identified by rowIndexes.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – browser:draggingImageForRowsWithIndexes:inColumn:withEvent:offset:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setTitle:ofColumn:
• – titleFrameOfColumn:
• – titleHeight

Declared In

firstVisibleColumn

Returns the index of the first visible column.

- (NSInteger)firstVisibleColumn

Return Value

The index of the first visible column.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lastVisibleColumn
• – numberOfVisibleColumns

Declared In

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

• Available in Mac OS X v10.0 and later.

Declared In

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

• Available in Mac OS X v10.0 and later.

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setHasHorizontalScroller:

Declared In

isLoaded

Returns whether column 0 is loaded.

- (BOOL)isLoaded

Return Value

YES if column 0 is loaded; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – loadColumnZero
• – reloadColumn:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – setTitled:

Declared In

lastColumn

Returns the index of the last column loaded.

- (NSInteger)lastColumn

Return Value

The index of the last loaded column.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – selectedColumn
• – setLastColumn:

Declared In

lastVisibleColumn

Returns the index of the last visible column.

- (NSInteger)lastVisibleColumn

Return Value

The index of the last visible column.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – firstVisibleColumn
• – numberOfVisibleColumns

Declared In

loadColumnZero

Loads column 0; unloads previously loaded columns.

- (void)loadColumnZero

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isLoaded
• – reloadColumn:

Declared In

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

• Available in Mac OS X v10.0 and later.

See Also

• – selectedCellInColumn:

Declared In

matrixClass

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