MOExtendedOutlineView


Abstract

MOExtendedOutlineView adds a number of new features to the standard NSOutlineView.

Discussion

MOExtendedOutlineView adds a number of new features to the standard NSOutlineView. There are a few simple additional features such as being able to alter the way editing ends, setting a minimum row height, a convenience method for changing the font of the whole outline, and support for per-cell context menus.

MOExtendedOutlineView also adds a number of new, optional, dataSource and delegate methods. It defines dataSource API for user-initiated item creation and deletion with accompanying action methods to wire controls to. It defines delegate API to allow the delegate to easily handle return or delete key presses in the outline. It adds delegate API to provide, replace or alter a outline's context menu. And, there's dataSource API that unifies handling of pasteboard contents for drag&drop, copy/paste, and Services.



Methods

setUsesRowBasedEditing:
Sets whether editing is row-based.
usesRowBasedEditing
Returns whether editing is row-based.
textDidEndEditing:
Overridden to support row-based editing.
setIsDragSource:
Does the outline act as a drag source.
isDragSource
Does the outline act as a drag source.
setFont:
Sets the font of all text-based columns.
setMinRowHeight:
Sets a minimum row height for the outline.
minRowHeight
Returns the minimum row height for the outline.
setRowHeight:
Overridden to support -setMinRowHeight:.
keyDown:
Overridden to support the return/backspace delegate API.
delete:
Action method for user-initiated deletion of selected items.
createNewItem:
Action method for user-initiated creation of a new item.
copy:
Action method for the Copy command.
cut:
Action method for the Cut command.
paste:
Action method for the Paste command.
validateUserInterfaceItem:
User command validation.
validRequestorForSendType:returnType:
Services and Paste validation.
readSelectionFromPasteboard:
Services support method.
writeSelectionToPasteboard:types:
Services support method.
menuForEvent:
Override to support per-cell context menus.

copy:

Action method for the Copy command.
- ( IBAction ) copy:
        (id ) sender;

Action method for the Copy command. This causes the selected items to be written to the general pasteboard by sending the dataSource the -outlineView:writeItems:toPasteboard: message, if it implements it. If the dataSource does not implement that method or it returns NO, this beeps.

Parameter Descriptions
sender
The sender of the action.

createNewItem:

Action method for user-initiated creation of a new item.
- ( IBAction ) createNewItem:
        (id ) sender;

Action method for user-initiated creation of a new item. This can be wired to Add buttons or other UI elements. It causes a new item to be inserted directly under (as a sibling of) the last currently selected item (or at the end if there is no selection), by sending the dataSource the -outlineView:createNewItemAtChildIndex:ofItem: message, if it implements it. If the dataSource does not implement that method or it returns NO, this beeps. If the dataSource method does not alter the selection, then the outline will select the new row (as the only selected row) after a successful deletion.

Parameter Descriptions
sender
The sender of the action.

cut:

Action method for the Cut command.
- ( IBAction ) cut:
        (id ) sender;

Action method for the Cut command. This causes the selected items to be written to the general pasteboard by sending the dataSource the -outlineView:writeItems:toPasteboard: message and then deletes them by sending it the -outlineView:deleteItems:, if it implements both. If the dataSource does not implement either method or one returns NO, this beeps. (If the writing of items to the pasteboard returns NO, the deletion is not attempted.) If the dataSource methods do not alter the selection, then the outline will deselect all rows after a successful cut.

Parameter Descriptions
sender
The sender of the action.

delete:

Action method for user-initiated deletion of selected items.
- ( IBAction ) delete:
        (id ) sender;

Action method for user-initiated deletion of selected items. This is the action of the Delete or Clear menu item and can also be wired to delete buttons or other UI elements. It causes the selected items to be deleted by sending the dataSource the -outlineView:deleteItems: message, if it implements it. If the dataSource does not implement that method or it returns NO, this beeps. If the dataSource method does not alter the selection, then the outline will deselect all rows after a successful deletion.

Parameter Descriptions
sender
The sender of the action.

isDragSource

Does the outline act as a drag source.
- ( BOOL ) isDragSource;

Returns whether the outline allows rows to be dragged. Since MOExtendedOutlineView extends the use of the -outlineView:writeItems:toPasteboard: to include Copy/Paste and Services support, the dataSource may implement that method without wanting to allow drags. This method makes it possible to support the Copy menu command without supporting dragging. The default is YES which means dragging is allowed as long as the dataSource implements -outlineView:writeItems:toPasteboard:.

method result
Whether the outline allows rows to be dragged.

keyDown:

Overridden to support the return/backspace delegate API.
- ( void ) keyDown:
        (NSEvent *) event;

Overridden to support the -outlineView:handleReturnKeyEvent: and -outlineView:handleDeleteKeyEvent: delegate API. This looks for those characters, and if the delegate implements the appropriate method, calls it. For other keys, or if the delegate does not implement the right method, or if the delegate's implementation returns NO, this calls super.

Parameter Descriptions
event
The keyDown event.

menuForEvent:

Override to support per-cell context menus.
- ( NSMenu *) menuForEvent:
        (NSEvent *) event;

Cocoa sends this method when it needs a context menu. This override figures out what item and column the mouse event was over. If it was over a real cell, first the row for that cell is selected if it is not already selected, then the column's NSTableColumn is sent a -dataCellForRow: message and the resulting cell is asked for its menu. If the cell has no menu or if the click was not over a cell, then super is called (which will return any menu set on the outline with the -setMenu: or wired to the menu outlet of the outline in IB). Finally, if the delegate implements -outlineView:willReturnMenu:forTableColumn:item:event:, that message is sent (passing the menu we found, or nil if no menu was found.) The delegate may create and return a new menu, return nil to block the menu being shown or modify the provided menu and return it.

Parameter Descriptions
event
The event that caused the view to require its context menu (usually a right-mouseDown: or Control-mouseDown:).
method result
The menu that should be used.

minRowHeight

Returns the minimum row height for the outline.
- ( float ) minRowHeight;

Returns the minimum row height for the outline. Calls to setRowHeight: with heights smaller than the minimum will cause the row height to be set to the minimum instead.

method result
The minimum row height.

paste:

Action method for the Paste command.
- ( IBAction ) paste:
        (id ) sender;

Action method for the Paste command. This causes new items to be read from the pasteboard and inserted directly under (as siblings of) the last currently selected item (or at the end if there is no selection), by sending the dataSource the -outlineView:readItemsFromPasteboard:item:childIndex:pasteboardSourceType: message, if it implements it. If the dataSource does not implement that method or it returns NO, this beeps. If the dataSource method does not alter the selection, then the outline will attempt to select the new rows (as the only selected rows). To do this, the outline starts at the insertion row and selects a number of rows equal to the difference between the outline's number of rows before the paste and the number after the paste.

Parameter Descriptions
sender
The sender of the action.

readSelectionFromPasteboard:

Services support method.
- ( BOOL ) readSelectionFromPasteboard:
        (NSPasteboard *) pboard;

This method is sent by the Services mechanism to get the outline to read the results of a service. This causes new items to be read from the pasteboard and inserted directly under (as siblings of) the last currently selected item (or at the end if there is no selection), by sending the dataSource the -outlineView:readItemsFromPasteboard:item:childIndex:pasteboardSourceType: message, if it implements it. If the dataSource does not implement that method or it returns NO, this does nothing. If the dataSource method does not alter the selection, then the outline will attempt to select the new rows (as the only selected rows). To do this, the outline starts at the insertion row and selects a number of rows equal to the difference between the outline's number of rows before the new rows are read and the number after the new rows are read. Note that for Services to be enabled, someone must call NSApplication's -registerServicesMenuSendTypes:returnTypes: with arrays of the supported send and return types to make the application globally aware that these types are supported.

Parameter Descriptions
pboard
The pasteboard to read from.
method result
YES if the read succeeded, NO if not.

setFont:

Sets the font of all text-based columns.
- ( void ) setFont:
        (NSFont *) font;

This is a convenience method that does two things. First it goes through all the outline's NSTableColumns and sets the font in each one's -dataCell. Second, it adjusts the row-height of the outline to something appropriate for the font.

If the font setting will ultimately be based on a user preference, and there is other content than text in your outlines, it is probably a good idea to set a minimum row height for the outline that will accomodate the non-text content. (Don't forget the disclosure triangles...)

Parameter Descriptions
font
The font.

setIsDragSource:

Does the outline act as a drag source.
- ( void ) setIsDragSource:
        (BOOL ) flag;

Sets whether the outline allows rows to be dragged. Since MOExtendedOutlineView extends the use of the -outlineView:writeItems:toPasteboard: to include Copy/Paste and Services support, the dataSource may implement that method without wanting to allow drags. This method makes it possible to support the Copy menu command without supporting dragging. The default is YES which means dragging is allowed as long as the dataSource implements -outlineView:writeItems:toPasteboard:.

Parameter Descriptions
flag
Whether the outline allows rows to be dragged.

setMinRowHeight:

Sets a minimum row height for the outline.
- ( void ) setMinRowHeight:
        (float ) height;

Sets a minimum row height for the outline. If you set this then calls to setRowHeight: with heights smaller than the minimum will cause the row height to be set to the minimum instead.

This method can be useful if the control over the row-height is somehow in the user's hands andd you want to set a lower limit. For example, if the font of the outline will be a user preference but there is also non-textual content that requires a minimum row height.

Parameter Descriptions
height
The minimum row height.

setRowHeight:

Overridden to support -setMinRowHeight:.
- ( void ) setRowHeight:
        (float ) rowHeight;

Overridden to support -setMinRowHeight:. This sets rowHeight to the minimum if it was less, then it calls super.

Parameter Descriptions
rowHeight
The desired row height.

setUsesRowBasedEditing:

Sets whether editing is row-based.
- ( void ) setUsesRowBasedEditing:
        (BOOL ) flag;

Sets whether editing is row-based. NO by default, in which case the outline behaves like NSOutlineView. If this is turned on then it effects what happens as textual editing of a cell's value ends. Hitting return or Enter will end editing instead of starting editing in the next row. Tabbing and backtabbing will take you horizontally through the cells in a row but tabbing off the end of a row or shift-tabbing off the beginning will cause editing to end instead of changing rows.

This behavior can often be desirable in situations where editing the value of a row is not the most common operation and it is rarely desirable to edit multiple values in multiple rows all at once.

Parameter Descriptions
flag
Whether editing is row-based.

textDidEndEditing:

Overridden to support row-based editing.
- ( void ) textDidEndEditing:
        (NSNotification *) notification;

This method is overridden to support row-based editing. It always calls super but sometimes it replaces the notification with a different one that alters the NSTextMovement key in the userInfo of the original notification.

Parameter Descriptions
notification
The notification.

usesRowBasedEditing

Returns whether editing is row-based.
- ( BOOL ) usesRowBasedEditing;

Returns whether editing is row-based. NO by default, in which case the outline behaves like NSOutlineView. If this is turned on then it effects what happens as textual editing of a cell's value ends. Hitting return or Enter will end editing instead of starting editing in the next row. Tabbing and backtabbing will take you horizontally through the cells in a row but tabbing off the end of a row or shift-tabbing off the beginning will cause editing to end instead of changing rows.

This behavior can often be desirable in situations where editing the value of a row is not the most common operation and it is rarely desirable to edit multiple values in multiple rows all at once.

method result
Whether editing is row-based.

validRequestorForSendType:returnType:

Services and Paste validation.
- ( id ) validRequestorForSendType:
        (NSString *) sendType returnType:
        (NSString *) returnType;

This method is sent by the Services mechanism to find out whether a particular service is applicable. MOExtendedOutlineView implements this method to send the -outlineView:validRequestorForSendType:returnType: dataSource method, if it is implemented. If the delegate does not implement it this method calls super. Note that for Services to be enabled, someone must call NSApplication's -registerServicesMenuSendTypes:returnTypes: with arrays of the supported send and return types to make the application globally aware that these types are supported.

Parameter Descriptions
sendType
The pasteboard type that will be sent to the service.
returnType
The pasteboard type that will come from the service.
method result
a "requestor" to handle the service.

validateUserInterfaceItem:

User command validation.
- ( BOOL ) validateUserInterfaceItem:
        (id ) anItem;

This method implements validation for the delete:, createNewItem:, copy:, cut:, and paste: actions. Validation is based on whether the dataSource implements the appropriate methods and also on whether the command currently makes sense (eg is there a selection for delete:, copy:, and cut:, and does the pasteboard contain a type that can be read for paste:).

The validation for paste: will send the -outlineView:validRequestorForSendType:returnType: dataSource method, if it is implemented. The send type will be nil and the return type will be a type that is currently on the pasteboard. If the dataSource returns a requestor for any of the types on the pasteboard, then Paste will be enabled.

For any other commands, this returns YES.

Parameter Descriptions
anItem
The user interface item being validated.
method result
YES if the item should be enabled, NO if not.

writeSelectionToPasteboard:types:

Services support method.
- ( BOOL ) writeSelectionToPasteboard:
        (NSPasteboard *) pboard types:
        (NSArray *) types;

This method is sent by the Services mechanism to get the outline to provide input to a service. This causes selected items to be written to the pasteboard, by sending the dataSource the -outlineView:writeItems:toPasteboard: message, if it implements it. If the dataSource does not implement that method or it returns NO, this does nothing. Note that for Services to be enabled, someone must call NSApplication's -registerServicesMenuSendTypes:returnTypes: with arrays of the supported send and return types to make the application globally aware that these types are supported.

Parameter Descriptions
pboard
The pasteboard to write to.
method result
YES if the write succeeded, NO if not.

(Last Updated 3/20/2005)