Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXBrowser



Inherits From: Control : View : Responder : Object
Declared In: appkit/NXBrowser.h



Class Description

NXBrowser 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 a ScrollView or ClipView containing a Matrix filled with NXBrowserCells.  NXBrowser relies on a delegate to provide the data in its NXBrowserCells.  See the BrowserCell class description for more on its implementation.



Browser Selection

An entry in an NXBrowser'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 NXBrowser 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, much like a UNIX file's pathname; however, the separator can be set to any character, not just `/'.  An NXBrowser 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 Control, NXBrowser 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.  NXBrowser 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 NXBrowser can be changed in a number of ways.  Columns in an NXBrowser may have up and down scroll buttons, scroll bars, both, or neither; the NXBrowser itself may or may not have left and right scroll buttons or a scroll bar.  You generally shouldn't create an NXBrowser without scrollers; if you do, you must make sure the bounds rectangle of the NXBrowser is large enough that all its rows and columns can be displayed.  An NXBrowser'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 NXBrowser or its delegate.  Interface Builder provides easier ways to set many of the user interface features described previously.



NXBrowser's Delegate

NXBrowser requires a delegate to provide it with data for 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 three delegate types--normal, lazy, or very lazy--depending on your needs for performance and memory use.  An NXBrowser can determine what type of delegate it has by which methods it responds to.  To implement a delegate, you implement the normal, lazy, or very lazy methods described below.  Two methods, browser:fillMatrix:inColumn: and browser:getNumRowsInColumn:, are mutually exclusive; you can implement one or the other, but not both.

A normal delegate loads an entire column of its NXBrowser at once, with the browser:fillMatrix:inColumn: method.  A normal delegate is useful for small sets of data, since it can quickly load each set without much delay, and since each set takes up little memory.  A normal delegate creates all of the Cells in a column and fills them with appropriate information, including the title for the Cell, whether it's a node or a leaf, and whether it's enabled or not.

Note:  Though called "normal," a normal delgate is not really the most commonly useful.  As stated, it's primary useful for small, static sets of data.  Lazy and very lazy delegates, described below, are much more flexible, and often end up being easier to program, since data only has to be accessed as it's needed by the NXBrowser.

A lazy delegate creates an entire column for an NXBrowser, but only fills the Cells in the column as requested by the NXBrowser.  It must implement both the browser:fillMatrix:inColumn: and browser:loadCell:atRow:inColumn: methods. When filling a column, it only needs to create the Cells, though it may actually fill them in partially or completely, perhaps setting only the title in order to sort the items.  A lazy delegate is useful for fairly large sets of data that would take a long time to load completely.  For example, a file system would be well served by a lazy delegate; it could fill each column with the names of all files in that directory, but only when the NXBrowser is about to display a particular Cell would the delegate check whether the file for that Cell is actually a directory (to set the Cell as a node or leaf), and whether the user has permission to access that file or directory (to set the Cell as enabled or disabled).

A very lazy delegate is responsible only for informing its NXBrowser how many items are in a particular column and for loading each Cell on request, with the browser: getNumRowsInColumn: and browser:loadCell:atRow:inColumn: methods.  Very lazy delegates make spare use of memory by not loading a Cell for an entry until it's about to be displayed; this is useful for large, potentially open-ended data spaces that are already sorted, or simply don't need to be sorted.  A very lazy delegate is also a good candidate for browsing a file system, provided that the file names can be loaded in the proper positions in a browser column based on their ordering.

An NXBrowser's delegate is also useful for manipulating the data in the NXBrowser on the request of another object.  For example, a panel may have a browser with some buttons for adding and deleting entries.  Instead of having the entire column reloaded when an entry is added or deleted, the delegate can directly access the NXBrower's Matrix for the selected column, adding or removing Cells, and then invoking NXBrowser's displayColumn: method to redraw that column only.



Instance Variables

id  target;

id delegate;

SEL action;

SEL doubleAction;

id matrixClass;

id cellPrototype;

unsigned short pathSeparator;


target The object notified by NXBrowser when one or more items are selected in a column.
delegate The object providing the data which is browsed by the NXBrowser.
action The message sent to the target when one or more entries are selected in a column.
doubleAction The message sent to the target when an entry in the NXBrowser is double-clicked.
matrixClass The class used to instantiate the matrices in the columns of NXBrowser; Matrix by default.
cellPrototype A Cell that is copied to create new Cells in the NXBrowser's Matrices; NXBrowserCell by default.
pathSeparator The character which separates the substrings of a path (see getPath:ToColumn:, setPath:).



Method Types

Initializing and freeing an NXBrowser
initFrame:
free
Setting the delegate setDelegate:
delegate
Target and action setAction:
action
setTarget:
target
setDoubleAction:
doubleAction
sendAction
Setting component classes setMatrixClass:
setCellClass:
setCellPrototype:
cellPrototype
Setting NXBrowser behavior setMultipleSelectionEnabled:
isMultipleSelectionEnabled
setBranchSelectionEnabled:
isBranchSelectionEnabled
setEmptySelectionEnabled:
isEmptySelectionEnabled
reuseColumns:
setEnabled:
acceptsFirstResponder
acceptArrowKeys:andSendActionMessages:
getTitleFromPreviousColumn:
Configuring controls useScrollBars:
useScrollButtons:
setHorizontalScrollButtonsEnabled:
areHorizontalScrollButtonsEnabled
setHorizontalScrollerEnabled:
isHorizontalScrollerEnabled
Setting the NXBrowser's appearance
setMinColumnWidth:
minColumnWidth
setMaxVisibleColumns:
maxVisibleColumns
numVisibleColumns
firstVisibleColumn
lastVisibleColumn
lastColumn
separateColumns:
columnsAreSeparated
Manipulating columns loadColumnZero
isLoaded
addColumn
reloadColumn:
displayColumn:
displayAllColumns
setLastColumn:
selectAll:
selectedColumn
columnOf:
validateVisibleColumns
Manipulating column titles setTitled:
isTitled
setTitle:ofColumn:
titleOfColumn:
getTitleFrame:ofColumn:
titleHeight
drawTitle:inRect:ofColumn:
clearTitleInRect:ofColumn:
Scrolling an NXBrowser scrollColumnsLeftBy:
scrollColumnsRightBy:
scrollColumnToVisible:
scrollUpOrDown:
scrollViaScroller:
reflectScroll:
updateScroller
Event handling mouseDown:
keyDown:
doClick:
doDoubleClick:
Getting Matrices and Cells getLoadedCellAtRow:inColumn:
matrixInColumn:
selectedCell
getSelectedCells:
Getting column frames getFrame:ofColumn:
getFrame:ofInsideOfColumn:
Manipulating paths setPathSeparator:
setPath:
getPath:toColumn:
Drawing drawSelf::
Resizing the NXBrowser sizeTo::
sizeToFit
Arranging an NXBrowser's components
tile



Instance Methods

acceptArrowKeys:andSendActionMessages:
acceptArrowKeys:(BOOL)acceptFlag andSendActionMessages:(BOOL)sendFlag

Sets NXBrowser handling of arrow key input.  If acceptFlag is YES, then the keyboard arrow keys move the selection whenever the NXBrowser or one of its subviews is the first responder; if acceptFlag is NO, arrow key input has no effect. Further, if sendFlag is YES, then when an arrow key is pressed, the NXBrowser's action message is sent as though the user had clicked on the new selection; if sendFlag is NO, then arrow keys only move the selection (if they are enabled).  Returns self.

This method replaces the acceptArrowKeys: method from NEXTSTEP Release 2.

See also:  acceptsFirstResponder



acceptsFirstResponder
(BOOL)acceptsFirstResponder

Returns YES if the NXBrowser accepts arrow key input, NO otherwise.  The default setting is NO.

See also:  acceptArrowKeys:andSendActionMessages:



action
(SEL)action

Returns the action sent to the target by the NXBrowser when the user makes a selection in one of its columns.

See also:  setAction:, doubleAction, target



addColumn
addColumn

Adds a column to the right of the last column in the NXBrowser and, if necessary, scrolls the NXBrowser so that the new column is visible.  Your code should never invoke this method; it's invoked as needed by doClick: and keyDown: when the user selects a single branch node entry in the NXBrowser, and by setPath: when it matches a path substring with a branch node entry.  Override this method if you need the NXBrowser to do any additional updating when a column is added, but be sure to send this message to super.  Returns self.

See also:  loadColumnZero, setPath:, reloadColumn:



areHorizontalScrollButtonsEnabled
(BOOL)areHorizontalScrollButtonsEnabled

Returns YES if horizontal scroll buttons are used by the NXBrowser and are enabled, NO otherwise.

See also:  setHorizontalScrollButtonsEnabled:, isHorizontalScrollerEnabled, setHorizontalScrollerEnabled:



cellPrototype
cellPrototype

Returns the NXBrowser's prototype Cell.  This Cell is copied to create new Cells in the columns of the NXBrowser.

See also:  setCellPrototype:



clearTitleInRect:ofColumn:
clearTitleInRect:(const NXRect *)aRect ofColumn:(int)column

Clears the title displayed in aRect above column.  Your code shouldn't invoke this method directly; it's sent whenever a column title needs to be cleared.  You can override this method if you draw your own column titles.  aRect is in the NXBrowser's coordinate system.  Returns self.



columnOf:
(int)columnOf:matrix

Returns the index of the column containing matrix; the leftmost (root) column is 0.  Returns 1 if no column contains matrix.

See also:  matrixInColumn:



columnsAreSeparated
(BOOL)columnsAreSeparated

Returns YES if columns are separated by a bezeled bar; NO if they're separated by a black line.  If the NXBrowser is set to display column titles, its columns are automatically separated by bezels.

See also:  separateColumns:, setTitled:



delegate
delegate

Returns the delegate of the NXBrowser, the object that provides data for the NXBrowser and responds to certain notification messages.

See also:  setDelegate:



displayAllColumns
displayAllColumns

Causes all columns currently visible in the NXBrowser to be redisplayed.  This method is useful for redisplaying the NXBrowser after manipulating it with display disabled in the window (for instance, if Cells in some of the columns are deleted). Returns self.

See also:  displayColumn:



displayColumn:
displayColumn:(int)column

Validates and displays column number columncolumn must already be loaded.  This method is useful for updating the NXBrowser after manipulating column with display disabled in the window.  Returns self.

See also:  displayAllColumns



doClick:
doClick:sender

Your code should never invoke this method.  This is the action message sent to the NXBrowser by a column's Matrix when a mouse-down event occurs in a column.  It sets the NXBrowser's last column to that of the Matrix where the click occurred, and removes any columns to the right that were previously loaded in the NXBrowser.  If a single branch node entry is selected by the event, this method sends addColumn to self to display the corresponding data in the column to the right.  It also sends the NXBrowser's action message to its target.  Returns self.

You may want to override this method to add specific behavior for mouse clicks.

See also:  action, target, doDoubleClick:



doDoubleClick:
doDoubleClick:sender

Your code should never invoke this method.  This is the action message sent to the NXBrowser by a column's Matrix when a double-click occurs in a column.  This method simply sends the double-click action message to the target; if no double-click action message is set, it sends the regular (single-click) action.  Returns self.

You may want to override this method to add specific behavior for double-click events.

See also:  doubleAction, target, doClick:



doubleAction
(SEL)doubleAction

Returns the action sent by the NXBrowser to its target when the user double-clicks an entry.  If no double-click action message has been set, this method returns the regular (single-click) action.

See also:  setDoubleAction:, action, target, doDoubleClick:



drawSelf::
drawSelf:(const NXRect *)rects :(int)rectCount

Draws the NXBrowser, loading column 0 if it has not been loaded.  Override this method if you change the way NXBrowser draws itself.  Your code should never invoke this method; it's invoked by the display method.  Returns self.

See also:  display (View)



drawTitle:inRect:ofColumn:
drawTitle:(const char *)title
inRect:(const NXRect *)aRect
ofColumn:(int)column

Your code should never invoke this method.  It's invoked whenever the NXBrowser needs to draw a column title.  You may override it if you want your own column titles drawn.  Returns self.



firstVisibleColumn
(int)firstVisibleColumn

Returns the index of the leftmost visible column.

See also:  lastVisibleColumn



free
free

Frees the NXBrowser and all the objects it manages:  ScrollViews, Matrices, Cells, scroll Buttons, prototypes, and so on. Returns nil.



getFrame:ofColumn:
(NXRect *)getFrame:(NXRect *)theRect ofColumn:(int)column

Returns a pointer to the rectangle (in NXBrowser coordinates) containing column; the pointer is returned both explicitly by the method and by reference in theRect.  The returned rectangle includes the bezel area surrounding the column.  If column isn't currently loaded or displayed, this method returns NULL, without changing the coordinates of the rectangle represented in theRect.  It also returns NULL if theRect is NULL.

See also:  getFrame:ofInsideOfColumn:



getFrame:ofInsideOfColumn:
(NXRect *)getFrame:(NXRect *)theRect ofInsideOfColumn:(int)column

Returns a pointer to the rectangle (in NXBrowser coordinates) containing the "inside" of column number column; the pointer is returned both explicitly by the method and by reference in theRect.  The "inside" is defined as the area in the column that contains the Cells and only that area (that is, no bezels).  If column isn't currently loaded or displayed, this method returns NULL, without changing the coordinates of the rectangle represented in theRect.  It also returns NULL if theRect is NULL.

See also:  getFrame:ofColumn:



getLoadedCellAtRow:inColumn:
getLoadedCellAtRow:(int)row inColumn:(int)column

Returns the Cell at row in column, if that column is currently in the NXBrowser.  This method creates and loads the Cell if necessary.  It's the safest way to get a particular Cell in a column, since lazy delegates don't load every Cell in a Matrix and very lazy delegates don't even create all Cells until they're displayed.  This method is preferred to the Matrix method cellAt::. If the specified column isn't in the NXBrowser, or if row doesn't exist in column, returns nil.

See also:  browser:loadCellAtRow:inColumn: (delegate method)



getPath:toColumn:
(char *)getPath:(char *)thePath toColumn:(int)column

Returns a pointer to the string representing the path to column, both explicitly and by reference in thePath.  Before invoking this method, you must allocate sufficient memory to accept the entire path string, and set thePath as a pointer to that memory.  If column isn't loaded or thePath is a null pointer, this method returns NULL.

The path is constructed by concatenating the string values in the selected Cells in each column, preceding each with the path separator.  For example, consider a path separator "@" and an NXBrowser with two columns.  If the selected Cell in the left column has the string value "fowl" and the selected Cell in the right column has the string value "duck," the resulting path is "@fowl@duck."  If there is no selection in the NXBrowser, the path will be "" (an empty string--not "@").  The default pathSeparator is the slash character ("/").

If multiple selection is enabled and there are multiple Cells selected, this method returns the path of the last (that is, the lowest) Cell in the last column.  Once the path is retrieved, the selected Cells can all be retrieved with getSelectedCells:, and their titles used with the path to manipulate the data they represent.

See also:  getSelectedCells:, pathSeparator, setPath:



getSelectedCells:
getSelectedCells:(List *)aList

Fills the provided List with the Cells in the NXBrowser that are selected.  The previous contents of aList are not altered; your code should be sure aList is empty before invoking this method.  If aList is nil, this method creates a List from the zone of the Matrix containing the Cells and returns it.  Returns aList, or the created List.

See also:  selectedCell



getTitleFrame:ofColumn:
(NXRect *)getTitleFrame:(NXRect *)theRect ofColumn:(int)column

Returns the rectangle (in NXBrowser coordinates) enclosing the title of column number column, both explicitly and by reference in theRect.  If the NXBrowser isn't displaying titles or if the specified column isn't loaded, returns this method returns NULL.



getTitleFromPreviousColumn:
getTitleFromPreviousColumn:(BOOL)flag

If flag is YES, sets the NXBrowser so that each column takes its title from the string value in the selected Cell in the column to its left, leaving column 0 untitled; use setTitle:ofColumn: to give column 0 a title.  This method affects the receiver only when it is titled (that is, when isTitled returns YES).

By default, the NXBrowser is set to get column titles from the previous column.  Send this message with NO as the argument if your delegate implements the browser:titleOfColumn: method or if you use the setTitle:ofColumn: method to set all column titles.  Returns self.

See also:  setTitled:, setTitle:ofColumn:, browser:titleOfColumn: (delegate method)



initFrame:
initFrame:(const NXRect *)frameRect

Initializes a new instance of NXBrowser with a bounds of frameRect.  The initialized NXBrowser is set to have column titles, to get titles from previous columns, and to use scrollbars.  The minimum column width is set to 100 and the path separator is set to the slash ("/") character.  The NXBrowser is set not to clip.  This method invokes the tile method to arrange the components of the NXBrowser (titles, scroll bars, Matrices, and so on).



isBranchSelectionEnabled
(BOOL)isBranchSelectionEnabled

Returns YES if a branch node can be selected, NO otherwise.

See also:  setBranchSelectionEnabled:



isEmptySelectionEnabled
(BOOL)isEmptySelectionEnabled

Returns YES if it is possible to have no Cells selected, NO otherwise.

See also:  setEmptySelectionEnabled:



isHorizontalScrollerEnabled
(BOOL)isHorizontalScrollerEnabled

Returns YES if the NXBrowser uses a horizontal Scroller (instead of Buttons), and if that Scroller is enabled, NO otherwise.

See also:  setHorizontalScrollerEnabled:, setHorizontalScrollButtonsEnabled:



isMultipleSelectionEnabled
(BOOL)isMultipleSelectionEnabled

Returns YES if more than one leaf node can be selected, NO otherwise.

See also:  setMultipleSelectionEnabled:



isLoaded
(BOOL)isLoaded

Returns YES if any of the NXBrowser's columns are loaded.

See also:  loadColumnZero, setPath:



isTitled
(BOOL)isTitled

Returns YES if the NXBrowser's columns are displayed with titles above them; NO otherwise.

See also:  getTitleFromPreviousColumn:, setTitled:



keyDown:
keyDown:(NXEvent *)theEvent

Handles arrow key events.  This method is invoked when the NXBrowser or one of its subviews is the first responder.  If the NXBrowser has been set to accept arrow keys, and the key represented in theEvent is an arrow key, this method scrolls through the NXBrowser in the direction indicated.

See also:  acceptArrowKeys:andSendActionMessages:, acceptsFirstResponder, mouseDown:



lastColumn
(int)lastColumn

Returns the index of the last loaded column in the NXBrowser.

See also:  lastVisibleColumn



lastVisibleColumn
(int)lastVisibleColumn

Returns the index of the rightmost visible column.  This may be less than the value returned by lastColumn if the NXBrowser has been scrolled left.

See also:  firstVisibleColumn, lastColumn



loadColumnZero
loadColumnZero

Loads and displays data in column 0 of the NXBrowser, unloading any columns to the right that were previously loaded.  Invoke this method to force the NXBrowser to be loaded; for example, after initializing the NXBrowser, when changing delegates, or when changing the data set managed by the delegate.  You may want to override this method if you subclass NXBrowser.

See also:  setPath:, reloadColumn:



matrixInColumn:
matrixInColumn:(int)column

Returns the Matrix found in column number column.  Returns nil if column number column isn't loaded in the NXBrowser.



maxVisibleColumns
(int)maxVisibleColumns

Returns the maximum number of visible columns allowed.  No matter how many loaded columns the NXBrowser contains, or how large the NXBrowser is made (for example, by resizing its window), it will never display more than this number of columns.  If the number of loaded columns can exceed the value returned by this method, the NXBrowser must display left and right scroll buttons.

See also:  setMaxVisibleColumns:, numVisibleColumns, setHorizontalScrollerEnabled:, setHorizontalScrollButtonsEnabled:



minColumnWidth
(int)minColumnWidth

Returns the minimum width of a column in PostScript points (rounded to the nearest integer).  No column will be smaller than the returned value unless the NXBrowser itself is smaller than that.  The default setting is 100 points.

See also:  setMinColumnWidth:



mouseDown:
mouseDown:(NXEvent *)theEvent

Handles a mouse down in the NXBrowser's left or right scroll buttons.  Override this method if you need to to any special event processing.  Returns self.

See also:  keyDown:



numVisibleColumns
(int)numVisibleColumns

Returns the number of columns which can be visible at the same time in the NXBrowser (that is, the current width, in columns, of the NXBrowser).  This may be less than the value returned by maxVisibleColumns if the window containing the NXBrowser has been resized.

See also:  setMaxVisibleColumns:, maxVisibleColumns:



reflectScroll:
reflectScroll:clipView

This method updates scroll bars in the column containing clipView.  Scroll bars are enabled if a column contains more data than can be displayed at once and disabled if the column can display all data.  You should never need to invoke this method, but you may want to override it.  Returns self.

See also:  useScrollBars:



reloadColumn:
reloadColumn:(int)column

Reloads the previously loaded column number column by sending a message to the delegate to update the Cells in its Matrix, then reselecting the previously selected Cell if it's still in the Matrix.  You should never send this message for a column that hasn't been loaded (you can check for this with the lastColumn method).  Redraws the column and returns self.

See also:  lastColumn



reuseColumns:
reuseColumns:(BOOL)flag

Sets whether the NXBrowser saves a column's Matrix and ClipView or ScrollView when the column is removed, and whether it then reuses these subviews when the column is reloaded.  If flag is YES, the NXBrowser reuses columns for somewhat faster display of columns as they are reloaded.  If flag is NO, the NXBrowser frees columns as they're unloaded, reducing average memory use.  Returns self.



scrollColumnsLeftBy:
scrollColumnsLeftBy:(int)shiftAmount

Scrolls the columns in the NXBrowser left by shiftAmount columns, making higher numbered columns visible.  If shiftAmount exceeds the number of loaded columns to the right of the first visible column, then the columns scroll left to make the last loaded column visible.  Redraws and returns self.

See also:  scrollColumnsRightBy:



scrollColumnsRightBy:
scrollColumnsRightBy:(int)shiftAmount

Scrolls the columns in the NXBrowser right by shiftAmount columns, making lower numbered columns visible.  If shiftAmount exceeds the number of columns to the left of the first visible column, then the columns scroll right until column 0 is visible. Redraws and returns self.

See also:  scrollColumnsLeftBy:



scrollColumnToVisible:
scrollColumnToVisible:(int)column

Scrolls the NXBrowser to make column number column visible.  If there's no column in the NXBrowser, this method scrolls to the right as far as possible.  Redraws and returns self.



scrollUpOrDown:
scrollUpOrDown:sender

Scrolls a column up or down.  Your code shouldn't send this message; NXBrowser receives it from a column's scroll buttons. You may want to override it to perform additional updating.  Returns self.



scrollViaScroller:
scrollViaScroller:sender

Scrolls the NXBrowser's columns left or right based on the position of the Scroller sending the message.  Your code shouldn't send this message, but you may want to override it.  Returns self.



selectAll:
selectAll:sender

Selects all entries in the last column loaded in the NXBrowser if multiple selection is allowed.  Returns self.

See also:  setMultipleSelectionEnabled:



selectedCell
selectedCell

If there is a selection, returns the last selected Cell.  "Last," in this context, means furthest to the right and lowest in the column.

See also:  getSelectedCells:



selectedColumn
(int)selectedColumn

Returns the column number of the rightmost column containing a selected Cell.  This won't be the last column if the selected Cell isn't a leaf.  Returns 1 if no column in the NXBrowser contains a selected Cell.

See also:  lastColumn



sendAction
sendAction

Sends the NXBrowser's action to its target and returns self.

See also:  sendAction:to: (Control)



separateColumns:
separateColumns:(BOOL)flag

If flag is YES, sets NXBrowser so that columns have bezeled borders separating them; if NO, the borders are removed.  When titles are set to display (by setTitled:), columns are automatically separated.  Redraws the NXBrowser and returns self.

See also:  setTitled:



setAction:
setAction:(SEL)aSelector

Sets the action of the NXBrowser.  aSelector is the selector for the message sent to the NXBrowser's target when a mouse-down event occurs in a column of the NXBrowser.  Returns self.

See also:  action, setDoubleAction:, setTarget:, doClick



setBranchSelectionEnabled:
setBranchSelectionEnabled:(BOOL)flag

Sets whether the user can select multiple branch and leaf node entries.  If flag is YES and multiple selection is enabled (by setMultipleSelectionEnabled:), then multiple branch and leaf node entries can be selected.  By default, a user can choose only multiple leaf node entries when multiple entry selection is enabled.  Returns self.

This method replaces the allowBranchSel: method from NEXTSTEP Release 2.

See also:  isBranchSelectionEnabled, setMultipleSelectionEnabled:



setCellClass:
setCellClass:classId

Sets the class of Cell used when adding Cells to a Matrix in a column of the NXBrowser.  classId must be the value returned when sending the class message to NXBrowserCell or a subclass of NXBrowserCell.  Since an NXBrowser always has its Matrices copy prototype Cells, this method simply makes a prototype, sends it an init message, and records that prototype. Returns self.

You shouldn't use Control's class method setCellClass: with an NXBrowser.

See also:  setCellPrototype:



setCellPrototype:
setCellPrototype:aCell

Sets aCell as the Cell prototype copied when adding Cells to the Matrices in the columns of NXBrowser.  aCell must be an instance of NXBrowserCell or a subclass of NXBrowserCell.  Each Matrix gets its own copy of aCell to use as a prototype, and will free that copy when the Matrix is freed.  Returns the previous Cell prototype if aCell is an instance of either NXBrowserCell or a subclass of NXBrowserCell; otherwise, returns nil.

You shouldn't use Control's class method setCellClass: with an NXBrowser.

See also:  cellPrototype, setCellClass:



setDelegate:
setDelegate:anObject

Sets the delegate of the NXBrowser to anObject and returns self.  If anObject is of a class that implements the methods indicated in the class description for a normal, lazy, or very lazy delegate, it's set as the NXBrowser's delegate; otherwise, the delegate is set to nil.  Returns self.

See also:  delegate



setDoubleAction:
setDoubleAction:(SEL)aSelector

Sets the double-click action of the NXBrowser.  aSelector is the selector for the action message sent to the target when a double-click occurs in one of the columns of the NXBrowser.  Returns self.

See also:  doubleAction, setAction:, setTarget:, doDoubleClick:



setEmptySelectionEnabled:
setEmptySelectionEnabled:(BOOL)flag

If flag is YES, the NXBrowser can display without any Cells selected; if flag is NO, then there must always be at least one Cell selected.  By default, the setting is NO, and NXBrowser selects the first item in the first column.  Returns self.

See also:  isEmptySelectionEnabled, setMultipleSelectionEnabled:



setEnabled:
setEnabled:(BOOL)flag

Enables the NXBrowser when flag is YES; disables it when flag is NO.  Returns self.

See also:  isEnabled (Control)



setHorizontalScrollButtonsEnabled:
setHorizontalScrollButtonsEnabled:(BOOL)flag

If flag is YES, sets the NXBrowser to use left and right scroll buttons.  Generally, you should allow your NXBrowser to scroll horizontally unless your data is nonhierarchical, thus limited to a single column, or restricted so that the NXBrowser will always display enough columns for all data. Returns self.

This method, along with setHorizontalScrollerEnabled:, replaces the hideLeftAndRightScrollButtons: method from NEXTSTEP Release 2.  In order to completely remove horizontal scrolling Controls, invoke both methods with arguments of NO.

See also:  setHorizontalScrollerEnabled:, areHorizontalScrollButtonsEnabled



setHorizontalScrollerEnabled:
setHorizontalScrollerEnabled:(BOOL)flag

If flag is YES, sets the NXBrowser to use a horizontal Scroller.  Generally, you should allow your NXBrowser to scroll horizontally unless your data is nonhierarchical, thus limited to a single column, or restricted so that the NXBrowser will always display enough columns for all data. Returns self.

This method, along with setHorizontalScrollButtonsEnabled:, replaces the hideLeftAndRightScrollButtons: method from NEXTSTEP Release 2.  In order to completely remove horizontal scrolling Controls, invoke both methods with arguments of NO.

See also:  setHorizontalScrollButtonsEnabled:, areHorizontalScrollButtonsEnabled



setLastColumn:
setLastColumn:(int)column

Makes column number column the last column loaded and displayed by the NXBrowser.  Removes any columns to the right of column from the NXBrowser, and scrolls columns in the NXBrowser to make the new last column visible if it wasn't previously. If column number column isn't already loaded, this method does nothing.  Returns self.

See also:  lastColumn



setMatrixClass:
setMatrixClass:classId

Sets the class of Matrix used when adding new columns to the NXBrowser.  classId must be the value returned by sending the class message to Matrix or a subclass of Matrix; otherwise this method retains the previous setting for the NXBrowser's Matrix class.  NXBrowser initializes the Matrix of a new column with the initFrame:mode:prototype: numRows:numCols: method. Returns self.



setMaxVisibleColumns:
setMaxVisibleColumns:(int)columnCount

Sets the maximum number of columns that may be displayed by the NXBrowser.  Returns self.

To set the number of columns displayed in a new NXBrowser, first send it a setMinColumnWidth: message with a small argument (1, for example) to ensure that the desired number of columns will fit in the NXBrowser's frame.  Then invoke this method to set the number of columns you want your NXBrowser to display.  The minimum column width may then be reestablished to its desired value.

See also:  maxVisibleColumns, setMinColumnWidth:



setMinColumnWidth:
setMinColumnWidth:(int)columnWidth

Sets the minimum width for each column to columnWidth.  If the new minimum width is different from the previous one, this method also redisplays the NXBrowser with columns set to the new width.  columnWidth is measured in PostScript points rounded to the nearest integer.  The default setting is 100.  Returns self.

See also:  minColumnWidth



setMultipleSelectionEnabled:
setMultipleSelectionEnabled:(BOOL)flag

Sets whether the user can select multiple entries in a column.  If flag is YES, the user can choose any number of leaf entries in a column (or leaf and branch entries in a column if enabled by setBranchSelectionEnabled:).  By default, the user can choose just one entry in a column at a time.  Returns self.

This method replaces the allowMultiSel: method from NEXTSTEP Release 2.

See also:  isMultipleSelectionEnabled, setBranchSelectionEnabled:



setPath:
setPath:(const char *)aPath

Parses aPath--a string consisting of one or more substrings separated by the path separator--and selects column entries in the NXBrowser that match the substrings.  If the first character in aPath is the path separator, this method begins searching for matches in column 0; otherwise, it begins searching in the last column loaded.  If no column is loaded, this method loads column 0 and begins the search there.  While parsing the current substring, it tries to locate a matching entry in the search column.  If it finds an exact match, this method selects that entry and moves to the next column (loading the column if necessary) to search for the next substring.

If this method finds a valid path (one in which each substring is matched by an entry in the corresponding column), it returns self.  If it doesn't find an exact match on a substring, it stops parsing aPath and returns nil; however, column entries that it has already selected remain selected.

Your code should never try to set a path or select items by sending Cell selection messages to the Matrices in the NXBrowser's columns.  This bypasses every mechanism that allows the NXBrowser to update its display and load columns and Cells properly.

See also:  getPath:toColumn, pathSeparator, setPathSeparator, browser:selectCell:inColumn: (delegate method)



setPathSeparator:
setPathSeparator:(unsigned short)charCode

Sets the character used as the path separator; the default is the slash character ("/").  Returns self.

See also:  getPath:toColumn, setPath:



setTarget:
setTarget:anObject

Sets the target of the NXBrowser.  This is the object that will receive action messages when the user clicks or double-clicks on items in the NXBrowser.  Returns self.

See also:  target, setAction:, setDoubleAction:



setTitle:ofColumn:
setTitle:(const char *)aString ofColumn:(int)column

Sets the title of column number column in the NXBrowser to aString.  If column column isn't loaded, this method does nothing. Returns self.

See also:  getTitleFromPreviousColumn:, setTitled:, browser:TitleOfColumn: (delegate method)



setTitled:
setTitled:(BOOL)flag

If flag is YES, columns display titles and are separated by bezeled borders.  Returns self.

See also:  getTitleFromPreviousColumn:, setTitle:ofColumn:, browser:TitleOfColumn: (delegate method)



sizeTo::
sizeTo:(NXCoord)width :(NXCoord)height

Resizes the NXBrowser to the new width and height.  Usually sent by the NXBrowser's Window.  Override this method if your subclass of NXBrowser need to do any special updating when resized.  Returns self.



sizeToFit
sizeToFit

Resizes the NXBrowser to contain all the columns and Controls displayed in it.  Returns self.



target
target

Returns the target for the NXBrowser's action message.  This object receives action messages when the user clicks or double-clicks on items in the NXBrowser.

See also:  setTarget:, action, setAction:, doubleAction, setDoubleAction:



tile
tile

Arranges the various subviews of NXBrowser--Scrollers, columns, titles, and so on--without redrawing.  Your code shouldn't send this message.  It's invoked any time the appearance of the NXBrowser changes; for example, when scroll Buttons or scroll bars are set, a column is added, and so on.  Override this method if your code changes the appearance of the NXBrowser (for example, if you draw your own titles above columns).  Returns self.



titleHeight
(NXCoord)titleHeight

Returns the height of titles drawn above the columns of the NXBrowser.  Override this method if you display your own titles above the NXBrowser's columns.



titleOfColumn:
(const char *)titleOfColumn:(int)column

Returns a pointer to the title string displayed above column number column.  If that column isn't loaded in the NXBrowser, returns NULL.



updateScroller
updateScroller

Updates the horizontal Scroller to reflect the position of the visible columns of the NXBrowser.  Returns self.



useScrollBars:
useScrollBars:(BOOL)flag

Sets NXBrowser to use scroll bars for its columns based on flag.  If flag is YES and the NXBrowser was previously set to use only scroll Buttons, this method causes the scroll Buttons to display at the base of the scroll bars.  By default, NXBrowser uses scroll bars without Buttons; send useScrollButtons: to also have Buttons at the bottoms of the Scrollers.  This method redraws the NXBrowser.  Returns self.

See also:  useScrollButtons:



useScrollButtons:
useScrollButtons:(BOOL)flag

Sets the NXBrowser to use scroll Buttons for its columns based on flag.  If flag is YES and the NXBrowser was previously set to use scroll bars, this method causes scroll buttons to display at the base of the scroll bars; otherwise the Buttons are displayed underneath each column.  To get only Buttons under the columns, send useScrollBars: with NO as the argument, then send this message with YES as the argument.  This method redraws the NXBrowser.  Returns self.

See also:  useScrollBars:



validateVisibleColumns
validateVisibleColumns

Validates the columns visible in the NXBrowser by invoking the delegate method browser:columnIsValid: for all visible columns.  Use this method to confirm that the entries displayed in each visible column are valid before redrawing.

See also:  browser:columnIsValid: (delegate method)



Methods Implemented by the Delegate

browser:columnIsValid:
(BOOL)browser:sender columnIsValid:(int)column

This method is invoked by NXBrowser's validateVisibleColumns method to determine whether the contents currently loaded in column number column need to be updated.  This is useful for data sets that may change over time, such as files in a file system, or lists from a shared set of data that others can change.  Returns YES if the contents are valid; NO otherwise.

See also:  browser:selectCell:inColumn: (delegate method)



browserDidScroll:
browserDidScroll:sender

Notifies the delegate when the browser has finished scrolling horizontally.  This can be useful for aligning other user interface items with the columns of the browser (for example, an icon path or a series of pop-up lists).  Returns self.

See also:  browserDidScroll: (delegate method)



browser:fillMatrix:inColumn:
(int)browser:sender
fillMatrix:matrix
inColumn:(int)column

Invoked by the NXBrowser to query a normal or lazy browser for the contents of column.  This method should create NXBrowserCells by sending addRow or insertRowAt: messages to matrix.  The NXBrowser will resize them to fit in the Matrix--you can't control the size of an NXBrowserCell.  Returns the number of items in column.

A normal delegate should create each NXBrowserCell and send them the messages setLoaded: and setLeaf:, and setEnabled: if necessary.  A lazy delegate marks Cells as loaded only when they are about to be displayed; however, it may create and partially fill in information (such as the title), saving only the time-consuming operations for an actual request to load an individual Cell.

If you implement this method, don't implement the delegate method browser:getNumRowsInColumn:.

See also:  browser:loadCell:atRow:inColumn: (delegate method)



browser:getNumRowsInColumn:
(int)browser:sender getNumRowsInColumn:(int)column

Implemented by very lazy delegates, this method is invoked by the NXBrowser to ask the delegate for the number of rows in column number column.  This method allows the NXBrowser to resize its scroll bar for a column without loading all the Cells in that column.  Returns the number of rows in column.

If you implement this method, don't implement the delegate method browser:fillMatrix:inColumn:.

See also:  browser:loadCell:atRow:inColumn: (delegate method)



browser:loadCell:atRow:inColumn:
browser:sender
loadCell:cell
atRow:(int)row
inColumn:(int)column

Implemented by lazy and very lazy delegates.  This method loads the entry in the provided NXBrowserCell cell for the specified row and column in the NXBrowser.  The NXBrowser will resize the Cell to fit in the Matrix--you can't control the size of an NXBrowserCell.  Returns self.

A lazy delegate should send a setLoaded: message to cell at load time; it can send setLeaf:, setStringValue: and setEnabled: messages at load time or later.  A very lazy delegate should send setLoaded:, setLeaf:, and setStringValue: messages to cell at load time, and setEnabled: when needed.

See also:  browser:fillMatrix:inColumn: (delegate method), browser:getNumRowsInColumn: (delegate method)



browser:selectCell:inColumn:
(BOOL)browser:sender
selectCell:(const char *)entry
inColumn:(int)column

Asks NXBrowser's delegate to validate and select an entry in column number column.  This method should load the Cell corresponding to entry if necessary, send it setLoaded: and setLeaf: messages as needed to indicate its state, and send the column's Matrix a selectCell: or selectCellAt:: message to select that Cell.  If there is no Cell corresponding to entry, the selection should be cleared by sending selectCellAt:: to the Matrix with 1 and 1 as the arguments.  Returns YES if the method successfully selects the Cell corresponding to entry in column; NO otherwise.

If the delegate doesn't implement this method, the NXBrowser searches for entries by scanning through the entire list of Cells in the column.  This will always work properly for NXBrowsers that browse static data.  However, if the data can change while the NXBrowser is in use (for example, if a new file is created or deleted), this method allows the delegate to find that new data and add it to the column, or to find out that it no longer exists (or that its status has changed) and mark it as disabled or remove the Cell altogether with Matrix's removeRowAt:andFree: method (be sure to free the Cell).

See also:  browser:columnIsValid: (delegate method), matrixInColumn:, selectCell: (Matrix), selectCellAt:: (Matrix), removeRowAt:andFree: (Matrix)



browser:titleOfColumn:
(const char *)browser:sender titleOfColumn:(int)column

Invoked by NXBrowser to get the title for column from the delegate.  This method is invoked if the delegate implements it, but only when the NXBrowser is titled and has received a getTitleFromPreviousColumn: message with NO as the argument.  By default, the NXBrowser makes each column title the string value of the selected Cell in the previous column.  Returns the string representing the title belonging above column.

See also:  getTitleFromPreviousColumn:, setTitle:ofColumn:, setTitled:



browserWillScroll:
browserWillScroll:sender

This method notifies the delegate when the browser is about to scroll horizontally.  This can be useful for hiding other user interface items to prepare for aligning them with the columns of the browser (for example, an icon path or a series of pop-up lists).  Returns self.

See also:  browserDidScroll: (delegate method)