diff --git a/ChangeLog b/ChangeLog index 61f272522..1479fbc1b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2003-10-18 16:48 Gregory John Casamento + + * Source/NSOutlineView.m: Added full gsdoc documentation for this class. + 2003-10-17 Richard Frith-Macdonald * Source/GSServicesManager.m: Make mapping of service names to diff --git a/Headers/AppKit/NSOutlineView.h b/Headers/AppKit/NSOutlineView.h index d0e734830..f3938c7f8 100644 --- a/Headers/AppKit/NSOutlineView.h +++ b/Headers/AppKit/NSOutlineView.h @@ -76,49 +76,79 @@ @end /* interface of NSOutlineView */ -/* +/** * Informal protocol NSOutlineViewDataSource */ @interface NSObject (NSOutlineViewDataSource) +/** + * Returns whether or not the outline view should accept a drop + * into the indicated item. + */ - (BOOL)outlineView: (NSOutlineView *)outlineView acceptDrop: (id )info item: (id)item childIndex: (int)index; - -// required method +/** + * Implementation of this method is required. Returns the child at + * the specified index for the given item. + */ - (id)outlineView: (NSOutlineView *)outlineView child: (int)index ofItem: (id)item; - -// required method +/** + * This is a required method. Returns whether or not the outline view + * item specified is expandable or not. + */ - (BOOL)outlineView: (NSOutlineView *)outlineView isItemExpandable: (id)item; +/** + * Returns the item for the given persistent object. + */ - (id)outlineView: (NSOutlineView *)outlineView itemForPersistentObject:(id)object; -// required method +/* + * This is a required method. Returns the number of children of + * the given item. + */ - (int)outlineView: (NSOutlineView *)outlineView numberOfChildrenOfItem: (id)item; -// required method +/** + * This is a required method. Returns the object corresponding to the + * item representing it in the outline view. + */ - (id)outlineView: (NSOutlineView *)outlineView objectValueForTableColumn:(NSTableColumn *)tableColumn byItem:(id)item; +/** + * Returns the persistent object for the item specified. + */ - (id)outlineView: (NSOutlineView *)outlineView persistentObjectForItem: (id)item; +/** + * Sets the object value of the given item in the given table column to the object provided. + */ - (void)outlineView: (NSOutlineView *)outlineView setObjectValue: (id)object forTableColumn: (NSTableColumn *)tableColumn byItem: (id)item; +/** + * Used by the Drag and Drop system. Returns the drap operations which was performed on the + * given outline view. + */ - (NSDragOperation)outlineView: (NSOutlineView*)outlineView validateDrop: (id )info proposedItem: (id)item proposedChildIndex: (int)index; +/** + * Causes the outline view to write the specified items to the pastboard. + */ - (BOOL)outlineView: (NSOutlineView *)outlineView writeItems: (NSArray*)items toPasteboard: (NSPasteboard*)pboard; @@ -148,35 +178,89 @@ APPKIT_EXPORT NSString *NSOutlineViewItemWillCollapseNotification; */ @interface NSObject (NSOutlineViewDelegate) // notification methods +/** + * Called after the column has moved. + */ - (void) outlineViewColumnDidMove: (NSNotification *)aNotification; +/** + * Called after the view column is resized. + */ - (void) outlineViewColumnDidResize: (NSNotification *)aNotification; +/** + * Called after the item has collapsed. + */ - (void) outlineViewItemDidCollapse: (NSNotification *)aNotification; +/** + * Called after the item has expanded + */ - (void) outlineViewItemDidExpand: (NSNotification *)aNotification; +/** + * Called before the item has collapsed. + */ - (void) outlineViewItemWillCollapse: (NSNotification *)aNotification; +/** + * Called before the item is expanded. + */ - (void) outlineViewItemWillExpand: (NSNotification *)aNotification; +/** + * Called when the selection has changed. + */ - (void) outlineViewSelectionDidChange: (NSNotification *)aNotification; +/** + * Called when the selection is about to change. + */ - (void) outlineViewSelectionIsChanging: (NSNotification *)aNotification; // delegate methods +/** + * Returns whether or not the specified item should be allowed to collapse. + */ - (BOOL) outlineView: (NSOutlineView *)outlineView shouldCollapseItem: (id)item; +/** + * Returns whether or not the given table column should be allowed to be edited. + */ - (BOOL) outlineView: (NSOutlineView *)outlineView shouldEditTableColumn: (NSTableColumn *)tableColumn item: (id)item; +/** + * Returns whether or not the specified item should be expanded. + */ - (BOOL) outlineView: (NSOutlineView *)outlineView shouldExpandItem: (id)item; +/** + * Returns YES or NO depending on if the given item is selectable. If YES, the item is selected, + * otherwise the outline view will reject the selection. + */ - (BOOL) outlineView: (NSOutlineView *)outlineView shouldSelectItem: (id)item; +/** + * Returns YES or NO depending on if the given table column is selectable according + * to the delegate. If NO is returned the outline view will not allow the selection, if YES + * it will allow the selection. + */ - (BOOL) outlineView: (NSOutlineView *)outlineView shouldSelectTableColumn: (NSTableColumn *)tableColumn; +/** + * Called when the given cell is about to be displayed. This method is + * useful for making last second modifications to what will be shown. + */ - (void) outlineView: (NSOutlineView *)outlineView willDisplayCell: (id)cell forTableColumn: (NSTableColumn *)tableColumn item: (id)item; +/** + * Called when the given cell in the outline column is about to be displayed. This method is + * useful for making last second modifications to what will be shown. + */ - (void) outlineView: (NSOutlineView *)outlineView willDisplayOutlineCell: (id)cell forTableColumn: (NSTableColumn *)tableColumn item: (id)item; +/** + * Called before the selection is modified. This method should return YES if + * the selection is allowed and NO, if not. + */ - (BOOL) selectionShouldChangeInOutlineView: (NSOutlineView *)outlineView; @end diff --git a/Source/NSOutlineView.m b/Source/NSOutlineView.m index 46d05733d..7d9fbff3e 100644 --- a/Source/NSOutlineView.m +++ b/Source/NSOutlineView.m @@ -1,6 +1,10 @@ /** NSOutlineView - The outline class. + + This class is a subclass of NSTableView which provides the user with a way + to display tree structured data in an outline format. It is particularly useful for show + hierarchical data such as a class inheritance tree or any other set of relationships. + Copyright (C) 2001 Free Software Foundation, Inc. @@ -116,6 +120,12 @@ static NSImage *unexpandable = nil; } // Instance methods + +/** + * Initalizes the outline view with the given frame. Invokes + * the superclass method initWithFrame: as well to initialize the object. + * + */ - (id)initWithFrame: (NSRect)frame { [super initWithFrame: frame]; @@ -161,11 +171,19 @@ static NSImage *unexpandable = nil; [super dealloc]; } +/** + * Causes the outline column, the column containing the expand/collapse gadget, to + * resize based on the amount of space needed by widest content. + */ - (BOOL)autoResizesOutlineColumn { return _autoResizesOutlineColumn; } +/** + * Causes the outline column, the column containing the expand/collapse gadget, to + * resize based on the amount of space needed by widest content. + */ - (BOOL)autosaveExpandedItems { return _autosaveExpandedItems; @@ -303,11 +321,20 @@ static NSImage *unexpandable = nil; } } +/** + * Collapses the given item only. This is the equivalent of calling + * [NSOutlineView-collapseItem:collapseChildren:] with NO. + */ - (void)collapseItem: (id)item { [self collapseItem: item collapseChildren: NO]; } +/** + * Collapses the specified item. If collapseChildren is set to YES, then all of the + * expandable children of this item all also collapsed in a recursive fashion (i.e. + * all children, grandchildren and etc). + */ - (void)collapseItem: (id)item collapseChildren: (BOOL)collapseChildren { const SEL shouldSelector = @selector(outlineView:shouldCollapseItem:); @@ -363,11 +390,20 @@ static NSImage *unexpandable = nil; } } +/** + * Expands the given item only. This is the equivalent of calling + * [NSOutlineView-expandItem:expandChildren:] with NO. + */ - (void)expandItem: (id)item { [self expandItem: item expandChildren: NO]; } +/** + * Expands the specified item. If expandChildren is set to YES, then all of the + * expandable children of this item all also expanded in a recursive fashion (i.e. + * all children, grandchildren and etc). + */ - (void)expandItem:(id)item expandChildren:(BOOL)expandChildren { const SEL shouldExpandSelector = @selector(outlineView:shouldExpandItem:); @@ -430,21 +466,35 @@ static NSImage *unexpandable = nil; [self noteNumberOfRowsChanged]; } +/** + * Returns whether or not the indentation marker or "knob" is indented + * along with the content inside the cell. + */ - (BOOL)indentationMarkerFollowsCell { return _indentationMarkerFollowsCell; } +/** + * Returns the amount of indentation, in points, for each level + * of the tree represented by the outline view. + */ - (float)indentationPerLevel { return _indentationPerLevel; } +/** + * Returns YES, if the item is able to be expanded, NO otherwise. + */ - (BOOL)isExpandable: (id)item { return [_dataSource outlineView: self isItemExpandable: item]; } +/** + * Returns YES if the item is expanded or open, NO otherwise. + */ - (BOOL)isItemExpanded: (id)item { if(item == nil) @@ -454,11 +504,17 @@ static NSImage *unexpandable = nil; return([_expandedItems containsObject: item]); } +/** + * Returns the item at a given row. + */ - (id)itemAtRow: (int)row { return [_items objectAtIndex: row]; } +/** + * Returns the level for a given item. + */ - (int)levelForItem: (id)item { if(item != nil) @@ -470,11 +526,17 @@ static NSImage *unexpandable = nil; return -1; } +/** + * Returns the level for the given row. + */ - (int)levelForRow: (int)row { return [self levelForItem: [self itemAtRow: row]]; } +/** + * Returns the outline table column. + */ - (NSTableColumn *)outlineTableColumn { return _outlineTableColumn; @@ -512,11 +574,20 @@ static NSImage *unexpandable = nil; return hasChildren; } +/** + * Causes an item to be reloaded. This is the equivalent of calling + * [NSOutlineView-reloadItem:reloadChildren:] with reloadChildren set to NO. + */ - (void)reloadItem: (id)item { [self reloadItem: item reloadChildren: NO]; } +/** + * Causes an item and all of it's children to be reloaded if reloadChildren is + * set to YES, if it's set to NO, then only the item itself is refreshed from the + * datasource. + */ - (void)reloadItem: (id)item reloadChildren: (BOOL)reloadChildren { id parent = nil; @@ -555,16 +626,29 @@ static NSImage *unexpandable = nil; } } +/** + * Returns the corresponding row in the outline view for the given item. + */ - (int)rowForItem: (id)item { return [_items indexOfObject: item]; } +/** + * When set to YES this causes the outline column, the column containing + * the expand/collapse gadget, to resize based on the amount of space + * needed by widest content. + */ - (void)setAutoresizesOutlineColumn: (BOOL)resize { _autoResizesOutlineColumn = resize; } +/** + * When set to YES, the outline view will save the state of all expanded or + * collapsed items in the view to the users defaults for the application the + * outline view is running in. + */ - (void)setAutosaveExpandedItems: (BOOL)flag { if(flag == _autosaveExpandedItems) @@ -602,26 +686,44 @@ static NSImage *unexpandable = nil; } } +/** + * If set to YES, the indentation marker will follow the content at each level. + * Otherwise, the indentation marker will remain at the left most position of + * the view regardless of how many levels in the content is indented. + */ - (void)setIndentationMarkerFollowsCell: (BOOL)followsCell { _indentationMarkerFollowsCell = followsCell; } +/** + * Sets the amount, in points, that each level is to be indented by. + */ - (void)setIndentationPerLevel: (float)newIndentLevel { _indentationPerLevel = newIndentLevel; } +/** + * Sets the outline table column in which to place the indentation marker. + */ - (void)setOutlineTableColumn: (NSTableColumn *)outlineTableColumn { _outlineTableColumn = outlineTableColumn; } +/** + * Returns YES, by default. Subclasses should override this method if + * a different behaviour is required. + */ - (BOOL)shouldCollapseAutoExpandedItemsForDeposited: (BOOL)deposited { return YES; } +/** + * This method returns the number of rows changed in the data source. + */ - (void) noteNumberOfRowsChanged { _numberOfRows = [_items count]; @@ -708,6 +810,9 @@ static NSImage *unexpandable = nil; } } +/** + * Sets the data source for this outline view. + */ - (void) setDataSource: (id)anObject { #define CHECK_REQUIRED_METHOD(selector_name) \ @@ -730,6 +835,9 @@ static NSImage *unexpandable = nil; [self reloadData]; } +/** + * Forces a from scratch reload of all data in the outline view. + */ - (void) reloadData { // release the old array @@ -764,6 +872,9 @@ static NSImage *unexpandable = nil; [super reloadData]; } +/** + * Sets the delegate of the outline view. + */ - (void) setDelegate: (id)anObject { const SEL sel = @selector(outlineView:willDisplayCell:forTableColumn:item:);