This is NSColor.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSColor
pard s14 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s7 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding, NSCopying
fi0 NSObject (NSObject)
fs20
fs28 s8 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSColor.h
fs20
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 fs28 An NSColor represents a color. The color can be a grayscale value and can include alpha (opacity) information. By sending a b set b0 message to an NSColor instance, you set the color for the current PostScript drawing context. This causes subsequently drawn graphics to have the color represented by the NSColor instance.
fs16
fs28 A color is defined in some particular i color spacei0 . A color space consists of a set of dimensions'd0such as red, green, and blue in the case of RGB space. Each point in the space represents a unique color, and the point'27s location along each dimension is called a i componenti0 . An individual color is usually specified by the numeric values of its components, which range from 0.0 to 1.0. For instance, a pure red is specified in RGB space by the component values 1.0, 0.0, and 0.0.
fs16
fs28 Some color spaces include an alpha component, which defines the color'27s opacity. An alpha value of 1.0 means completely opaque, and 0.0 means completely transparent. The alpha component is ignored when the color is used on a device that doesn'27t support alpha, such as a printer.
fs16
fs28 There are three kinds of color space in OpenStep:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab i Device-dependenti0 . This means that a given color might not look the same on different displays and printers.
fs16
fs28 'b7tab i Device-independenti0 , also known as i calibrated. i0 With this sort of color space, a given color should look the same on all devices.
fs16
fs28 'b7tab i Namedi0 . The 'aanamed color space'ba has components that aren'27t numeric values, but simply names in various catalogs of colors. Named colors come with lookup tables that provide the ability to generate the correct color on a given device.
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 OpenStep includes six different color spaces, referred to by these enumeration constants:
fs16
fs28 pard s21 li4636 fi-3782 ri1007 ql tx4636 tx10432 NSDeviceCMYKColorSpacetab Cyan, magenta, yellow, black, and alpha components
fs16
fs28 fi-3782 fi-3782 NSDeviceWhiteColorSpacetab White and alpha components
fs16
fs28 fi-3782 fi-3782 NSDeviceRGBColorSpacetab Red, green, blue, and alpha componentstab
fi0 tab Hue, saturation, brightness, and alpha components
fs16
fs28 fi-3782 NSCalibratedWhiteColorSpacetab White and alpha components
fs16
fs28 fi-3782 fi-3782 NSCalibratedRGBColorSpacetab Red, green, blue, and alpha components
fi0 tab Hue, saturation, brightness, and alpha components
fs16
fs28 fi-3782 NSNamedColorSpacetab Catalog name and color name components
fs16
fs28 fi-3782 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 (Color spaces whose names start with 'aaNSDevice'ba are device-dependent; those with 'aaNSCalibrated'ba are device-independent.)
fs16
fs28 There'27s usually no need to retrieve the individual components of a color, but when needed, you can either retrieve a set of components (using such methods as b getRed:green:blue:alpha:b0 ) or an individual component (using such methods as b redComponentb0 ). However, it'27s illegal to ask an NSColor for components that aren'27t defined for its color space. You can identify the color space by sending a b colorSpaceNameb0 method to the NSColor. If you need to ask an NSColor for components that aren'27t in its color space (for instance, when you'27ve gotten the color from the color panel), first convert the color to the appropriate color space using the b colorUsingColorSpaceName:b0 method. If the color is already in the specified color space, you get the same color back; otherwise you get a conversion that'27s usually lossy or that'27s correct only for the current device. You might also get back b nilb0 if the specified conversion can'27t be done.
fs16
fs28 Subclasses of NSColor need to implement the b colorSpaceName b0 andb setb0 methods, as well as the methods that return the components for that color space and the methods in the NSCoding protocol. Some other methods'd0such as b colorWithAlphaComponent:b0 , b isEqual:b0 , and b colorUsingColorSpaceName:device:b0 'd0may also be implemented if they make sense for the color space. Mutable subclasses (if any) should additionally implement b copyWithZone:b0 to provide a true copy.
fs16
fs28 pard s19 li100 fi0 ri1007 ql f0 b fs24
fs28 Creating an NSColor from Component Values
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSColor *)b colorWithCalibratedHue:b0 (float)i huei0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b saturation:b0 (float)i saturationi0 tab tab NSCalibratedRGBColorSpace, whose opacity value is
b brightness:b0 (float)i brightnessi0 tab i tab alphai0 , and whose components in HSB space would be
b alpha:b0 (float)i alphai0 tab i tab huei0 ,i saturationi0 , andi brightnessi0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithCalibratedRed:b0 (float)i redi0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b green:b0 (float)i greeni0 tab tab NSCalibratedRGBColorSpace, whose opacity value is
b blue:b0 (float)i bluei0 tab i tab alphai0 , and whose RGB components are i red, greeni0 , and
b alpha:b0 (float)i alphai0 tab i tab bluei0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithCalibratedWhite:b0 (float)i whitei0 tab
s11 li7030 fi-6553 fi-5796 b alpha:b0 (float)i alphai0 tab Creates and returns a new NSColor whose color space is NSCalibratedWhiteColorSpace, whose opacity value is i alphai0 , and whose grayscale value is i whitei0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithCatalogName:b0 (NSString *)i listName
s11 li7030 fi-6553 fi-5796 i0 b colorName:b0 (NSString *)i colorNamei0 tab Creates and returns a new NSColor whose color space is NSNamedColorSpace, by finding the color named i colorNamei0 in the catalog named i listName.
s9 li7029 fi-5794 fi-6552 i0 fs16
fs28 fi-6552 + (NSColor *)b colorWithDeviceCyan:b0 (float)i cyani0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b magenta:b0 (float)i magentai0 tab tab NSDeviceCMYKColorSpace, whose opacity value is
b yellow:b0 (float)i yellowi0 tab i tab alphai0 , and whose CMYK components are i cyani0 ,
b black:b0 (float)i blacki0 tab i tab magentai0 ,i yellowi0 , and i blacki0 . All values are legal, but
b alpha:b0 (float)i alphai0 tab tab values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithDeviceHue:b0 (float)i huei0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b saturation:b0 (float)i saturationi0 tab tab NSDeviceRGBColorSpace, whose opacity value is
b brightness:b0 (float)i brightnessi0 tab i tab alphai0 , and whose components in HSB space would be
b alpha:b0 (float)i alphai0 tab i tab huei0 ,i saturationi0 , andi brightnessi0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithDeviceRed:b0 (float)i redi0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b green:b0 (float)i greeni0 tab tab NSDeviceRGBColorSpace, whose opacity value is
b blue:b0 (float)i bluei0 tab i tab alphai0 , and whose RGB components are i red, greeni0 , and
b alpha:b0 (float)i alphai0 tab i tab bluei0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 + (NSColor *)b colorWithDeviceWhite:b0 (float)i whitei0 tab Creates and returns a new NSColor whose color space is
s11 li7030 fi-6553 fi-5796 b alpha:b0 (float)i alphai0 tab tab NSDeviceWhiteColorSpace, whose opacity value is i alphai0 , and whose grayscale value is i whitei0 . All values are legal, but values less than 0.0 are set to 0.0, and values greater than 1.0 are set to 1.0.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Creating an NSColor With Preset Components
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSColor *)b blackColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 0.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b blueColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 0.0, 1.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b brownColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.6, 0.4, 0.2 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b clearColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale and alpha values are both 0.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b cyanColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 1.0, 1.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b darkGrayColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 1/3 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b grayColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 0.5 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b greenColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.0, 1.0, 0.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b lightGrayColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale value is 2/3 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b magentaColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.0, 1.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b orangeColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.5, 0.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b purpleColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 0.5, 0.0, 0.5 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b redColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 0.0, 0.0 and whose alpha value is 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b whiteColorb0 tab Returns an NSColor in NSCalibratedWhiteColorSpace whose grayscale and alpha values are both 1.0.
fi-6552 fs16
fs28 fi-6552 + (NSColor *)b yellowColorb0 tab Returns an NSColor in NSCalibratedRGBColorSpace whose RGB value is 1.0, 1.0, 0.0 and whose alpha value is 1.0.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Ignoring Alpha Components
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (BOOL)b ignoresAlphab0 tab Returns YES (the default) if the application hides the color panel'27s opacity slider and sets imported colors'27 alpha values to 1.0.
fi-6552 fs16
fs28 fi-6552 + (void)b setIgnoresAlpha:b0 (BOOL)i flagi0 tab If i flag i0 is YES, no opacity slider is displayed in the color panel, and colors dragged in or pasted have their alpha values set to 1.0.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Retrieving a Set of Components
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b getCyan:b0 (float *)i cyani0 tab Returns the CMYK and alpha values in the respective
s11 li7030 fi-6553 fi-5796 b magenta:b0 (float *)i magentai0 tab tab arguments. Ifi i0 NULLb b0 is passed in as an argument, the
b yellow:b0 (float *)i yellowi0 tab tab method doesn'27t set that value. It'27s an error if the
b black:b0 (float *)i blacki0 tab tab receiver isn'27t a CMYK color.
b alpha:b0 (float *)i alphai0 tab
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b getHue:b0 (float *)i huei0 tab Returns the HSB and alpha values in the respective
s11 li7030 fi-6553 fi-5796 b saturation:b0 (float *)i saturationi0 tab tab arguments. Ifi i0 NULLb b0 is passed in as an argument, the
b brightness:b0 (float *)i brightnessi0 tab tab method doesn'27t set that value. It'27s an error if the
b alpha:b0 (float *)i alphai0 tab tab receiver isn'27t a CMYK color.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b getRed:b0 (float *)i redi0 tab Returns the RGB and alpha values in the respective
s11 li7030 fi-6553 fi-5796 b green:b0 (float *)i greeni0 tab tab arguments. Ifi i0 NULLb b0 is passed in as an argument, the
b blue:b0 (float *)i bluei0 tab tab method doesn'27t set that value. It'27s an error if the
b alpha:b0 (float *)i alphai0 tab tab receiver isn'27t a CMYK color.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b getWhite:b0 (float *)i whitei0 tab Returns the grayscale and alpha values in the respective
s11 li7030 fi-6553 fi-5796 b alpha:b0 (float *)i alphai0 tab tab arguments. Ifi i0 NULLb b0 is passed in as an argument, the method doesn'27t set that value. It'27s an error if the receiver isn'27t a CMYK color.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Retrieving Individual Components
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (float)b alphaComponentb0 tab Returns the alpha (opacity) component (1.0 by default).
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b blackComponentb0 tab Returns the black component. It'27s an error if the receiver isn'27t a CMYK color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b blueComponentb0 tab Returns the blue component. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b brightnessComponentb0 tab Returns the brightness component of the HSB color equivalent to the receiver. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b catalogNameComponentb0 tab Returns the name of the catalog containing this color, or b nilb0 if the receiver'27s color space isn'27t NSNamedColorSpace.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b colorNameComponentb0 tab Returns the name of this color, or b nilb0 if the receiver'27s color space isn'27t NSNamedColorSpace.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b cyanComponentb0 tab Returns the cyan component. It'27s an error if the receiver isn'27t a CMYK color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b greenComponentb0 tab Returns the green component. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b hueComponentb0 tab Returns the hue component of the HSB color equivalent to the receiver. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b localizedCatalogNameComponentb0 tab Like b catalogNameComponentb0 , but returns a localized string.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b localizedColorNameComponentb0 tab Like b colorNameComponentb0 , but returns a localized string.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b magentaComponentb0 tab Returns the magenta component. It'27s an error if the receiver isn'27t a CMYK color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b redComponentb0 tab Returns the red component. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b saturationComponentb0 tab Returns the saturation component of the HSB color equivalent to the receiver. It'27s an error if the receiver isn'27t an RGB color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b whiteComponentb0 tab Returns the white component. It'27s an error if the receiver isn'27t a grayscale color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b yellowComponentb0 tab Returns the yellow component. It'27s an error if the receiver isn'27t a CMYK color.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Converting to Another Color Space
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSString *)b colorSpaceNameb0 tab Returns the name of the NSColor'27s color space.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSColor *)b colorUsingColorSpaceName:b0 (NSString *)i colorSpacei0 tab
s11 li7030 fi-6553 fi-5796 tab Returns a newly created NSColor whose color is the same as the receiver'27s, except that the new NSColor is in the color space named i colorSpacei0 . This method calls b colorUsingColorSpaceName:device:b0 with the current device, indicating that the color is appropriate for the current device (the current window if drawing, or the current printer if printing).
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSColor *)b colorUsingColorSpaceName:b0 (NSString *)i colorSpace
s11 li7030 fi-6553 fi-5796 i0 b device:b0 (NSDictionary *)i deviceDescriptioni0 tab Returns a newly created NSColor whose color is the same as the receiver'27s, except that the new NSColor is in the color space named i colorSpace i0 and is specific to the device described by i deviceDescription.
pard s19 li100 fi0 ri1007 ql f0 b i0 fs48
fs28 Changing the Color
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSColor *)b blendedColorWithFraction:b0 (float)i fractioni0 tab
s11 li7030 fi-6553 fi-5796 b ofColor:b0 (NSColor *)i aColori0 tab Returns a newly created NSColor in NSCalibratedRGBColorSpace whose component values are a weighted sum of the receiver'27s and i aColori0 '27s. The method converts i aColori0 and a copy of the receiver to RGB, and then sets each component of the returned color to i fractioni0 of i aColori0 '27s value plus 1 {f3 -} i fractioni0 of the receiver'27s. If the colors can'27t be converted to NSCalibratedRGBColorSpace, b nilb0 is returned.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSColor *)b colorWithAlphaComponent:b0 (float)i alphai0 tab
s11 li7030 fi-6553 fi-5796 tab Returns a newly created NSColor that has the same color space and component values as the receiver, except that its alpha component is i alphai0 . If the receiver'27s color space doesn'27t include an alpha component, the receiver is returned.
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Copying and Pasting
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSColor *)b colorFromPasteboard:b0 (NSPasteboard *)i pasteBoardi0 tab
s11 li7030 fi-6553 fi-5796 tab Returns the NSColor currently on the pasteboard, or b nil b0 if the pasteboard doesn'27t contain color data. The returned color'27s alpha component is set to 1.0 if b ignoresAlphab0 returns YES.
s9 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b writeToPasteboard:b0 (NSPasteboard *)i pasteBoardi0 tab
s11 li7030 fi-6553 fi-5796 tab Writes the receiver'27s data to the pasteboard, unless the pasteboard doesn'27t support color data (in which case the method does nothing).
pard s19 li100 fi0 ri1007 ql f0 b fs48
fs28 Drawing
fs14
fs28 pard s9 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b drawSwatchInRect:b0 (NSRect)i recti0 tab Draws the current color in the rectangle i recti0 . Subclasses adorn the rectangle in some manner to indicate the type of color. This method is invoked by color wells, swatches, and other user-interface objects that need to display colors.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b setb0 tab Sets the color of subsequent PostScript drawing to the color that the receiver represents. If the application is drawing to the screen rather than printing, this method also sets the current drawing context'27s alpha value to the value returned by b alphaComponentb0 .
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.