Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSBrowser

Inherits From:	NSControl : NSView : NSResponder : NSObject

Conforms To:	NSCoding (NSResponder)
NSObject (NSObject)

Declared In:	AppKit/NSBrowser.h 

Class Description

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.

Browser Selection

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.

User Interface Features

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's 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 the Delegate 

- (id)delegate	Returns the NSBrowser's delegate.

- (void)setDelegate:(id)anObject	Sets the NSBrowser's delegate to anObject. 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:

Target and Action 

- (SEL)doubleAction	Returns the NSBrowser's double-click action method.

- (BOOL)sendAction	Sends the action message to the target. Returns YES upon success, NO if no responder for the message could be found. 

- (void)setDoubleAction:(SEL)aSelector	Sets the NSBrowser's double-click action to aSelector.

Setting Component Classes 

+ (Class)cellClass	Returns the NSBrowserCell class (regardless of whether a setCellClass: message has been sent to a particular instance).

- (id)cellPrototype	Returns the NSBrowser's prototype NSCell.

- (Class)matrixClass	Returns the class of NSMatrix used in the NSBrowser's columns.

- (void)setCellClass:(Class)classId	Sets the class of NSCell used in the columns of the NSBrowser.

- (void)setCellPrototype:(NSCell *)aCell	Sets the NSCell instance copied to display items in the columns of NSBrowser.

- (void)setMatrixClass:(Class)classId	Sets the class of NSMatrix used in the NSBrowser's columns.

Setting NSBrowser Behavior 

- (BOOL)reusesColumns	Returns YES if NSMatrix objects aren't freed when their columns are unloaded. 

- (void)setReusesColumns:(BOOL)flag	If flag is YES, prevents NSMatrix objects from being freed when their columns are unloaded, so they can be reused.

- (void)setTakesTitleFromPreviousColumn:(BOOL)flag	
	Sets whether the title of a column is set to the string value of the selected NSCell in the previous column.

- (BOOL)takesTitleFromPreviousColumn	Returns YES if the title of a column is set to the string value of the selected NSCell in the previous column.

Allowing Different Types of Selection 

- (BOOL)allowsBranchSelection	Returns whether the user can select branch items when multiple selection is enabled.

- (BOOL)allowsEmptySelection	Returns whether there can be nothing selected.

- (BOOL)allowsMultipleSelection	Returns whether the user can select multiple items.

- (void)setAllowsBranchSelection:(BOOL)flag	Sets whether the user can select branch items when multiple selection is enabled.

- (void)setAllowsEmptySelection:(BOOL)flag	Sets whether there can be nothing selected.

- (void)setAllowsMultipleSelection:(BOOL)flag	Sets whether the user can select multiple items.

Setting Arrow Key Behavior

- (BOOL)acceptsArrowKeys	Returns YES if the arrow keys are enabled.	

- (BOOL)sendsActionOnArrowKeys	Returns NO if pressing an arrow key only scrolls the browser, YES if it also sends the action message specified by setAction:.

- (void)setAcceptsArrowKeys:(BOOL)flag	Enables or disables the arrow keys.

- (void)setSendsActionOnArrowKeys:(BOOL)flag	Sets whether pressing an arrow key will cause the action message to be sent (in addition to causing scrolling). 

Showing a Horizontal Scroller 

- (void)setHasHorizontalScroller:(BOOL)flag	Sets whether an NSScroller is used to scroll horizontally.

- (BOOL)hasHorizontalScroller	Returns whether an NSScroller is used to scroll horizontally.

Setting the NSBrowser's Appearance 

- (int)maxVisibleColumns	Returns the maximum number of visible columns. 

- (int)minColumnWidth	Returns the minimum column width.

- (BOOL)separatesColumns	Returns whether columns are separated by bezeled borders.

- (void)setMaxVisibleColumns:(int)columnCount	Sets the maximum number of columns displayed.

- (void)setMinColumnWidth:(int)columnWidth	Sets the minimum column width.

- (void)setSeparatesColumns:(BOOL)flag	Sets whether to separate columns with bezeled borders.

Manipulating Columns 

- (void)addColumn	Adds a column to the right of the last column.

- (int)columnOfMatrix:(NSMatrix *)matrix	Returns the column number in which matrix is located.

- (void)displayAllColumns	Updates the NSBrowser to display all loaded columns.

- (void)displayColumn:(int)column	Updates the NSBrowser to display the column with the given index.

- (int)firstVisibleColumn	Returns the index of the first visible column.

- (BOOL)isLoaded	Returns whether column zero is loaded.

- (int)lastColumn	Returns the index of the last column loaded.

- (int)lastVisibleColumn	Returns the index of the last visible column.

- (void)loadColumnZero	Loads column zero; unloads previously loaded columns.

- (int)numberOfVisibleColumns	Returns the number of columns visible.

- (void)reloadColumn:(int)column	Reloads column if it is loaded; sets it as the last column.

- (void)selectAll:(id)sender	Selects all NSCells in the last column of the NSBrowser.

- (int)selectedColumn	Returns the index of the last column with a selected item. 

- (void)setLastColumn:(int)column	Sets the last column to column.

- (void)validateVisibleColumns	Invokes delegate method browser:isColumnValid: for visible columns.

Manipulating Column Titles 

- (void)drawTitle:(NSString *)title	Draws the title for the column at index column.
inRect:(NSRect)aRect
ofColumn:(int)column

- (BOOL)isTitled	Returns whether columns display titles.

- (void)setTitled:(BOOL)flag	Sets whether columns display titles.

- (void)setTitle:(NSString *)aString	Sets the title of the column at index column to aString.	 
ofColumn:(int)column

- (NSRect)titleFrameOfColumn:(int)column	Returns the bounds of the title frame for the column at index column.

- (float)titleHeight	Returns the height of column titles. 

- (NSString *)titleOfColumn:(int)column	Returns the title displayed for the column at index column.

Scrolling an NSBrowser 

- (void)scrollColumnsLeftBy:(int)shiftAmount	Scrolls columns left by shiftAmount columns.

- (void)scrollColumnsRightBy:(int)shiftAmount	Scrolls columns right by shiftAmount columns. 

- (void)scrollColumnToVisible:(int)column	Scrolls to make the column at index column visible.

- (void)scrollViaScroller:(NSScroller *)sender	Scrolls columns left or right based on an NSScroller. 

- (void)updateScroller	Updates the horizontal scroller to reflect column positions.

Event Handling 

- (void)doClick:(id)sender	Responds to mouse clicks in a column of the NSBrowser.

- (void)doDoubleClick:(id)sender	Responds to double-clicks in a column of the NSBrowser. 

Getting Matrices and Cells 

- (id)loadedCellAtRow:(int)row	Loads if necessary and returns the NSCell at row in	 
column:(int)column		column.

- (NSMatrix *)matrixInColumn:(int)column	Returns the matrix located in column.

- (id)selectedCell	Returns the last (rightmost and lowest) selected NSCell.

- (id)selectedCellInColumn:(int)column	Returns the last (lowest) NSCell that's selected in column.

- (NSArray *)selectedCells	Returns all the rightmost selected NSCells.

Getting Column Frames 

- (NSRect)frameOfColumn:(int)column	Returns the rectangle containing the column at index column.

- (NSRect)frameOfInsideOfColumn:(int)column	Returns the rectangle containing the column at index column, not including borders.

Manipulating Paths 

- (NSString *)path	Returns the browser's current path. 

- (NSString *)pathSeparator	Returns the path separator. The default is ª/º.

- (NSString *)pathToColumn:(int)column	Returns a string representing the path from the first column to the column at index column.

- (BOOL)setPath:(NSString *)path	Parses path and selects corresponding items in columns.

- (void)setPathSeparator:(NSString *)aString	Sets the path separator to aString.

Arranging an NSBrowser's Components 

- (void)tile	Adjusts the various subviews of NSBrowserÐscrollers, columns, titles, and so onÐwithout redrawing.  Your code shouldn't send this message.  It's invoked any time the appearance of the NSBrowser changes.

Methods Implemented by the Delegate 

- (void)browser:(NSBrowser *)sender 	Creates a row in matrix for each row of data to be displayed
createRowsForColumn:(int)column 		 in column of the browser. Either this method or 
inMatrix:(NSMatrix *)matrix		browser:numberOfRowsInColumn: must be implemented, but not both (or an NSBrowserIllegalDelegateException will be raised).

- (BOOL)browser:(NSBrowser *)sender	 
isColumnValid:(int)column	Returns whether the contents of the specified column are valid.

- (int)browser:(NSBrowser *)sender	Returns the number of rows of data in the column at index	 
numberOfRowsInColumn:(int)column		column. Either this method or 
		browser:createRowsForColumn:inMatrix: must be implemented, but not both.

- (BOOL)browser:(NSBrowser *)sender	 Asks the delegate to select the NSCell with title title in 
selectCell:(NSString *)title		 the column at index column.
inColumn:(int)column	

- (NSString *)browser:(NSBrowser *)sender	 Queries the delegate for the title to display above the 
titleOfColumn:(int)column		column at index column.

- (void)browser:(NSBrowser *)sender 	Notifies the delegate when the NSBrowser will display 
willDisplayCell:(id)cell 		the specified cell. The delegate should set any state
atRow:(int)row 		necessary for correct display of the cell.
column:(int)column

- (void)browserDidScroll:(NSBrowser *)sender	Notifies the delegate when the NSBrowser has scrolled.

- (void)browserWillScroll:(NSBrowser *)sender	Notifies the delegate when the NSBrowser will scroll.