- Inherits from:
- NSControl : NSView : NSResponder : NSObject
- Conforms to:
- NSCoding
- (NSResponder)
- NSObject (NSObject)
Declared in:
- AppKit/NSBrowser.h
NSBrowser 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. When working with a hierarchy of data, the levels are displayed in columns, which are numbered from left to right, beginning with 0. Each column consists of an NSScrollView containing an NSMatrix filled with NSBrowserCells. NSBrowser relies on a delegate to provide the data in its NSBrowserCells. See the NSBrowserCell class description for more on its implementation.
An entry in an NSBrowser's column can be either a branch node (such as a directory) or a leaf node (such as a file). When the user selects a single branch node entry in a column, the NSBrowser sends itself the addColumn message, which messages its delegate to load the next column. The user's selection can be represented as a character string; if the selection is hierarchical (for example, a filename within a directory), each component of the path to the selected node is separated by "/". To use some other character as the delimiter, invoke setPathSeparator:.
An NSBrowser can be set to allow selection of multiple entries in a column, or to limit selection to a single entry. When set for multiple selection, it can also be set to limit multiple selection to leaf nodes only, or to allow selection of both types of nodes together.
As a subclass of NSControl, NSBrowser has a target object and action message. Each time the user selects one or more entries in a column, the action message is sent to the target. NSBrowser also adds an action to be sent when the user double-clicks on an entry, which allows the user to select items without any action being taken, and then double-click to invoke some useful action such as opening a file.
The user interface features of an NSBrowser can be changed in a number of ways. The NSBrowser may or may not have a horizontal scroller. (The NSBrowser's columns, by contrast, always have vertical scrollers-although a scroller's buttons and knob might be invisible if the column doesn't contain many entries.) You generally shouldn't create an NSBrowser without a horizontal scroller; if you do, you must make sure the bounds rectangle of the NSBrowser is wide enough that all the columns can be displayed. An NSBrowser's columns may be bordered and titled, bordered and untitled, or unbordered and untitled. A column's title may be taken from the selected entry in the column to its left, or may be provided explicitly by the NSBrowser or its delegate.
NSBrowser requires a delegate to provide it with data to display. The delegate is responsible for providing the data and for setting each item as a branch or leaf node, enabled or disabled. It can also receive notification of events like scrolling and requests for validation of columns that may have changed.
You can implement one of two delegate types: active or passive. An active delegate creates a column's rows (that is, the NSBrowserCells) itself, while a passive one leaves that job to the NSBrowser. Normally, passive delegates are preferable, because they're easier to implement. An active delegate must implement browser:createRowsForColumn:inMatrix: to create the rows of the specified column. A passive delegate, on the other hand, must implement browser:numberOfRowsInColumn: to let the NSBrowser know how many rows to create. These two methods are mutually exclusive; you can implement one or the other, but not both. (The NSBrowser ascertains what type of delegate it has by which method the delegate responds to.)
Both types of delegate implement browser:willDisplayCell:atRow:column: to set up state (such as the cell's string value and whether the cell is a leaf or a branch) before an individual cell is displayed. (This delegate method doesn't need to invoke NSBrowserCell's setLoaded: method, because the NSBrowser can determine that state by itself.) An active delegate can instead set all the cells' state at the time the cells are created, in which case it doesn't need to implement browser:willDisplayCell:atRow:column:. However, a passive delegate must always implement this method.
- Setting component classes
- + cellClass
- - setCellClass:
- - cellPrototype
- - setCellPrototype:
- - matrixClass
- - setMatrixClass:
- Getting matrices, cells, and rows
- - selectedCell
- - selectedCellInColumn:
- - selectedCells
- - selectAll:
- - selectedRowInColumn:
- - selectRow:inColumn:
- - loadedCellAtRow:column:
- - matrixInColumn:
- Getting and setting paths
- - path
- - setPath:
- - pathToColumn:
- - pathSeparator
- - setPathSeparator:
- Manipulating columns
- - addColumn
- - displayAllColumns
- - displayColumn:
- - columnOfMatrix:
- - selectedColumn
- - lastColumn
- - setLastColumn:
- - firstVisibleColumn
- - numberOfVisibleColumns
- - lastVisibleColumn
- - validateVisibleColumns
- Loading columns
- - isLoaded
- - loadColumnZero
- - reloadColumn:
- Setting selection characteristics
- - allowsBranchSelection
- - setAllowsBranchSelection:
- - allowsEmptySelection
- - setAllowsEmptySelection:
- - allowsMultipleSelection
- - setAllowsMultipleSelection:
- Setting column characteristics
- - reusesColumns
- - setReusesColumns:
- - maxVisibleColumns
- - setMaxVisibleColumns:
- - minColumnWidth
- - setMinColumnWidth:
- - separatesColumns
- - setSeparatesColumns:
- - takesTitleFromPreviousColumn
- - setTakesTitleFromPreviousColumn:
- Manipulating column titles
- - titleOfColumn:
- - setTitle:ofColumn:
- - isTitled
- - setTitled:
- - drawTitleOfColumn:inRect:
- - titleHeight
- - titleFrameOfColumn:
- Scrolling an NSBrowser
- - scrollColumnToVisible:
- - scrollColumnsLeftBy:
- - scrollColumnsRightBy:
- - updateScroller
- - scrollViaScroller:
- Showing a horizontal scroller
- - hasHorizontalScroller
- - setHasHorizontalScroller:
- Setting the behavior of arrow keys
- - acceptsArrowKeys
- - setAcceptsArrowKeys:
- - sendsActionOnArrowKeys
- - setSendsActionOnArrowKeys:
- Getting column frames
- - frameOfColumn:
- - frameOfInsideOfColumn:
- Arranging browser components
- - tile
- Setting the delegate
- - delegate
- - setDelegate:
- Target and action
- - doubleAction
- - setDoubleAction:
- - sendAction
- Event handling
- - doClick:
- - doDoubleClick:
+ (Class)cellClass
See Also: - cellPrototype, - setCellPrototype:
- (BOOL)acceptsArrowKeys
See Also: - setAcceptsArrowKeys:
- (void)addColumn
See Also: - columnOfMatrix:, - displayColumn:, - selectedColumn
- (BOOL)allowsBranchSelection
See Also: - setAllowsBranchSelection:
- (BOOL)allowsEmptySelection
See Also: - setAllowsEmptySelection:
- (BOOL)allowsMultipleSelection
See Also: - setAllowsMultipleSelection:
- (id)cellPrototype
See Also: - setCellPrototype:, - setCellClass:
- (int)columnOfMatrix:(NSMatrix
*)matrix
See Also: - matrixInColumn:
- (id)delegate
See Also: - setDelegate:
- (void)displayAllColumns
See Also: - addColumn, - validateVisibleColumns
- (void)displayColumn:(int)column
See Also: - addColumn, - validateVisibleColumns
- (void)doClick:(id)sender
See Also: - sendAction
- (void)doDoubleClick:(id)sender
See Also: - setDoubleAction:
- (SEL)doubleAction
See Also: - setDoubleAction:
- (void)drawTitleOfColumn:(int)column
inRect:(NSRect)aRect
See Also: - setTitle:ofColumn:, - titleFrameOfColumn:, - titleHeight
- (int)firstVisibleColumn
See Also: - lastVisibleColumn, - numberOfVisibleColumns
- (NSRect)frameOfColumn:(int)column
- (NSRect)frameOfInsideOfColumn:(int)column
- (BOOL)hasHorizontalScroller
See Also: - setHasHorizontalScroller:
- (BOOL)isLoaded
See Also: - loadColumnZero, - reloadColumn:
- (BOOL)isTitled
See Also: - setTitled:
- (int)lastColumn
See Also: - selectedColumn, - setLastColumn:
- (int)lastVisibleColumn
See Also: - firstVisibleColumn, - numberOfVisibleColumns
- (void)loadColumnZero
See Also: - isLoaded, - reloadColumn:
- (id)loadedCellAtRow:(int)row
column:(int)column
See Also: - selectedCellInColumn:
- (Class)matrixClass
See Also: - setMatrixClass:
- (NSMatrix *)matrixInColumn:(int)column
- (int)maxVisibleColumns
See Also: - setMaxVisibleColumns:
- (float)minColumnWidth
See Also: - setMinColumnWidth:
- (int)numberOfVisibleColumns
See Also: - validateVisibleColumns
- (NSString *)path
Invoking this method is equivalent to invoking pathToColumn: for all columns.
See Also: - setPath:
- (NSString *)pathSeparator
See Also: - setPathSeparator:
- (NSString *)pathToColumn:(int)column
See Also: - path, - setPath:
- (void)reloadColumn:(int)column
See Also: - isLoaded, - loadColumnZero
- (BOOL)reusesColumns
See Also: - setReusesColumns:
- (void)scrollColumnToVisible:(int)column
See Also: - scrollViaScroller:, - updateScroller
- (void)scrollColumnsLeftBy:(int)shiftAmount
See Also: - scrollViaScroller:, - updateScroller
- (void)scrollColumnsRightBy:(int)shiftAmount
See Also: - scrollViaScroller:, - updateScroller
- (void)scrollViaScroller:(NSScroller
*)sender
See Also: - updateScroller
- (void)selectAll:(id)sender
See Also: - selectedCell, - selectedCells, - selectedColumn
- (void)selectRow:(int)row
inColumn:(int)column
See Also: - loadedCellAtRow:column:
- (id)selectedCell
See Also: - loadedCellAtRow:column:, - selectedCell, - selectRow:inColumn:
- (id)selectedCellInColumn:(int)column
See Also: - loadedCellAtRow:column:, - selectedCell, - selectedRowInColumn:
- (NSArray *)selectedCells
See Also: - selectAll:, - selectedCell
- (int)selectedColumn
See Also: - columnOfMatrix:, - selectAll:
- (int)selectedRowInColumn:(int)column
See Also: - loadedCellAtRow:column:, - selectedCell, - selectedCellInColumn:
- (BOOL)sendAction
- (BOOL)sendsActionOnArrowKeys
See Also: - acceptsArrowKeys, - setSendsActionOnArrowKeys:
- (BOOL)separatesColumns
See Also: - setSeparatesColumns:
- (void)setAcceptsArrowKeys:(BOOL)flag
See Also: - acceptsArrowKeys, - sendsActionOnArrowKeys
- (void)setAllowsBranchSelection:(BOOL)flag
See Also: - allowsBranchSelection
- (void)setAllowsEmptySelection:(BOOL)flag
See Also: - allowsEmptySelection
- (void)setAllowsMultipleSelection:(BOOL)flag
See Also: - allowsMultipleSelection
- (void)setCellClass:(Class)factoryId
See Also: + cellClass, - cellPrototype
- (void)setCellPrototype:(NSCell
*)aCell
See Also: + cellClass, - cellPrototype, - setCellClass:
- (void)setDelegate:(id)anObject
See Also: - delegate
- (void)setDoubleAction:(SEL)aSelector
See Also: - doubleAction, - sendAction
- (void)setHasHorizontalScroller:(BOOL)flag
See Also: - hasHorizontalScroller
- (void)setLastColumn:(int)column
See Also: - lastColumn, - lastVisibleColumn
- (void)setMatrixClass:(Class)factoryId
See Also: - matrixClass
- (void)setMaxVisibleColumns:(int)columnCount
See Also: - maxVisibleColumns
- (void)setMinColumnWidth:(float)columnWidth
See Also: - minColumnWidth
- (BOOL)setPath:(NSString
*)path
See Also: - path, - pathToColumn:, - pathSeparator, - setPathSeparator:
- (void)setPathSeparator:(NSString
*)newString
See Also: - pathSeparator
- (void)setReusesColumns:(BOOL)flag
See Also: - reusesColumns
- (void)setSendsActionOnArrowKeys:(BOOL)flag
See Also: - sendsActionOnArrowKeys
- (void)setSeparatesColumns:(BOOL)flag
See Also: - separatesColumns
- (void)setTakesTitleFromPreviousColumn:(BOOL)flag
See Also: - takesTitleFromPreviousColumn
- (void)setTitle:(NSString
*)aString
ofColumn:(int)column
See Also: - drawTitleOfColumn:inRect:, - titleOfColumn:
- (void)setTitled:(BOOL)flag
See Also: - isTitled
- (BOOL)takesTitleFromPreviousColumn
See Also: - setTakesTitleFromPreviousColumn:
- (void)tile
- (NSRect)titleFrameOfColumn:(int)column
See Also: - drawTitleOfColumn:inRect:
- (float)titleHeight
See Also: - drawTitleOfColumn:inRect:
- (NSString *)titleOfColumn:(int)column
See Also: - setTitle:ofColumn:
- (void)updateScroller
See Also: - scrollViaScroller:
- (void)validateVisibleColumns
See Also: - numberOfVisibleColumns
- (void)browser:(NSBrowser
*)sender
createRowsForColumn:(int)column
inMatrix:(NSMatrix *)matrix
See Also: - browser:willDisplayCell:atRow:column:
- (int)browser:(NSBrowser
*)sender
numberOfRowsInColumn:(int)column
See Also: - browser:willDisplayCell:atRow:column:
- (BOOL)browser:(NSBrowser
*)sender
isColumnValid:(int)column
- (BOOL)browser:(NSBrowser
*)sender
selectCellWithString:(NSString
*)title
inColumn:(int)column
See Also: - selectedCellInColumn:
- (BOOL)browser:(NSBrowser
*)sender
selectRow:(int)row
inColumn:(int)column
See Also: - selectedRowInColumn:, - selectRow:inColumn:
- (NSString *)browser:(NSBrowser
*)sender
titleOfColumn:(int)column
See Also: - setTitle:ofColumn:, - titleOfColumn:
- (void)browser:(NSBrowser
*)sender
willDisplayCell:(id)cell
atRow:(int)row
column:(int)column
See Also: - browser:createRowsForColumn:inMatrix:, - browser:numberOfRowsInColumn:
- (void)browserDidScroll:(NSBrowser
*)sender
- (void)browserWillScroll:(NSBrowser
*)sender