Inherits from: NSControl : NSView : NSResponder : NSObject
Package: com.apple.yellow.application
Implements: NSCoding (NSResponder)
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 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.
- Setting component classes
- cellClass
- setCellClass:
- cellPrototype
- setCellPrototype
- matrixClass
- setMatrixClass:
- 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
public NSBrowser(NSRect aRect)
public static Class cellClass()
See Also: cellPrototype, setCellPrototype
public boolean
acceptsArrowKeys
()
true
if
the arrow keys are enabled.See Also: setAcceptsArrowKeys
public void addColumn()
See Also: columnOfMatrix, displayColumn, selectedColumn
public boolean allowsBranchSelection()
See Also: setAllowsBranchSelection
public boolean allowsEmptySelection()
See Also: setAllowsEmptySelection
public boolean allowsMultipleSelection()
See Also: setAllowsMultipleSelection
public NSCell cellPrototype()
See Also: setCellClass:setCellPrototype
public int columnOfMatrix(NSMatrix matrix)
See Also: matrixInColumn:
public Object delegate()
See Also: setDelegate
public void displayAllColumns()
See Also: addColumn, validateVisibleColumns
public void displayColumn(int column)
See Also: addColumn, validateVisibleColumns
public void doClick(Object sender)
See Also: sendAction
public void doDoubleClick(Object sender)
See Also: setDoubleAction
public NSSelector doubleAction()
See Also: setDoubleAction
public void drawTitleOfColumn(int column, NSRect aRect)
See Also: setTitleOfColumn, titleFrameOfColumn, titleHeight
public int firstVisibleColumn()
See Also: lastVisibleColumn, numberOfVisibleColumns
public NSRect frameOfColumn(int column)
public NSRect frameOfInsideOfColumn(int column)
public boolean hasHorizontalScroller()
See Also: setHasHorizontalScroller
public boolean isLoaded()
See Also: loadColumnZero, reloadColumn
public boolean isTitled()
See Also: setTitled
public int lastColumn()
See Also: selectedColumn, setLastColumn
public int lastVisibleColumn()
See Also: firstVisibleColumn, numberOfVisibleColumns
public void loadColumnZero()
See Also: isLoaded, reloadColumn
public NSCell loadedCellAtLocation(int row, int column)
See Also: selectedCellInColumn
public Class matrixClass()
See Also: setNewMatrixClass
public NSMatrix matrixInColumn(int column)
public int maxVisibleColumns()
See Also: setMaxVisibleColumns
public float minColumnWidth()
See Also: setMinColumnWidth
public int numberOfVisibleColumns()
See Also: validateVisibleColumns
public String path()
Invoking this method is equivalent to invoking pathToColumn for all columns.
See Also: setPath
public String pathSeparator()
See Also: setPathSeparator
public String
pathToColumn
(int column)
public void reloadColumn(int column)
See Also: isLoaded, loadColumnZero
public boolean reusesColumns()
true
if
NSMatrix objects aren't freed when their columns are unloaded.See Also: setReusesColumns
public void scrollColumnToVisible(int column)
See Also: scrollViaScroller, updateScroller
public void scrollColumnsLeftBy(int shiftAmount)
See Also: scrollViaScroller, updateScroller
public void scrollColumnsRightBy(int shiftAmount)
See Also: scrollViaScroller, updateScroller
public void scrollViaScroller(NSScroller sender)
See Also: updateScroller
public void selectAll(Object sender)
See Also: selectedCell, selectedCells, selectedColumn
public void selectRowInColumn(int row, int column)
See Also: loadedCellAtLocation
public NSCell selectedCell()
See Also: loadedCellAtLocation, selectedCell, selectRowInColumn
public NSCell selectedCellInColumn(int column)
See Also: loadedCellAtLocation, selectedCell, selectedRowInColumn
public NSArray selectedCells()
See Also: selectAll, selectedCell
public int selectedColumn()
See Also: columnOfMatrix, selectAll
public int selectedRowInColumn(int column)
See Also: loadedCellAtLocation, selectedCell, selectedCellInColumn
public boolean sendAction()
true
upon
success,
false
if
no target for the message could be found.public boolean sendsActionOnArrowKeys()
false
if
pressing an arrow key only scrolls the browser,
true
if
it also sends the action message specified by setAction.See Also: acceptsArrowKeys, setSendsActionOnArrowKeys
public boolean separatesColumns()
See Also: setSeparatesColumns
public void setAcceptsArrowKeys(boolean flag)
See Also: acceptsArrowKeys, sendsActionOnArrowKeys
public void setAllowsBranchSelection(boolean flag)
See Also: allowsBranchSelection
public void setAllowsEmptySelection(boolean flag)
See Also: allowsEmptySelection
public void setAllowsMultipleSelection(boolean flag)
See Also: allowsMultipleSelection
public void setCellPrototype(NSCell aCell)
See Also: cellClass, cellPrototype
public void setDelegate(Object anObject)
See Also: delegate
public void setDoubleAction(NSSelector aSelector)
See Also: doubleAction, sendAction
public void setHasHorizontalScroller(boolean flag)
See Also: hasHorizontalScroller
public void setLastColumn(int column)
See Also: lastColumn, lastVisibleColumn
public void setMaxVisibleColumns(int columnCount)
See Also: maxVisibleColumns
public void setMinColumnWidth(float columnWidth)
See Also: minColumnWidth
public void setNewCellClass(Class aClass)
See Also: cellClass, cellPrototype
public void setNewMatrixClass(Class aClass)
See Also: matrixClass
public boolean setPath(String path)
See Also: path, pathToColumn
public void setPathSeparator(String newString
See Also: pathSeparator
public void setReusesColumns(boolean flag)
true
,
prevents NSMatrix objects from being freed when their columns are
unloaded, so they can be reused.See Also: reusesColumns
public void setSendsActionOnArrowKeys(boolean flag)
See Also: sendsActionOnArrowKeys
public void setSeparatesColumns(boolean flag)
See Also: separatesColumns
public void setTakesTitleFromPreviousColumn(boolean flag)
See Also: takesTitleFromPreviousColumn
public void setTitleOfColumn(String aString, int column)
See Also: drawTitleOfColumn, titleOfColumn
public void setTitled(boolean flag)
See Also: isTitled
public boolean takesTitleFromPreviousColumn()
true
if
the title of a column is set to the string value of the selected NSCell
in the previous column.See Also: setTakesTitleFromPreviousColumn
public void tile()
public NSRect titleFrameOfColumn(int
column)
See Also: drawTitleOfColumn
public float titleHeight()
See Also: drawTitleOfColumn
public String titleOfColumn(int column)
See Also: setTitleOfColumn
public void updateScroller()
See Also: scrollViaScroller
public void validateVisibleColumns()
See Also: numberOfVisibleColumns
public abstract void browserCreateRowsForColumn(NSBrowser sender, int column, NSMatrix matrix)
See Also: browserWillDisplayCell
public abstract boolean browserIsColumnValid(NSBrowser sender, int column)
false
is returned, sender reloads
the column. This method is invoked in response to validateVisibleColumns being
sent to sender.public abstract int browserNumberOfRowsInColumn(NSBrowser sender, int column)
See Also: browserWillDisplayCell
public abstract boolean browserSelectCellWithStringInColumn(NSBrowser sender, String title, int column)
false
,
the NSCell is not selected.See Also: selectedCellInColumn
public abstract boolean browserSelectRowInColumn(NSBrowser sender, int row, int column)
false
,
the NSCell is not selected.See Also: selectedRowInColumn, selectRowInColumn
public abstract String browserTitleOfColumn(NSBrowser sender, int column)
See Also: setTitleOfColumn, titleOfColumn
public abstract void browserWillDisplayCell(NSBrowser sender, Object cell, int row, intcolumn)
See Also: browserCreateRowsForColumn, browserNumberOfRowsInColumn
public abstract void browserDidScroll(NSBrowser sender)
public abstract void browserWillScroll(NSBrowser sender)