From 3550daa6a3c7dbb7c3a111d3ac0bc4f33e3a8dcc Mon Sep 17 00:00:00 2001 From: CaS Date: Sun, 13 Oct 2002 07:00:38 +0000 Subject: [PATCH] SRome documentation tidyupsi git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@14751 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 3 ++ Headers/gnustep/gui/NSToolbar.h | 56 +++++++++++------------ Source/NSToolbar.m | 66 ++++++++++++++------------- Source/NSView.m | 80 ++++++++++++++++++++------------- Source/NSWindow.m | 39 ++++++++++------ Source/NSWorkspace.m | 21 ++++----- 6 files changed, 151 insertions(+), 114 deletions(-) diff --git a/ChangeLog b/ChangeLog index d733b9c60..29a2a4ea0 100644 --- a/ChangeLog +++ b/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 diff --git a/Headers/gnustep/gui/NSToolbar.h b/Headers/gnustep/gui/NSToolbar.h index a1ea55d9f..68134e6b9 100644 --- a/Headers/gnustep/gui/NSToolbar.h +++ b/Headers/gnustep/gui/NSToolbar.h @@ -71,29 +71,29 @@ APPKIT_EXPORT NSString *NSToolbarWillAddItemNotification; } // Instance methods -- (BOOL)allowsUserCustomization; -- (BOOL)autosavesConfiguration; -- (NSDictionary *)configurationDictionary; -- (BOOL)customizationPaletteIsRunning; -- (id)delegate; -- (NSToolbarDisplayMode)displayMode; -- (NSString *)identifier; -- (id)initWithIdentifier: (NSString *)indentifier; -- (void)insertItemWithItemIdentifier: (NSString *)itemIdentifier - atIndex: (int)index; -- (BOOL)isVisible; -- (NSArray *)items; -- (void)removeItemAtIndex: (int)index; -- (void)runCustomizationPalette: (id)sender; +- (BOOL) allowsUserCustomization; +- (BOOL) autosavesConfiguration; +- (NSDictionary*) configurationDictionary; +- (BOOL) customizationPaletteIsRunning; +- (id) delegate; +- (NSToolbarDisplayMode) displayMode; +- (NSString*) identifier; +- (id) initWithIdentifier: (NSString*)identifier; +- (void) insertItemWithItemIdentifier: (NSString*)itemIdentifier + atIndex: (int)index; +- (BOOL) isVisible; +- (NSArray*) items; +- (void) removeItemAtIndex: (int)index; +- (void) runCustomizationPalette: (id)sender; -- (void)setAllowsUserCustomization: (BOOL)flag; -- (void)setAutosavesConfiguration: (BOOL)flag; -- (void)setConfigurationFromDictionary: (NSDictionary *)configDict; -- (void)setDelegate: (id)delegate; -- (void)setDisplayMode: (NSToolbarDisplayMode)displayMode; -- (void)setVisible: (BOOL)shown; -- (void)validateVisibleItems; -- (NSArray *)visibleItems; +- (void) setAllowsUserCustomization: (BOOL)flag; +- (void) setAutosavesConfiguration: (BOOL)flag; +- (void) setConfigurationFromDictionary: (NSDictionary*)configDict; +- (void) setDelegate: (id)delegate; +- (void) setDisplayMode: (NSToolbarDisplayMode)displayMode; +- (void) setVisible: (BOOL)shown; +- (void) validateVisibleItems; +- (NSArray*) visibleItems; @end /* interface of NSToolbar */ /* @@ -101,18 +101,18 @@ APPKIT_EXPORT NSString *NSToolbarWillAddItemNotification; */ @interface NSObject (NSToolbarDelegate) // notification methods -- (void) toolbarDidRemoveItem: (NSNotification *)aNotification; -- (void) toolbarWillAddItem: (NSNotification *)aNotification; +- (void) toolbarDidRemoveItem: (NSNotification*)aNotification; +- (void) toolbarWillAddItem: (NSNotification*)aNotification; // delegate methods // required method -- (NSToolbarItem *)toolbar: (NSToolbar *)toolbar - itemForItemIdentifier: (NSString *)itemIdentifier +- (NSToolbarItem*)toolbar: (NSToolbar*)toolbar + 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 */ diff --git a/Source/NSToolbar.m b/Source/NSToolbar.m index 5679d98a2..f3a498f4a 100644 --- a/Source/NSToolbar.m +++ b/Source/NSToolbar.m @@ -46,22 +46,22 @@ static const int current_version = 1; { NSToolbar *_toolbar; } -- (void)setToolbar: (NSToolbar *)toolbar; -- (NSToolbar *)toolbar; +- (void) setToolbar: (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; } diff --git a/Source/NSView.m b/Source/NSView.m index 1b7d42989..c78f12c6c 100644 --- a/Source/NSView.m +++ b/Source/NSView.m @@ -466,7 +466,7 @@ GSSetDragTypes(NSView* obj, NSArray *types) /**

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.

@@ -486,12 +486,13 @@ GSSetDragTypes(NSView* obj, NSArray *types)

Removes aSubview from the receivers list of subviews and from the responder chain.

-

Also invokes [aView -viewWillMoveToWindow: nil] to handle +

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.

*/ -- (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]; - aSubview->_super_view = nil; - [aSubview viewWillMoveToWindow: nil]; - [aSubview setNextResponder: nil]; - RETAIN(aSubview); - [_sub_views removeObjectIdenticalTo: aSubview]; - [aSubview setNeedsDisplay: NO]; - [aSubview viewDidMoveToWindow]; - [aSubview viewDidMoveToSuperview]; - RELEASE(aSubview); + [self willRemoveSubview: aView]; + aView->_super_view = nil; + [aView viewWillMoveToWindow: nil]; + [aView setNextResponder: nil]; + RETAIN(aView); + [_sub_views removeObjectIdenticalTo: aView]; + [aView setNeedsDisplay: NO]; + [aView viewDidMoveToWindow]; + [aView viewDidMoveToSuperview]; + 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]; - [firstOpaque displayRectIgnoringOpacity: rect]; + aRect = [firstOpaque convertRect: aRect fromView: self]; + [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); - rect = NSUnionRect(_invalidRect, rect); - if (NSEqualRects(rect, _invalidRect) == NO) + invalidRect = NSIntersectionRect(invalidRect, _bounds); + invalidRect = NSUnionRect(_invalidRect, invalidRect); + 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]; - [firstOpaque setNeedsDisplayInRect: rect]; + invalidRect = [firstOpaque convertRect: _invalidRect fromView: self]; + [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)NSMaxX(bBox), (int)NSMaxY(bBox)); + (int)NSMinX(boundingBox), (int)NSMinY(boundingBox), + (int)NSMaxX(boundingBox), (int)NSMaxY(boundingBox)); else DPSPrintf(ctxt, "%%%%BoundingBox: (atend)\n"); diff --git a/Source/NSWindow.m b/Source/NSWindow.m index 1c44d00b3..e1955a9cf 100644 --- a/Source/NSWindow.m +++ b/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.y = _frame.origin.y + basePoint.y + b; + screenPoint.x = _frame.origin.x + aPoint.x + l; + 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.y = screenPoint.y - _frame.origin.y - b; + basePoint.x = aPoint.x - _frame.origin.x - l; + 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"]; - [aButtonCell setKeyEquivalentModifierMask: 0]; + [aCell setKeyEquivalent: @"\r"]; + [aCell setKeyEquivalentModifierMask: 0]; } - (void) disableKeyEquivalentForDefaultButtonCell diff --git a/Source/NSWorkspace.m b/Source/NSWorkspace.m index 606bce183..6f31ac309 100644 --- a/Source/NSWorkspace.m +++ b/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]; - iconPath = [aPath stringByAppendingPathComponent: str]; + str = [fullPath lastPathComponent]; + 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]; }