SSListView

Inherits from:

NSView : NSResponder : NSObject

Class Description

The list view presents long lists of data in snaking columns that will scroll horizontally, if necessary. The user can select individual data items by clicking, or by using the complete set of navigation keys. When the user clicks on an item, an action message can be sent, double-clicking will lead to an alternative message. Double-clicking an item can also open it for editing, if required.

As shown above, it is possible to use a custom cell instead of the default NSTextFieldCell. Odd columns can be highlighted. Vertical intercell spacing can be included, optionally displaying grid lines. Individual cells can be highlighted or show a background color, with the help of delegate methods. Formatting is partially supported.

Method Types

Setting the data source

- setDataSource:

- dataSource

Loading data

- reloadData

Target-action behavior

- setTarget:

- target

- setAction:

- action

- setDoubleAction:

- doubleAction

Configuring behavior

- setAllowsSelection:

- allowsSelection

Setting display attributes

- setIntercellSpacing:

- intercellSpacing

- setRowHeight:

- rowHeight

- setColumnWidth:

- columnWidth

- setHighlightOddColumns:

- highlightOddColumns

- setBackgroundColor:

- backgroundColor

Setting grid attributes

- setDrawsGrid:

- drawsGrid

- setGridColor:

- gridColor

Selecting cells

- indexOfSelectedCell

- selectCellAtIndex:

Getting the dimensions of the table

- numberOfColumns

- numberOfRows

Editing cells

- setIsEditable:

- isEditable

- editCellAtIndex:

Layout support

- frameOfCellAtPoint:

- frameOfCellAtIndex:

- cellIndexAtPoint:

- columnAtIndex:

- rectOfColumn:

Scrolling

- scrollColumnToVisible:

- scrollToSelection

Text delegate methods

- textDidChange:

- textShouldEndEditing:

- textDidEndEditing:

Assigning a delegate

- setDelegate:

- delegate
Formatting text

- alignment

- setAlignment:

- formatter

- setFormatter:

Methods implemented by the data source

- numberOfObjectsInListView:

- listView:objectValueAtIndex:

- listView:setObjectValue:atIndex:

Methods implemented by the delegate

listView:willDisplayCell:atIndex:

listView:shouldEditCell:atIndex:

listView:shouldSelectCell:atIndex:

listView:textShouldEndEditing:

listView:didFailToFormatString:errorDescription:

listView:didFailToValidatePartialString:errorDescription:

listView:textView:doCommandBySelector:

Notifications

SSListViewSelectionIsChangingNotification

SSListViewSelectionDidChangeNotification

SSListViewTextDidEndEditingNotification

Instance Methods

action

- (SEL)action

Returns the action-message selector of the receiver's cell.

See Also: - doubleAction, - target, - setAction:

alignment

- (NSTextAlignment)alignment

Returns the alignment of text in the receiver: NSLeftTextAlignment, NSRightTextAlignment, NSCenterTextAlignment, NSJustifiedTextAlignment, or NSNaturalTextAlignment.

See Also: - setAlignment:

allowsSelection

- (BOOL)allowsSelection

Returns YES if the receiver allows the user to select a cell, NO otherwise. The default is NO.

You can select a cell programmatically even if this setting is NO.

See Also: - setAllowsSelection:

cellIndexAtPoint:

- (int)cellIndexAtPoint:(NSPoint)aPoint

Returns the index of the cell aPoint lies in, or -1 if aPoint lies below the visible area of cells.

columnAtIndex:

- (int)columnAtIndex:(int)index

Returns the number of the column containing the cell at index.

See Also: - rectOfColumn:

dataSource

- (id)dataSource

Returns the object that provides the data displayed by the receiver. See the SSListViewDataSource informal protocol specification for more information.

See Also: - setDataSource:

delegate

- (id)delegate

Returns the receiver's delegate.

See Also: - setDelegate:

formatter

- (id)formatter

Returns the formatter object (a kind of NSFormatter) associated with the receiver.

See Also: - setFormatter:

doubleAction

- (SEL)doubleAction

Returns the message sent to the target when the user double-clicks an uneditable cell.

See Also: - action, - target, - setDoubleAction:

drawsGrid

- (BOOL)drawsGrid

Returns YES if the receiver draws grid lines between cells, NO if it doesn't. The default is NO.

See Also: - gridColor, - setDrawsGrid:

editCellAtIndex:

- (void)editCellAtIndex:(int)index

Begins editing of the receiver's text in the cell at index, selecting the full text. If the cell is not editable and selected, this method does nothing. The listview's delegate can implement listView:shouldEditCell:atIndex: to disallow editing of specific cells.

This method scrolls the receiver so that the cell is visible, sets up the field editor, and sends selectWithFrame:inView:editor:delegate:start:length: to the field editor's NSCell object with the receiver as the text delegate.

See Also: - isEditable, - setIsEditable:

frameOfCellAtIndex:

- (NSRect)frameOfCellAtIndex:(int)index

Returns the frame rectangle of the cell at index. This method does not check if index is outside the scope of the data source.

frameOfCellAtPoint:

- (NSRect)frameOfCellAtPoint:(NSPoint)aPoint

Returns the frame rectangle of the cell at aPoint. Returns NSZeroRect if aPoint lies below the area of valid cells of the receiver.

gridColor

- (NSColor *)gridColor

Returns the color used to draw grid lines. The default color is light gray.

See Also: - drawsGrid, - setGridColor:

indexOfSelectedCell

- (int)indexOfSelectedCell

Returns the index of the last cell selected, or -1 if no cell is selected.

See Also: - selectCellAtIndex:

intercellSpacing

- (NSSize)intercellSpacing

Returns the horizontal and vertical spacing between cells. The vertical spacing is not used.

See Also: - setDrawsGrid:, - setIntercellSpacing:

isEditable

- (BOOL)isEditable

Returns YES if the selected cell is editable, NO if it doesn't. The default is NO.

See Also: - setIsEditable:, - editCellAtIndex:

numberOfColumns

- (int)numberOfColumns

Returns the minimum number of columns required for number of objects returned by numberOfObjectsInListView.

See Also: - numberOfRows

numberOfRows

- (int)numberOfRows

Returns the maximum number of rows that will fit within the height of the receiver's frame.

See Also: - numberOfColumns

rectOfColumn:

- (NSRect)rectOfColumn:(int)column

Returns the rectangle enclosing all the cells in column.

See Also: - columnAtIndex:

rowHeight

- (float)rowHeight

Returns the height of each row in the receiver. The default row height is that of the cellSize (NSCell).

See Also: - setRowHeight:

scrollColumnToVisible:

- (void)scrollColumnToVisible:(int)column

Scrolls the receiver horizontally in an enclosing NSClipView so the column specified by column is visible.

See Also: - scrollToSelection

scrollToSelection

- (void)scrollToSelection

Scrolls the receiver horizontally so the selected cell is visible.

See Also: - scrollColumnToVisible:

selectCellAtIndex:

- (void)selectCellAtIndex:(int)index

Selects the cell at index after deselecting the previously selected cell if allowsSelection returns YES. If index is outside the scope of the data source, no selection takes place.

Posts a SSListViewSelectionDidChangeNotification to the default notification center if the selection does in fact change. This method doesn't check with the delegate before changing the selection. If the user is editing a cell, editing is simply forced to end and the selection is changed.

See Also: - indexOfSelectedCell

setAction:

- (void)setAction:(SEL)aSelector

Sets the receiver's action method to aSelector. If aSelector is nil, then no action messages will be sent from the receiver.

See Also: - setDoubleAction:, - setTarget:, - action

setAlignment:

- (void)setAlignment:(NSTextAlignment)mode

Sets the alignment of text in the receiver. mode is one of five constants: NSLeftTextAlignment, NSRightTextAlignment, NSCenterTextAlignment, NSJustifiedTextAlignment, NSNaturalTextAlignment (the default alignment for the text). This method sets the alignment of the cell.

See Also: - alignment

setAllowsSelection:

- (void)setAllowsSelection:(BOOL)flag

Controls whether the receiver allows cells to be selected. If flag is YES selection is allowed; if flag is NO the user cannot select a cell. The default setting is NO.

You can select a cell programmatically, however, even if user selection is disallowed. If flag is NO, indexOfSelectedCell will return -1.

See Also: - allowsSelection

setDataSource:

- (void)setDataSource:(id)aSource

Sets the receiver's data source to aSource and invokes reloadData. aSource should implement the appropriate methods of the SSListViewDataSource informal protocol.

See Also: - dataSource

setDelegate:

- (void)setDelegate:(id)anObject

Sets the receiver's delegate to anObject.

See Also: - delegate

setDoubleAction:

- (void)setDoubleAction:(SEL)aSelector

Sets the message sent to the target when the user double-clicks an uneditable cell to aSelector. If the double-clicked cell is editable, this message isn't sent and the cell is edited instead.

See Also: - setAction:, - setTarget:, - doubleAction

setDrawsGrid:

- (void)setDrawsGrid:(BOOL)flag

Controls whether the receiver draws vertical grid lines between columns. If flag is YES it does; if flag is NO it doesn't. The default is NO.

If flag is YES, the width of intercellSpacing is set to 1, unless it is already non-zero.

See Also: - setGridColor:, - drawsGrid

setFormatter:

- (void)setFormatter:(NSFormatter *)newFormatter

Sets the formatter object used to format the textual representation of the receiver's object value and to validate cell input and convert it to that object value using getObjectValue:forString:errorDescription:. newFormatter is attached to the cell, and to the editing cell, if isEditable returns YES.

See Also: - formatter

setGridColor:

- (void)setGridColor:(NSColor *)color

Sets the color used to draw grid lines to color. The default color is light gray.

See Also: - setDrawsGrid:, - gridColor

setIntercellSpacing:

- (void)setIntercellSpacing:(NSSize)aSize

Sets the width and height between cells to those in aSize and redisplays the receiver. The horizontal spacing is subtracted from the cell width. The vertical spacing is not used.

See Also: - intercellSpacing

setIsEditable:

- (void)setIsEditable:(BOOL)flag

Controls whether the selected cell is editable. If flag is YES it is editable; if flag is NO it isn't editable. The default is NO.

If flag is YES, an NSTextFieldCell is created for the windows field editor, if required; if flag is NO, the editing cell is released, if applicable.

See Also: - isEditable, - editCellAtIndex:

setRowHeight:

- (void)setRowHeight:(float)height

Sets the height for rows to height and invokes reloadData.

See Also: - rowHeight

setTarget:

- (void)setTarget:(id)anObject

Sets the target object for the action message of the receiver's cell.

See Also: - setDoubleAction:, - setAction:, - target

target

- (id)target

Returns the target object of the receiver's cell.

See Also: - doubleAction, - action, - setTarget:

textDidChange:

- (void)textDidChange:(NSNotification *)aNotification

Not yet implemented.

textDidEndEditing:

- (void)textDidEndEditing:(NSNotification *)aNotification

Ends editing of the selected cell and selects another cell for editing if possible according to the character that ended editing (Tab, Backtab). aNotification is a SSListViewTextDidEndEditingNotification.

See Also: - textShouldEndEditing:

textShouldEndEditing:

- (BOOL)textShouldEndEditing:(NSText *)textObject

Validates the cell being edited, using getObjectValue:forString:errorDescription: and the delegate method listView:didFailToFormatString:errorDescription:. Finally, it queries the delegate using listView:textShouldEndEditing:, returning the delegate's response if it responds to that method. If it doesn't, it returns YES if the cell's new value is valid and NO if it isn't.

See Also: - textDidEndEditing:

Methods Implemented by the Data Source

Informal protocol:

NSObject (SSListViewDataSource)

numberOfObjectsInListView:

- (int)numberOfObjectsInListView:(SSListView *)listView

Returns the number of records managed for listView by the data source object. An SSListView uses this method to determine how many rows and columns it should create and display. This method is required.

listView:objectValueAtIndex:

- (id)listView:(SSListView *)listView objectValueAtIndex:(int)index

Returns an object value for the record in listView at index. This method is required.

listView:setObjectValue:atIndex:

- (void)listView:(SSListView *)listView setObjectValue:(id)anObject atIndex:(int)index

Sets an object value for the record in listView at index. The implementation of this method is optional.

Methods Implemented by the Delegate

Informal protocol:

NSObject (SSListViewDelegate)

listView:didFailToFormatString:errorDescription:

- (BOOL)listView:(SSListView *)listView didFailToFormatString:(NSString *)string errorDescription:(NSString *)error

Invoked when the formatter for listview's cell cannot convert an NSString to an underlying object. error is a localized user-presentable NSString that explains why the conversion failed. Evaluate the error or query the user and return YES if string should be accepted as-is, or NO if string should be rejected.

See Also: getObjectValue:forString:errorDescription: (NSFormatter)

listView:didFailToValidatePartialString:errorDescription:

- (void)listView:(SSListView *)listView didFailToValidatePartialString:(NSString *)string errorDescription:(NSString *)error

Not implemented.

listView:shouldEditCell:atIndex:

- (BOOL)listView:(SSListView *)listView shouldEditCell:(id)aCell atIndex:(int)index

Returns YES to permit listView to edit the cell at index, NO to deny permission. The delegate can implement this method to disallow editing of specific cells.

listView:shouldSelectCell:atIndex:

- (BOOL)listView:(SSListView *)listView shouldSelectCell:(id)aCell atIndex:(int)index

Returns YES to permit listView to select the cell at index, NO to deny permission. The delegate can implement this method to disallow selection of particular cells.

listView:textShouldEndEditing:

- (BOOL)listView:(SSListView *)listView textShouldEndEditing:(NSText *)fieldEditor

Sent directly by listView to the delegate when the insertion point tries to leave a cell of the listview that has been edited. Return YES if the view's fieldEditor should be allowed to end its edit session, NO otherwise.

listView:textView:doCommandBySelector:

- (BOOL)listView:(SSListView *)listView textView:(NSTextView *)textView doCommandBySelector:(SEL)command

Invoked when users press keys with predefined bindings in view's cell or selected cell, as communicated to the view by the cell's field editor (textView). The delegate returns YES if it handles the key binding, and NO otherwise. These bindings are usually implemented as methods (command) defined in NSResponder; examples of such key bindings are arrow keys (for directional movement) and the Escape key (for name completion). By implementing this method, the delegate can override the default implementation of command and supply its own behavior.

listView:willDisplayCell:atIndex:

- (void)tableView:(SSListView *)listView willDisplayCell:(id)aCell atIndex:(int)index

Informs the delegate that listView will display the cell at index using aCell. The delegate can modify the display attributes of aCell to alter the appearance of the cell. Because aCell is reused for every entry in listView, the delegate must set the display attributes both when drawing special cells and when drawing normal cells.

Notifications

SSListView posts the following notifications to interested observers and its delegate.

SSListViewSelectionDidChangeNotification

Posted after the SSListView's selection changes. The notification object is the SSListView whose selection changed. The userInfo dictionary is nil.

SSListViewSelectionIsChangingNotification

Posted as the SSListView's selection changes (while the mouse is still down). The notification object is the SSListView whose selection is changing. The userInfo dictionary is nil.

SSListViewTextDidEndEditingNotification

This notification object contains a notification object and a userInfo dictionary. The notification object is the SSListView posting the notification. (The field editor of the edited cell originally sends a textDidEndEditing message to the listview, which passes it on in this form to its delegate.) The userInfo dictionary contains the key @"NSFieldEditor" and the value is the edited cell's field editor.