12. Browsers

A browser is a special type of matrix control, useful for the display of hierachial or tree-like data. They use vertical lists of cells, in which some cells can be selected so that they display the "branches" of a tree in the adjacent pane. In this way, a user can easily navigate a hierachy, such as a filesystem which has many directories and sub-directories.

In fact, the textual data in a browser can be accessed using path like string components, such as ‘/path/to/leaf’ or ‘/usr/local/lib’. A good example of it’s use in filesystems is GWorkspace, GNUstep’s file manager application.(15).

We introduce the concept of leaves and branches. A leaf is a simple browser cell that only display’s text; it does not open a new browser pane with sub-cells when it is selected. A branch both display text, and when selected, it fills the pane to the right with a list of leaves and/or branches that represent a group of cells logically below this one. A branch shows an arrow to indicate that it can be selected to display sub-cells. It is useful when dealing with tree-structures such as that modelled in Computer Sciencei courses.

Each pane in the browser view is actually a one-column matrix (an NSMatrix object) which can be returned.

Like many other controls, browsers define their own cell class, known as NSBrowserCell. It provides methods that are used to implement the functionality described above. Browsers use a simple delegate to decide how to display your hierachial data, which can be passive or active (see below).

12.1 Browser Cells

As mentioned above, NSBrowserCell is used to implement the cells’s placed in a browser. As a class it is quite simple, and warrants little attention.

It responds to all the methods in NSCell, such as setText: and the set value methods. Additionally, we can find out if it is a leaf using the -isLeaf method, and set whether or not it is a leaf using the -setLeaf: method.

You can set whether the browser cell is selected using the -set method, and reset it using the -reset method. A cell shows that it is selected (or "set") when it is highlighted.

12.2 Browser Methods

Browsers provide a number of methods used for customising their behaviour, setting their data and getting information about their state.

The path to the currently selected item (as described above) can be found using the -path method. You can find out the path leading upto a column with the -pathToColumn: method. An easy way of setting the current path is the -setPath: operator.

You can customize the appearance of a browser and it’s columns in various ways. Use -setSeparatesColumns: to have each column drawn in a separate pane. -setTakesTitleFromPreviousColumn: has it take the title displayed in the current column from the cell selected in the previous column, while -setTitle:ofColumn: allows you to set a column title directly. -setTitled: changes whether column titles are displayed at all.

The types of operations permitted by the user can be changed as well. -setAllowsMultipleSelection: can be used to allow multiple selection, while -setAllowsEmptySelection: can be used to permit nothing to be selected. Use -setAllowsBranchSelection: to allow multiple branches to be selected when in multiple selection mode.

The first and last column visible in the browser is found via the -firstVisibleColumn and -lastVisibleColumn respectively.

12.3 Browser Delegate

The delegate for a browser is used to gather it’s data. It can be optionally passive or active, the difference being that active delegates instantiate the browser cell’s themselves, whilst passive delegates leave this to NSBrowser. As a result, you can only implement one or the other subset of methods in NSBrowserDelegate informal protocol..

A passive delegate must implement the -browser:numberOfRowsInColumn:, returning the number of rows to appear in the specified column number. On the other hand, active delegates must implement -browser:createRowsForColumn:inMatrix: and create the cells for that column proactively. You can only implement one of these methods; not both.

All browser delegates can implement -browser:willDisplayCell:atRow:column:, a method called by the browser object before a particular cell is displayed so that the delegate can set up its properties. This method is a must for passive delegates. Another method that should be implemented is -browser:selectRow:inColumn:, as it is the delegate’s responsibility to select cells (often by calling -set on the corresponding NSBrowserCell object). This method returns whether or not the cell was selected.

You can optionally implement a number of other delegate methods if you wish. -browser:titleOfColumn: is called to get the title for a certain column, returned as a string, before the column is drawn.

Keeping track of when the browser scrolls can be accomplished by implementing the -browserWillScroll: and/or the -browserDidScroll: methods. You can also specify to the browser whether or not columns are "valid" by implementing the -browser:isColumnValid: method. This is called by the browser in response to its -validateVisibleColumn: method, which checks whether a column is invalid and needs redrawing.

This document was generated by Adam Fedor on December 24, 2013 using texi2html 1.82.