From 093651e20c43254ef87feea6da0daf50bbd52a49 Mon Sep 17 00:00:00 2001 From: Fabien Vallon Date: Sun, 4 Dec 2005 19:12:12 +0000 Subject: [PATCH] Improved docuentation git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@22135 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 6 +++++ Source/NSClipView.m | 22 ++++++++++------ Source/NSColor.m | 58 +++++++++++++++++++++++++++++++++++++------ Source/NSColorPanel.m | 44 +++++++++++++++++++------------- 4 files changed, 99 insertions(+), 31 deletions(-) diff --git a/ChangeLog b/ChangeLog index 82d2e28cb..561c15a74 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2005-12-04 Fabien VALLON + + * Source/NSColorPanel.m: Improved documentation, various cleanups + * Source/NSColor.m: Improved documentation + * Source/NSClipView.m: Improved documentation + 2005-12-04 Richard Frith-Macdonald * Source/GSServicesManager.m: Implement use of NSUseRunningCopy diff --git a/Source/NSClipView.m b/Source/NSClipView.m index 10b9686be..8a5809fdc 100644 --- a/Source/NSClipView.m +++ b/Source/NSClipView.m @@ -118,7 +118,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view) /**

Sets aView the NSClipView's document view to aView - .TODO explain notifications ...

+

See Also: -documentView

*/ - (void) setDocumentView: (NSView*)aView @@ -368,7 +368,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view) } /** - *

TODO

+ *

*/ - (NSPoint) constrainScrollPoint: (NSPoint)proposedNewOrigin { @@ -462,8 +462,9 @@ static inline NSRect integralRect (NSRect rect, NSView *view) return rect; } -/**

Returns the document visible rectangle

-

See Also: -documentRect

+/**

Returns the document visible rectangle. Returns NSZeroRect if the + document view does not exists.

+

See Also: -documentRect [NSView-convertRect:toView:]

*/ - (NSRect) documentVisibleRect { @@ -492,7 +493,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view) } } -/**

Scrolls in response to mouse-dragged events.

+/**

Scrolls in response to mouse-dragged events.

*/ - (BOOL) autoscroll: (NSEvent*)theEvent { @@ -599,7 +600,7 @@ static inline NSRect integralRect (NSRect rect, NSView *view) } /** - *

Returns the NSClipView's document view

+ *

Returns the NSClipView's document view.

*

See Also: -setDocumentView:

*/ - (id) documentView @@ -607,11 +608,15 @@ static inline NSRect integralRect (NSRect rect, NSView *view) return _documentView; } +/** + */ - (void) setCopiesOnScroll: (BOOL)flag { _copiesOnScroll = flag; } +/** + */ - (BOOL) copiesOnScroll { return _copiesOnScroll; @@ -642,7 +647,10 @@ static inline NSRect integralRect (NSRect rect, NSView *view) } /**

Sets the NSClipView's background color to aColor and marks - self for display. Sets the opaque flag to if needed

+ self for display. Sets the opaque flag if needed ( to YES if the + NSClipView does not draw its background, if the background color + is nil or if the background color alpha component is less than 1.0 , NO + otherwise)

See Also: -backgroundColor [NSView-isOpaque]

*/ - (void) setBackgroundColor: (NSColor*)aColor diff --git a/Source/NSColor.m b/Source/NSColor.m index 2990eff8c..9df231309 100644 --- a/Source/NSColor.m +++ b/Source/NSColor.m @@ -649,7 +649,7 @@ systemColorWithName(NSString *name) } -/** TODO +/** Returns whether TODO *

See Also: +setIgnoresAlpha:

*/ + (BOOL) ignoresAlpha @@ -866,10 +866,9 @@ systemColorWithName(NSString *name) return nil; } -/** - *

Returns CYMK and alpha values. - * GNUstep implemenation raise an NSInternalInconsistencyException

- * +/**

Gets the cyan, magenta, yellow,black and alpha values from the NSColor. + Raises a NSInternalInconsistencyException if the NSColor is not a CYMK color +

*/ - (void) getCyan: (float*)cyan magenta: (float*)magenta @@ -881,6 +880,10 @@ systemColorWithName(NSString *name) format: @"Called getCyan:magenta:yellow:black:alpha: on non-CMYK colour"]; } +/**

Gets the hue, saturation, brightness and alpha values from the NSColor. + Raises a NSInternalInconsistencyException if the NSColor is not a RGB color +

+ */ - (void) getHue: (float*)hue saturation: (float*)saturation brightness: (float*)brightness @@ -890,7 +893,11 @@ systemColorWithName(NSString *name) format: @"Called getHue:saturation:brightness:alpha: on non-RGB colour"]; } -- (void) getRed: (float*)red +/**

Gets the red, green, blue and alpha values from the NSColor. + Raises a NSInternalInconsistencyException if the NSColor is not a RGB color +

+ */ +-(void) getRed: (float*)red green: (float*)green blue: (float*)blue alpha: (float*)alpha @@ -899,6 +906,10 @@ systemColorWithName(NSString *name) format: @"Called getRed:green:blue:alpha: on non-RGB colour"]; } +/**

Gets the white alpha values from the NSColor. + Raises a NSInternalInconsistencyException if the NSColor is not a + greyscale color

+ */ - (void) getWhite: (float*)white alpha: (float*)alpha { @@ -919,13 +930,16 @@ systemColorWithName(NSString *name) } } -/**

Returns the alpha component (1.0 by default)

+/**

Returns the alpha component.

*/ - (float) alphaComponent { return 1.0; } +/**

Returns the black component. Raises a NSInternalInconsistencyException + if NSColor is not a CMYK color.

+ */ - (float) blackComponent { [NSException raise: NSInternalInconsistencyException @@ -933,6 +947,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the blue component. Raises a NSInternalInconsistencyException + if NSColor is not a RGB color.

+ */ - (float) blueComponent { [NSException raise: NSInternalInconsistencyException @@ -940,6 +957,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the brightness component. Raises a + NSInternalInconsistencyException if NSColor space is not a RGB color

+*/ - (float) brightnessComponent { [NSException raise: NSInternalInconsistencyException @@ -961,6 +981,9 @@ systemColorWithName(NSString *name) return nil; } +/**

Returns the cyan component. Raises a NSInternalInconsistencyException + if NSColor is not a CYMK color

+*/ - (float) cyanComponent { [NSException raise: NSInternalInconsistencyException @@ -968,6 +991,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the green component. Raises a NSInternalInconsistencyException + if NSColor is not a RGB color

+*/ - (float) greenComponent { [NSException raise: NSInternalInconsistencyException @@ -975,6 +1001,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the hue component. Raises a NSInternalInconsistencyException + if NSColor is not a RGB color

+*/ - (float) hueComponent { [NSException raise: NSInternalInconsistencyException @@ -996,6 +1025,9 @@ systemColorWithName(NSString *name) return nil; } +/**

Returns the magenta component. Raises a + NSInternalInconsistencyException if NSColor is not a CMYK color

+*/ - (float) magentaComponent { [NSException raise: NSInternalInconsistencyException @@ -1003,6 +1035,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the red component. Raises a NSInternalInconsistencyException + if NSColor is not a RGB color

+*/ - (float) redComponent { [NSException raise: NSInternalInconsistencyException @@ -1010,6 +1045,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the saturation component. Raises a + NSInternalInconsistencyException if NSColor is not a RGB color

+*/ - (float) saturationComponent { [NSException raise: NSInternalInconsistencyException @@ -1017,6 +1055,9 @@ systemColorWithName(NSString *name) return 0.0; } +/**

Returns the white component. Raises a NSInternalInconsistencyException + if NSColor is not a grayscale color

+*/ - (float) whiteComponent { [NSException raise: NSInternalInconsistencyException @@ -1031,6 +1072,9 @@ systemColorWithName(NSString *name) return nil; } +/**

Returns the yellow component. Raises a NSInternalInconsistencyException + if NSColor is not a RGB color

+*/ - (float) yellowComponent { [NSException raise: NSInternalInconsistencyException diff --git a/Source/NSColorPanel.m b/Source/NSColorPanel.m index c633472ec..94cc29af4 100644 --- a/Source/NSColorPanel.m +++ b/Source/NSColorPanel.m @@ -411,32 +411,40 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; _gs_gui_color_picker_mask = mask; } +/** + */ + (void) setPickerMode: (int)mode { _gs_gui_color_picker_mode = mode; } +/**

Drags aColor frome sourceView at the location + give by the event anEvent ( [NSView-convertPoint:fromView:] ). + The type declare into the pasteboard is NSColorPboardType

+

See Also: [NSView-convertPoint:fromView:] + [NSView-dragImage:at:offset:event:pasteboard:source:slideBack:

+ */ + (BOOL) dragColor: (NSColor *)aColor withEvent: (NSEvent *)anEvent fromView: (NSView *)sourceView { NSPasteboard *pb = [NSPasteboard pasteboardWithName: NSDragPboard]; NSImage *image = [NSImage imageNamed: @"common_ColorSwatch"]; - NSSize s; - NSPoint p; + NSSize size; + NSPoint point; [pb declareTypes: [NSArray arrayWithObjects: NSColorPboardType, nil] - owner: aColor]; + owner: aColor]; [aColor writeToPasteboard: pb]; [image setBackgroundColor: aColor]; - s = [image size]; - p = [sourceView convertPoint: [anEvent locationInWindow] fromView: nil]; - p.x -= s.width/2; - p.y -= s.width/2; + size = [image size]; + point = [sourceView convertPoint: [anEvent locationInWindow] fromView: nil]; + point.x -= size.width/2; + point.y -= size.width/2; [sourceView dragImage: image - at: p + at: point offset: NSMakeSize(0,0) event: anEvent pasteboard: pb @@ -530,7 +538,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; /**

Sets the NSColorPanl action method to aSelector The action message is usally send in -setColor:, when the picker is updated, when a new picker is show, when the alpha is changed or when one of the - color well at the bottom is selected

+ color well at the bottom is selected.

*/ - (void) setAction: (SEL)aSelector { @@ -545,7 +553,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; _isContinuous = flag; } -/**

Set the NSColorPanel mode to mode. TODO more about _pickers

+/**

Set the NSColorPanel mode to mode.

See Also: -mode

*/ - (void) setMode: (int)mode @@ -569,7 +577,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; } /**

Sets whether the NSColorPanel shows alpha values and the alpha - slider

See Also: -showsAlpha

+ slider.

See Also: -showsAlpha

*/ - (void) setShowsAlpha: (BOOL)flag { @@ -633,9 +641,10 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; withObject: aColorList]; } -// -// Setting Color -// +/**

Returns the alpha value of the NSColorPanel. Returns + 1.0 if the NSColorPanel does not show alpha

+

See Also: -showsAlpha -setShowsAlpha:

+ */ - (float) alpha { if ([self showsAlpha]) @@ -644,7 +653,7 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; return 1.0; } -/**

Returns the current NSColor displayed by the NSColorPanel

+/**

Returns the current NSColor displayed by the NSColorPanel.

See Also : -setColor:

*/ - (NSColor *) color @@ -653,8 +662,9 @@ static int _gs_gui_color_picker_mode = NSRGBModeColorPanel; } /**

Sets the NSColor displayed to aColor. This method post a - NSColorPanelColorChangedNotification notification

-

See Also: -color

+ NSColorPanelColorChangedNotification notification if needed.

+

See Also: -color [NSColorWell-setColor:] +

*/ - (void) setColor: (NSColor *)aColor {