SRome documentation tidyupsi

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

ChangeLog

@@ -13,6 +13,9 @@
 	without having to build binaries. Also add flag for macros template.
 	* Source/GNUmakefile: Removed documentation building rules.
 	* Documentation/GNUmakefile: Use DocMakefile
+	* Source/NSWindow.m: Slight documentation update/addition.
+	* Source/NSView.m: ditto.
+	* Source/NSToolbar.m: ditto.
 
 2002-10-11  Adam Fedor  <fedor@gnu.org>
 

Headers/gnustep/gui/NSToolbar.h

@@ -71,29 +71,29 @@ APPKIT_EXPORT NSString *NSToolbarWillAddItemNotification;
 }
 
 // Instance methods
-- (BOOL)allowsUserCustomization;
+- (BOOL) allowsUserCustomization;
-- (BOOL)autosavesConfiguration;
+- (BOOL) autosavesConfiguration;
-- (NSDictionary *)configurationDictionary;
+- (NSDictionary*) configurationDictionary;
-- (BOOL)customizationPaletteIsRunning;
+- (BOOL) customizationPaletteIsRunning;
-- (id)delegate;
+- (id) delegate;
-- (NSToolbarDisplayMode)displayMode;
+- (NSToolbarDisplayMode) displayMode;
-- (NSString *)identifier;
+- (NSString*) identifier;
-- (id)initWithIdentifier: (NSString *)indentifier;
+- (id) initWithIdentifier: (NSString*)identifier;
-- (void)insertItemWithItemIdentifier: (NSString *)itemIdentifier
+- (void) insertItemWithItemIdentifier: (NSString*)itemIdentifier
-                             atIndex: (int)index;
+			      atIndex: (int)index;
-- (BOOL)isVisible;
+- (BOOL) isVisible;
-- (NSArray *)items;
+- (NSArray*) items;
-- (void)removeItemAtIndex: (int)index;
+- (void) removeItemAtIndex: (int)index;
-- (void)runCustomizationPalette: (id)sender;
+- (void) runCustomizationPalette: (id)sender;
 
-- (void)setAllowsUserCustomization: (BOOL)flag;
+- (void) setAllowsUserCustomization: (BOOL)flag;
-- (void)setAutosavesConfiguration: (BOOL)flag;
+- (void) setAutosavesConfiguration: (BOOL)flag;
-- (void)setConfigurationFromDictionary: (NSDictionary *)configDict;
+- (void) setConfigurationFromDictionary: (NSDictionary*)configDict;
-- (void)setDelegate: (id)delegate;
+- (void) setDelegate: (id)delegate;
-- (void)setDisplayMode: (NSToolbarDisplayMode)displayMode;
+- (void) setDisplayMode: (NSToolbarDisplayMode)displayMode;
-- (void)setVisible: (BOOL)shown;
+- (void) setVisible: (BOOL)shown;
-- (void)validateVisibleItems;
+- (void) validateVisibleItems;
-- (NSArray *)visibleItems;
+- (NSArray*) visibleItems;
 @end /* interface of NSToolbar */
 
 /*
@@ -101,18 +101,18 @@ APPKIT_EXPORT NSString *NSToolbarWillAddItemNotification;
  */
 @interface NSObject (NSToolbarDelegate)
 // notification methods
-- (void) toolbarDidRemoveItem: (NSNotification *)aNotification;
+- (void) toolbarDidRemoveItem: (NSNotification*)aNotification;
-- (void) toolbarWillAddItem: (NSNotification *)aNotification;
+- (void) toolbarWillAddItem: (NSNotification*)aNotification;
 
 // delegate methods
 // required method
-- (NSToolbarItem *)toolbar: (NSToolbar *)toolbar
+- (NSToolbarItem*)toolbar: (NSToolbar*)toolbar
-     itemForItemIdentifier: (NSString *)itemIdentifier
+    itemForItemIdentifier: (NSString*)itemIdentifier
  willBeInsertedIntoToolbar: (BOOL)flag;
 // required method
-- (NSArray *)toolbarAllowedItemIdentifiers: (NSToolbar *)toolbar;
+- (NSArray*) toolbarAllowedItemIdentifiers: (NSToolbar*)toolbar;
 // required method
-- (NSArray *)toolbarDefaultItemIdentifiers: (NSToolbar *)toolbar;
+- (NSArray*) toolbarDefaultItemIdentifiers: (NSToolbar*)toolbar;
 @end
 
 #endif /* _GNUstep_H_NSToolbar */

Source/NSToolbar.m

@@ -46,22 +46,22 @@ static const int current_version = 1;
 {
   NSToolbar *_toolbar;
 }
-- (void)setToolbar: (NSToolbar *)toolbar;
+- (void) setToolbar: (NSToolbar *)toolbar;
-- (NSToolbar *)toolbar;
+- (NSToolbar *) toolbar;
 @end
 
 @implementation GSToolbarView
-- (void)setToolbar: (NSToolbar *)toolbar
+- (void) setToolbar: (NSToolbar *)toolbar
 {
   ASSIGN(_toolbar, toolbar);
 }
 
-- (NSToolbar *)toolbar
+- (NSToolbar *) toolbar
 {
   return _toolbar;
 }
 
-- (void)drawRect: (NSRect)aRect
+- (void) drawRect: (NSRect)aRect
 {
   [super drawRect: aRect];
 }
@@ -74,7 +74,7 @@ static const int current_version = 1;
 @end
 
 @implementation GSToolbarButton
-- (id)initWithItem: (NSToolbarItem *)item
+- (id) initWithItem: (NSToolbarItem *)item
 {
   [super init];
   ASSIGN(_item, item);
@@ -87,7 +87,7 @@ static const int current_version = 1;
   [super dealloc];
 }
 
-- (void)drawRect: (NSRect)aRect
+- (void) drawRect: (NSRect)aRect
 {
   // set the image and draw using the super class...
   [super drawRect: aRect];
@@ -118,37 +118,37 @@ static const int current_version = 1;
 }
 
 // Instance methods
-- (BOOL)allowsUserCustomization
+- (BOOL) allowsUserCustomization
 {
   return _allowsUserCustomization;
 }
 
-- (BOOL)autosavesConfiguration
+- (BOOL) autosavesConfiguration
 {
   return _autosavesConfiguration;
 }
 
-- (NSDictionary *)configurationDictionary
+- (NSDictionary *) configurationDictionary
 {
   return _configurationDictionary;
 }
 
-- (BOOL)customizationPaletteIsRunning
+- (BOOL) customizationPaletteIsRunning
 {
   return _customizationPaletteIsRunning;
 }
 
-- (id)delegate
+- (id) delegate
 {
   return _delegate;
 }
 
-- (NSToolbarDisplayMode)displayMode
+- (NSToolbarDisplayMode) displayMode
 {
   return _displayMode;
 }
 
-- (NSString *)identifier
+- (NSString *) identifier
 {
   return _identifier;
 }
@@ -179,7 +179,7 @@ static const int current_version = 1;
 }
 
 
-- (id)initWithIdentifier: (NSString *)identifier
+- (id) initWithIdentifier: (NSString*)identifier
 {
   [super init];
   ASSIGN(_identifier, identifier);
@@ -203,40 +203,40 @@ static const int current_version = 1;
 }
 
 
-- (void)insertItemWithItemIdentifier: (NSString *)itemIdentifier
+- (void) insertItemWithItemIdentifier: (NSString *)itemIdentifier
                              atIndex: (int)index
 {
 }
 
-- (BOOL)isVisible
+- (BOOL) isVisible
 {
   return _visible;
 }
 
-- (NSArray *)items
+- (NSArray *) items
 {
   return _items;
 }
 
-- (void)removeItemAtIndex: (int)index
+- (void) removeItemAtIndex: (int)index
 {
 }
 
-- (void)runCustomizationPalette: (id)sender
+- (void) runCustomizationPalette: (id)sender
 {
 }
 
-- (void)setAllowsUserCustomization: (BOOL)flag
+- (void) setAllowsUserCustomization: (BOOL)flag
 {
   _allowsUserCustomization = flag;
 }
 
-- (void)setAutosavesConfiguration: (BOOL)flag
+- (void) setAutosavesConfiguration: (BOOL)flag
 {
   _autosavesConfiguration = flag;
 }
 
-- (void)setConfigurationFromDictionary: (NSDictionary *)configDict
+- (void) setConfigurationFromDictionary: (NSDictionary *)configDict
 {
   if(!_configurationDictionary)
     {
@@ -245,10 +245,16 @@ static const int current_version = 1;
   ASSIGN(_configurationDictionary, configDict);
 }
 
-- (void) setDelegate: (id)anObject
+/**
+ * Sets the receivers delgate ... this is the object which will receive
+ * -toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:
+ * -toolbarAllowedItemIdentifiers: and -toolbarDefaultItemIdentifiers:
+ * messages.
+ */
+- (void) setDelegate: (id)delegate
 { 
 #define CHECK_REQUIRED_METHOD(selector_name) \
-  if (![anObject respondsToSelector: @selector(selector_name)]) \
+  if (![delegate respondsToSelector: @selector(selector_name)]) \
     [NSException raise: NSInternalInconsistencyException \
                  format: @"delegate does not respond to %@",@#selector_name]
 
@@ -258,7 +264,7 @@ static const int current_version = 1;
 
   if (_delegate)
     [nc removeObserver: _delegate name: nil object: self];
-  _delegate = anObject;
+  _delegate = delegate;
 
 
 #define SET_DELEGATE_NOTIFICATION(notif_name) \
@@ -271,21 +277,21 @@ static const int current_version = 1;
   SET_DELEGATE_NOTIFICATION(WillAddItem);
 }
 
-- (void)setDisplayMode: (NSToolbarDisplayMode)displayMode
+- (void) setDisplayMode: (NSToolbarDisplayMode)displayMode
 {
   _displayMode = displayMode;
 }
 
-- (void)setVisible: (BOOL)shown
+- (void) setVisible: (BOOL)shown
 {
   _visible = shown;
 }
 
-- (void)validateVisibleItems
+- (void) validateVisibleItems
 {
 }
 
-- (NSArray *)visibleItems
+- (NSArray *) visibleItems
 {
   return nil;
 }

Source/NSView.m

@@ -466,7 +466,7 @@ GSSetDragTypes(NSView* obj, NSArray *types)
 
 /**
   <p> Removes the receiver from its superviews list of subviews, by
-  invoking the superviews [-removeSubview:] method, and marks the
+  invoking the superviews -removeSubview: method, and marks the
   rectangle that the reciever occupied in the superview as needing
   redisplay.  </p>
 
@@ -486,12 +486,13 @@ GSSetDragTypes(NSView* obj, NSArray *types)
   <p> Removes aSubview from the receivers list of subviews and from
   the responder chain.  </p>
 
-  <p> Also invokes [aView -viewWillMoveToWindow: nil] to handle
+  <p> Also invokes -viewWillMoveToWindow: on aView with a nil argument,
+  to handle
   removal of aView (and recursively, its children) from its window -
   performing tidyup by invalidating cursor rects etc.  </p> 
   <standards><NotMacOS-X/><NotOpenStep/></standards>
 */
-- (void) removeSubview: (NSView*)aSubview
+- (void) removeSubview: (NSView*)aView
 {
   id view;
   /*
@@ -502,22 +503,22 @@ GSSetDragTypes(NSView* obj, NSArray *types)
     view != nil && [view respondsToSelector:@selector(superview)];
     view = [view superview])
     {
-      if (view == aSubview)
+      if (view == aView)
 	{      
 	  [_window makeFirstResponder: _window];
 	  break;
 	}
     }
-  [self willRemoveSubview: aSubview];
+  [self willRemoveSubview: aView];
-  aSubview->_super_view = nil;
+  aView->_super_view = nil;
-  [aSubview viewWillMoveToWindow: nil];
+  [aView viewWillMoveToWindow: nil];
-  [aSubview setNextResponder: nil];
+  [aView setNextResponder: nil];
-  RETAIN(aSubview);
+  RETAIN(aView);
-  [_sub_views removeObjectIdenticalTo: aSubview];
+  [_sub_views removeObjectIdenticalTo: aView];
-  [aSubview setNeedsDisplay: NO];
+  [aView setNeedsDisplay: NO];
-  [aSubview viewDidMoveToWindow];
+  [aView viewDidMoveToWindow];
-  [aSubview viewDidMoveToSuperview];
+  [aView viewDidMoveToSuperview];
-  RELEASE(aSubview);
+  RELEASE(aView);
   if ([_sub_views count] == 0)
     {
       _rFlags.has_subviews = 0;
@@ -1811,18 +1812,23 @@ GSSetDragTypes(NSView* obj, NSArray *types)
     }
 }
 
-- (void) displayRect: (NSRect)rect
+/**
+ * Causes the area of the view specified by aRect to be displayed.
+ * This is done by moving up the view hierarchy until an opaque view
+ * is found, then asking that view to update the appropriate area.
+ */
+- (void) displayRect: (NSRect)aRect
 {
   if ([self isOpaque] == YES)
     {
-      [self displayRectIgnoringOpacity: rect];
+      [self displayRectIgnoringOpacity: aRect];
     }
   else
     {
       NSView *firstOpaque = [self opaqueAncestor];
 
-      rect = [firstOpaque convertRect: rect fromView: self];
+      aRect = [firstOpaque convertRect: aRect fromView: self];
-      [firstOpaque displayRectIgnoringOpacity: rect];
+      [firstOpaque displayRectIgnoringOpacity: aRect];
     }
 }
 
@@ -1973,7 +1979,12 @@ GSSetDragTypes(NSView* obj, NSArray *types)
     }
 }
 
-- (void) setNeedsDisplayInRect: (NSRect)rect
+/**
+ * Inform the view system that the specified rectangle is invalid and
+ * requires updating.  This automatically informs any superviews of
+ * any updating they need to do.
+ */
+- (void) setNeedsDisplayInRect: (NSRect)invalidRect
 {
   NSView	*currentView = _super_view;
 
@@ -1982,22 +1993,22 @@ GSSetDragTypes(NSView* obj, NSArray *types)
    *	if the result is the same as the old _invalidRect - if it isn't then
    *	set the new _invalidRect.
    */
-  rect = NSIntersectionRect(rect, _bounds);
+  invalidRect = NSIntersectionRect(invalidRect, _bounds);
-  rect = NSUnionRect(_invalidRect, rect);
+  invalidRect = NSUnionRect(_invalidRect, invalidRect);
-  if (NSEqualRects(rect, _invalidRect) == NO)
+  if (NSEqualRects(invalidRect, _invalidRect) == NO)
     {
       NSView	*firstOpaque = [self opaqueAncestor];
 
       _rFlags.needs_display = YES;
-      _invalidRect = rect;
+      _invalidRect = invalidRect;
       if (firstOpaque == self)
 	{
 	  [_window setViewsNeedDisplay: YES];
 	}
       else
 	{
-	  rect = [firstOpaque convertRect: _invalidRect fromView: self];
+	  invalidRect = [firstOpaque convertRect: _invalidRect fromView: self];
-	  [firstOpaque setNeedsDisplayInRect: rect];
+	  [firstOpaque setNeedsDisplayInRect: invalidRect];
 	}
     }
   /*
@@ -2554,12 +2565,17 @@ static NSView* findByTag(NSView *view, int aTag, unsigned *level)
 	   slideBack: slideFlag];
 }
 
-- (void) registerForDraggedTypes: (NSArray*)types
+/**
+ * Registers the fact that the receiver should accept dragged data
+ * of any of the specified types.  You need to do this if you want
+ * your view to support drag and drop.
+ */
+- (void) registerForDraggedTypes: (NSArray*)newTypes
 {
   NSArray	*o;
   NSArray	*t;
 
-  if (types == nil || [types count] == 0)
+  if (newTypes == nil || [newTypes count] == 0)
     [NSException raise: NSInvalidArgumentException
 		format: @"Types information missing"];
 
@@ -2577,7 +2593,7 @@ static NSView* findByTag(NSView *view, int aTag, unsigned *level)
       o = nil;
     }
 
-  t = GSSetDragTypes(self, types);
+  t = GSSetDragTypes(self, newTypes);
   _rFlags.has_draginfo = 1;
   if (_window != nil)
     {
@@ -2867,7 +2883,7 @@ static NSView* findByTag(NSView *view, int aTag, unsigned *level)
   [self beginPageInRect: aRect atPlacement: location];
 }
 
-- (void) beginPrologueBBox: (NSRect)bBox
+- (void) beginPrologueBBox: (NSRect)boundingBox
 	      creationDate: (NSString*)dateCreated
 		 createdBy: (NSString*)anApplication
 		     fonts: (NSString*)fontNames
@@ -2897,10 +2913,10 @@ static NSView* findByTag(NSView *view, int aTag, unsigned *level)
   else
     DPSPrintf(ctxt, "%%%%DocumentFonts: (atend)\n");
 
-  if (NSIsEmptyRect(bBox) == NO)
+  if (NSIsEmptyRect(boundingBox) == NO)
     DPSPrintf(ctxt, "%%%%BoundingBox: %d %d %d %d\n", 
-    	      (int)NSMinX(bBox), (int)NSMinY(bBox), 
+    	      (int)NSMinX(boundingBox), (int)NSMinY(boundingBox), 
-	      (int)NSMaxX(bBox), (int)NSMaxY(bBox));
+	      (int)NSMaxX(boundingBox), (int)NSMaxY(boundingBox));
   else
     DPSPrintf(ctxt, "%%%%BoundingBox: (atend)\n");
 

Source/NSWindow.m

@@ -1502,7 +1502,11 @@ static NSNotificationCenter *nc = nil;
   [self setFrameOrigin: origin];
 }
 
-- (NSRect) constrainFrameRect: (NSRect)frameRect toScreen: screen
+/**
+ * Given a proposed frame rectangle, return a modified version
+ * which will fit inside the screen.
+ */
+- (NSRect) constrainFrameRect: (NSRect)frameRect toScreen: (NSScreen*)screen
 {
   NSRect screenRect = [screen frame];
   float difference;
@@ -1532,7 +1536,9 @@ static NSNotificationCenter *nc = nil;
 	  frameRect.size.height -= difference;
 	}
       if (frameRect.size.height < _minimumSize.height)
-	frameRect.size.height = _minimumSize.height;
+	{
+	  frameRect.size.height = _minimumSize.height;
+	}
     }
 
   return frameRect;
@@ -1690,31 +1696,36 @@ static NSNotificationCenter *nc = nil;
   // FIXME: This method is missing
 }
 
-/*
+/**
- * Converting coordinates
+ * Convert from a point in the base coordinate system for the window
+ * to a point in the screen coordinate system.
  */
-- (NSPoint) convertBaseToScreen: (NSPoint)basePoint
+- (NSPoint) convertBaseToScreen: (NSPoint)aPoint
 {
   GSDisplayServer *srv = GSCurrentServer();
   NSPoint		screenPoint;
   float			t, b, l, r;
 
   [srv styleoffsets: &l : &r : &t : &b : _styleMask];
-  screenPoint.x = _frame.origin.x + basePoint.x + l;
+  screenPoint.x = _frame.origin.x + aPoint.x + l;
-  screenPoint.y = _frame.origin.y + basePoint.y + b;
+  screenPoint.y = _frame.origin.y + aPoint.y + b;
 
   return screenPoint;
 }
 
-- (NSPoint) convertScreenToBase: (NSPoint)screenPoint
+/**
+ * Convert from a point in the screen coordinate system to a point in the
+ * screen coordinate system of the receiver.
+ */
+- (NSPoint) convertScreenToBase: (NSPoint)aPoint
 {
   GSDisplayServer *srv = GSCurrentServer();
   NSPoint 		basePoint;
   float			t, b, l, r;
 
   [srv styleoffsets: &l : &r : &t : &b : _styleMask];
-  basePoint.x = screenPoint.x - _frame.origin.x - l;
+  basePoint.x = aPoint.x - _frame.origin.x - l;
-  basePoint.y = screenPoint.y - _frame.origin.y - b;
+  basePoint.y = aPoint.y - _frame.origin.y - b;
 
   return basePoint;
 }
@@ -3677,13 +3688,13 @@ Code shared with [NSPanel -sendEvent:], remember to update both places.
   return _defaultButtonCell;
 }
 
-- (void) setDefaultButtonCell: (NSButtonCell *)aButtonCell
+- (void) setDefaultButtonCell: (NSButtonCell *)aCell
 {
-  ASSIGN(_defaultButtonCell, aButtonCell);
+  ASSIGN(_defaultButtonCell, aCell);
   _f.default_button_cell_key_disabled = NO;
 
-  [aButtonCell setKeyEquivalent: @"\r"];
+  [aCell setKeyEquivalent: @"\r"];
-  [aButtonCell setKeyEquivalentModifierMask: 0];
+  [aCell setKeyEquivalentModifierMask: 0];
 }
 
 - (void) disableKeyEquivalentForDefaultButtonCell

Source/NSWorkspace.m

@@ -683,12 +683,12 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
     }
 }
 
-- (NSImage*) iconForFile: (NSString*)aPath
+- (NSImage*) iconForFile: (NSString*)fullPath
 {
   NSImage	*image = nil;
-  NSString	*pathExtension = [[aPath pathExtension] lowercaseString];
+  NSString	*pathExtension = [[fullPath pathExtension] lowercaseString];
 
-  if ([self isFilePackageAtPath: aPath])
+  if ([self isFilePackageAtPath: fullPath])
     {
       NSFileManager	*mgr = [NSFileManager defaultManager];
       NSString		*iconPath = nil;
@@ -699,7 +699,7 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
 	{
 	  NSBundle	*bundle;
 
-	  bundle = [NSBundle bundleWithPath: aPath];
+	  bundle = [NSBundle bundleWithPath: fullPath];
 	  iconPath = [[bundle infoDictionary] objectForKey: @"NSIcon"];
 	  if (iconPath && [iconPath isAbsolutePath] == NO)
 	    {
@@ -713,7 +713,7 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
 	       */
 	      if (iconPath == nil)
 		{
-		  iconPath = [aPath stringByAppendingPathComponent: file];
+		  iconPath = [fullPath stringByAppendingPathComponent: file];
 		  if ([mgr isReadableFileAtPath: iconPath] == NO)
 		    {
 		      iconPath = nil;
@@ -728,8 +728,9 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
 	    {
 	      NSString	*str;
 
-	      str = [[aPath lastPathComponent] stringByDeletingPathExtension];
+	      str = [fullPath lastPathComponent];
-	      iconPath = [aPath stringByAppendingPathComponent: str];
+	      str = [str stringByDeletingPathExtension];
+	      iconPath = [fullPath stringByAppendingPathComponent: str];
 	      iconPath = [iconPath stringByAppendingPathExtension: @"tiff"];
 	      if ([mgr isReadableFileAtPath: iconPath] == NO)
 		{
@@ -744,7 +745,7 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
        */
       if (iconPath == nil)
 	{
-	  iconPath = [aPath stringByAppendingPathComponent: @".dir.tiff"];
+	  iconPath = [fullPath stringByAppendingPathComponent: @".dir.tiff"];
 	  if ([mgr isReadableFileAtPath: iconPath] == NO)
 	    {
 	      iconPath = nil;
@@ -770,11 +771,11 @@ inFileViewerRootedAtPath: (NSString*)rootFullpath
 	  image = [self _iconForExtension: pathExtension];
 	  if (image == nil || image == [self unknownFiletypeImage])
 	    {
-	      if ([aPath isEqual: _rootPath])
+	      if ([fullPath isEqual: _rootPath])
 		{
 		  image = [self rootImage];
 		}
-	      else if ([aPath isEqual: NSHomeDirectory ()])
+	      else if ([fullPath isEqual: NSHomeDirectory ()])
 		{
 		  image = [self homeDirectoryImage];
 		}