Added full docs for the class NSOutlineView.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@17920 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,7 @@
+2003-10-18  16:48  Gregory John Casamento <greg_casamento@yahoo.com>
+
+	* Source/NSOutlineView.m: Added full gsdoc documentation for this class.
+	
 2003-10-17  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/GSServicesManager.m: Make mapping of service names to

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 <NSDraggingInfo>)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 <NSDraggingInfo>)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
 

Source/NSOutlineView.m

@@ -1,6 +1,10 @@
 /** <title>NSOutlineView</title>
 
-   <abstract>The outline class.</abstract>
+   <abstract>
+   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.
+   </abstract>
    
    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:);