Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSBrowser


Inherits from:
NSControl : NSView : NSResponder : NSObject
Package:
com.apple.yellow.application


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 browserCreateRowsForColumn to create the rows of the specified column. A passive delegate, on the other hand, must implement browserNumberOfRowsInColumn 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 browserWillDisplayCell 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 browserWillDisplayCell. However, a passive delegate must always implement this method.




Method Types


Constructors
NSBrowser
Setting component classes
cellClass
cellPrototype
setCellPrototype
matrixClass
Getting matrices, cells, and rows
selectedCell
selectedCellInColumn
selectedCells
selectAll
selectedRowInColumn
selectRowInColumn
loadedCellAtLocation
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
setTitleOfColumn
isTitled
setTitled
drawTitleOfColumn
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


Constructors



NSBrowser

public NSBrowser()

Description forthcoming.

public NSBrowser(NSRect aRect)

Description forthcoming.


Static Methods



cellClass

public static Class cellClass()

Always returns the NSBrowserCell class (even if the developer has sent a setCellClass: message to a particular instance). This method is used by NSControl during initialization, and is not meant to be used by applications.

See Also: cellPrototype, setCellPrototype




Instance Methods



acceptsArrowKeys

public boolean acceptsArrowKeys()

Returnstrue if the arrow keys are enabled.

See Also: setAcceptsArrowKeys



addColumn

public void addColumn()

Adds a column to the right of the last column.

See Also: columnOfMatrix, displayColumn, selectedColumn



allowsBranchSelection

public boolean allowsBranchSelection()

Returns whether the user can select branch items when multiple selection is enabled.

See Also: setAllowsBranchSelection



allowsEmptySelection

public boolean allowsEmptySelection()

Returns whether there can be nothing selected.

See Also: setAllowsEmptySelection



allowsMultipleSelection

public boolean allowsMultipleSelection()

Returns whether the user can select multiple items.

See Also: setAllowsMultipleSelection



cellPrototype

public NSCell cellPrototype()

Returns the receiver's prototype NSCell.

See Also: setCellPrototype, setCellClass:



columnOfMatrix

public int columnOfMatrix(NSMatrix matrix)

Returns the column number in which matrix is located.

See Also: matrixInColumn:



delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate



displayAllColumns

public void displayAllColumns()

Updates the receiver to display all loaded columns.

See Also: addColumn, validateVisibleColumns



displayColumn

public void displayColumn(int column)

Updates the receiver to display the column with the given index.

See Also: addColumn, validateVisibleColumns



doClick

public void doClick(Object sender)

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

See Also: sendAction



doDoubleClick

public void doDoubleClick(Object sender)

Responds to double-clicks in a column of the receiver.

See Also: setDoubleAction



doubleAction

public NSSelector doubleAction()

Returns the receiver's double-click action method.

See Also: setDoubleAction



drawTitleOfColumn

public void drawTitleOfColumn( int column, NSRect aRect)

Draws the title for the column at index column within the rectangle defined by aRect.

See Also: setTitleOfColumn, titleFrameOfColumn, titleHeight



firstVisibleColumn

public int firstVisibleColumn()

Returns the index of the first visible column.

See Also: lastVisibleColumn, numberOfVisibleColumns



frameOfColumn

public NSRect frameOfColumn(int column)

Returns the rectangle containing the column at index column.

frameOfInsideOfColumn

public NSRect frameOfInsideOfColumn(int column)

Returns the rectangle containing the column at index column, not including borders.

hasHorizontalScroller

public boolean hasHorizontalScroller()

Returns whether an NSScroller is used to scroll horizontally.

See Also: setHasHorizontalScroller



isLoaded

public boolean isLoaded()

Returns whether column zero is loaded.

See Also: loadColumnZero, reloadColumn



isTitled

public boolean isTitled()

Returns whether columns display titles.

See Also: setTitled



lastColumn

public int lastColumn()

Returns the index of the last column loaded.

See Also: selectedColumn, setLastColumn



lastVisibleColumn

public int lastVisibleColumn()

Returns the index of the last visible column.

See Also: firstVisibleColumn, numberOfVisibleColumns



loadColumnZero

public void loadColumnZero()

Loads column zero; unloads previously loaded columns.

See Also: isLoaded, reloadColumn



loadedCellAtLocation

public NSCell loadedCellAtLocation( int row, int column)

Loads if necessary and returns the NSCell at row in column.

See Also: selectedCellInColumn



matrixClass

public Class matrixClass()

Returns the class of NSMatrix used in the receiver's columns.

See Also: setNewMatrixClass



matrixInColumn:

public NSMatrix matrixInColumn(int column)

Returns the matrix located in the column identified by index column.

maxVisibleColumns

public int maxVisibleColumns()

Returns the maximum number of visible columns.

See Also: setMaxVisibleColumns



minColumnWidth

public float minColumnWidth()

Returns the minimum column width in pixels.

See Also: setMinColumnWidth



numberOfVisibleColumns

public int numberOfVisibleColumns()

Returns the number of columns visible.

See Also: validateVisibleColumns



path

public String path()

Returns the receiver's current path. The components are separated with the string returned by pathSeparator.

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

See Also: setPath



pathSeparator

public String pathSeparator()

Returns the path separator. The default is "/".

See Also: setPathSeparator



pathToColumn

public String pathToColumn(int column)

Returns a string representing the path from the first column up to, but not including, the column at index column. The components are separated with the string returned by pathSeparator.

See Also: path, setPath



reloadColumn

public void reloadColumn(int column)

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

See Also: isLoaded, loadColumnZero



reusesColumns

public boolean reusesColumns()

Returns true if NSMatrix objects aren't freed when their columns are unloaded.

See Also: setReusesColumns



scrollColumnToVisible

public void scrollColumnToVisible(int column)

Scrolls to make the column at index column visible.

See Also: scrollViaScroller, updateScroller



scrollColumnsLeftBy

public void scrollColumnsLeftBy(int shiftAmount)

Scrolls columns left by shiftAmount columns.

See Also: scrollViaScroller, updateScroller



scrollColumnsRightBy

public void scrollColumnsRightBy(int shiftAmount)

Scrolls columns right by shiftAmount columns.

See Also: scrollViaScroller, updateScroller



scrollViaScroller

public void scrollViaScroller(NSScroller sender)

Scrolls columns left or right based on an NSScroller.

See Also: updateScroller



selectAll

public void selectAll(Object sender)

Selects all NSCells in the last column of the receiver.

See Also: selectedCell, selectedCells, selectedColumn



selectRowInColumn

public void selectRowInColumn( int row, int column)

Selects the cell at index row in the column identified by index column.

See Also: loadedCellAtLocation



selectedCell

public NSCell selectedCell()

Returns the last (rightmost and lowest) selected NSCell.

See Also: loadedCellAtLocation, selectedCell, selectRowInColumn



selectedCellInColumn

public NSCell selectedCellInColumn(int column)

Returns the last (lowest) NSCell selected in column.

See Also: loadedCellAtLocation, selectedCell, selectedRowInColumn



selectedCells

public NSArray selectedCells()

Returns all cells selected in the rightmost column.

See Also: selectAll, selectedCell



selectedColumn

public int selectedColumn()

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

See Also: columnOfMatrix, selectAll



selectedRowInColumn

public int selectedRowInColumn(int column)

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

See Also: loadedCellAtLocation, selectedCell, selectedCellInColumn



sendAction

public boolean sendAction()

Sends the action message to the target. Returns true upon success, false if no target for the message could be found.

sendsActionOnArrowKeys

public boolean sendsActionOnArrowKeys()

Returnsfalse if pressing an arrow key only scrolls the receiver,true if it also sends the action message specified by setAction.

See Also: acceptsArrowKeys, setSendsActionOnArrowKeys



separatesColumns

public boolean separatesColumns()

Returns whether columns are separated by bezeled borders.

See Also: setSeparatesColumns



setAcceptsArrowKeys

public void setAcceptsArrowKeys(boolean flag)

Enables or disables the arrow keys as used for navigating within and between browsers.

See Also: acceptsArrowKeys, sendsActionOnArrowKeys



setAllowsBranchSelection

public void setAllowsBranchSelection(boolean flag)

Sets whether the user can select branch items when multiple selection is enabled.

See Also: allowsBranchSelection



setAllowsEmptySelection

public void setAllowsEmptySelection(boolean flag)

Sets whether there can be nothing selected.

See Also: allowsEmptySelection



setAllowsMultipleSelection

public void setAllowsMultipleSelection(boolean flag)

Sets whether the user can select multiple items.

See Also: allowsMultipleSelection



setCellPrototype

public void setCellPrototype(NSCell aCell)

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

See Also: cellClass, cellPrototype



setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject. Throws BrowserIllegalDelegateException if the delegate specified by anObject doesn't respond to browserWillDisplayCell and either of the methods browserNumberOfRowsInColumn or browserCreateRowsForColumn.

See Also: delegate



setDoubleAction

public void setDoubleAction(NSSelector aSelector)

Sets the receiver's double-click action to aSelector.

See Also: doubleAction, sendAction



setHasHorizontalScroller

public void setHasHorizontalScroller(boolean flag)

Sets whether an NSScroller is used to scroll horizontally.

See Also: hasHorizontalScroller



setLastColumn

public void setLastColumn(int column)

Sets the last column to column.

See Also: lastColumn, lastVisibleColumn



setMaxVisibleColumns

public void setMaxVisibleColumns(int columnCount)

Sets the maximum number of columns displayed.

See Also: maxVisibleColumns



setMinColumnWidth

public void setMinColumnWidth(float columnWidth)

Sets the minimum column width in pixels.

See Also: minColumnWidth



setNewCellClass

public void setNewCellClass(Class aClass)

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

See Also: cellClass, cellPrototype



setNewMatrixClass

public void setNewMatrixClass(Class aClass)

Sets the matrix class (NSMatrix or an NSMatrix subclass) used in the receiver's columns.

See Also: matrixClass



setPath

public boolean setPath(String path)

Parses path using the current path separator, and selects corresponding items in the receiver's columns.

See Also: path, pathToColumn, pathSeparator, setPathSeparator



setPathSeparator

public void setPathSeparator(String newString)

Sets the path separator to newString.

See Also: pathSeparator



setReusesColumns

public void setReusesColumns(boolean flag)

If flag is true, prevents NSMatrix objects from being freed when their columns are unloaded, so they can be reused.

See Also: reusesColumns



setSendsActionOnArrowKeys

public void setSendsActionOnArrowKeys(boolean flag)

Sets whether pressing an arrow key will cause the action message to be sent (in addition to causing scrolling).

See Also: sendsActionOnArrowKeys



setSeparatesColumns

public void setSeparatesColumns(boolean flag)

Sets whether to separate columns with bezeled borders.

See Also: separatesColumns



setTakesTitleFromPreviousColumn

public void setTakesTitleFromPreviousColumn(boolean flag)

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

See Also: takesTitleFromPreviousColumn



setTitleOfColumn

public void setTitleOfColumn( String aString, int column)

Sets the title of the column at index column to aString.

See Also: drawTitleOfColumn, titleOfColumn



setTitled

public void setTitled(boolean flag)

Sets whether columns display titles.

See Also: isTitled



takesTitleFromPreviousColumn

public boolean takesTitleFromPreviousColumn()

Returnstrue if the title of a column is set to the string value of the selected NSCell in the previous column.

See Also: setTakesTitleFromPreviousColumn



tile

public void tile()

Adjusts the various subviews of the receiver-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.

titleFrameOfColumn

public NSRect titleFrameOfColumn(int column)

Returns the bounds of the title frame for the column at index column.

See Also: drawTitleOfColumn



titleHeight

public float titleHeight()

Returns the height of column titles.

See Also: drawTitleOfColumn



titleOfColumn

public String titleOfColumn(int column)

Returns the title displayed for the column at index column.

See Also: setTitleOfColumn



updateScroller

public void updateScroller()

Updates the horizontal scroller to reflect column positions.

See Also: scrollViaScroller



validateVisibleColumns

public void validateVisibleColumns()

Invokes delegate method browser:isColumnValid: for visible columns.

See Also: numberOfVisibleColumns




Methods Implemented By the Delegate


browserCreateRowsForColumn

public abstract void browserCreateRowsForColumn( NSBrowser sender, int column, NSMatrix matrix)

Creates a row in matrix for each row of data to be displayed in column of the browser. Either this method or browserNumberOfRowsInColumn must be implemented, but not both (or a BrowserIllegalDelegateException will be thrown).

See Also: browserWillDisplayCell



browserNumberOfRowsInColumn

public abstract int browserNumberOfRowsInColumn( NSBrowser sender, int column)

Returns the number of rows of data in the column at index column. Either this method or browserCreateRowsForColumn must be implemented, but not both.

See Also: browserWillDisplayCell



browserIsColumnValid

public abstract boolean browserIsColumnValid( NSBrowser sender, int column)

Returns whether the contents of the specified column are valid. If false is returned, sender reloads the column. This method is invoked in response to validateVisibleColumns being sent to sender.

browserSelectCellWithStringInColumn

public abstract boolean browserSelectCellWithStringInColumn( NSBrowser sender, String title, int column)

Asks the delegate to select the NSCell with title title in the column at index column. If the delegate returns false, the NSCell is not selected.

See Also: selectedCellInColumn



browserSelectRowInColumn

public abstract boolean browserSelectRowInColumn( NSBrowser sender, int row, int column)

Asks the delegate to select the NSCell at row row in the column at index column. If the delegate returns false, the NSCell is not selected.

See Also: selectedRowInColumn, selectRowInColumn



browserTitleOfColumn

public abstract String browserTitleOfColumn( NSBrowser sender, int column)

Asks the delegate for the title to display above the column at index column.

See Also: setTitleOfColumn, titleOfColumn



browserWillDisplayCell

public abstract void browserWillDisplayCell( NSBrowser sender, Object cell, int row, int column)

Notifies the delegate before the NSBrowser displays the specified cell at row in column. The delegate should set any state necessary for the correct display of the cell.

See Also: browserCreateRowsForColumn, browserNumberOfRowsInColumn



browserDidScroll

public abstract void browserDidScroll(NSBrowser sender)

Notifies the delegate when the NSBrowser has scrolled.

browserWillScroll

public abstract void browserWillScroll(NSBrowser sender)

Notifies the delegate when the NSBrowser will scroll.


Table of Contents