home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / DEV.Z / NSColor.h < prev    next >
Text File  |  1996-09-09  |  11KB  |  213 lines
  1. /*
  2.     NSColor.h
  3.     Application Kit
  4.     Copyright (c) 1994-1996, NeXT Software, Inc.
  5.     All rights reserved.
  6. */
  7.  
  8. /* NSColors store colors. Often the only NSColor message you send is the "set" method, which makes the receiver the current color in the drawing context. There is usually no need to dive in and get the individual components (for instance, red, green, blue) that make up a color.
  9.  
  10. An NSColor may be in one of various colorspaces. Different colorspaces have different ways of getting at the components which define colors in that colorspace. Implementations of NSColors exist for the following colorspaces:
  11.  
  12.   NSDeviceCMYKColorSpace    Cyan, magenta, yellow, black, and alpha components
  13.   NSDeviceWhiteColorSpace    White and alpha components
  14.   NSDeviceRGBColorSpace        Red, green, blue, and alpha components
  15.                 Hue, saturation, brightness, and alpha components
  16.   NSCalibratedWhiteColorSpace    White and alpha components
  17.   NSCalibratedRGBColorSpace    Red, green, blue, and alpha components
  18.                 Hue, saturation, brightness, and alpha components
  19.   NSNamedColorSpace        Catalog name, color name components
  20.  
  21. Alpha component defines opacity on devices which support it (1.0 == full opacity). On other devices the alpha is ignored when the color is used.
  22.  
  23. It's illegal to ask a color for components that are not defined for its colorspace. If you need to ask a color for a certain set of components (for instance, you need to know the RGB components of a color you got from the color panel), you should first convert the color to the appropriate colorspace using the colorUsingColorSpaceName: method.  If the color is already in the specified colorspace, you get the same color back; otherwise you get a conversion which is usually lossy or is correct only for the current device. You might also get back nil if the specified conversion cannot be done.
  24.  
  25. Subclassers of NSColor need to implement the methods colorSpaceName, set, the various methods which return the components for that color space, and the NSCoding protocol. Some other methods such as colorWithAlphaComponent:, isEqual:, colorUsingColorSpaceName:device: may also be implemented if they make sense for the colorspace. Mutable subclassers (if any) should also implement copyWithZone: to a true copy.
  26. */
  27.  
  28. #import <Foundation/NSObject.h>
  29. #import <Foundation/NSGeometry.h>
  30. #import <AppKit/NSGraphics.h>
  31. @class NSPasteboard;
  32. @class NSDictionary;
  33.  
  34.  
  35. @interface NSColor : NSObject <NSCopying, NSCoding>
  36.  
  37.  
  38. /* Create NSCalibratedWhiteColorSpace colors.
  39. */
  40. + (NSColor *)colorWithCalibratedWhite:(float)white alpha:(float)alpha;
  41.  
  42.  
  43. /* Create NSCalibratedRGBColorSpace colors.
  44. */
  45. + (NSColor *)colorWithCalibratedHue:(float)hue saturation:(float)saturation brightness:(float)brightness alpha:(float)alpha;
  46. + (NSColor *)colorWithCalibratedRed:(float)red green:(float)green blue:(float)blue alpha:(float)alpha;
  47.  
  48.  
  49. /* Create colors in various device color spaces. In PostScript these colorspaces correspond directly to the device-dependent operators setgray, sethsbcolor, setrgbcolor, and setcmykcolor.
  50. */
  51. + (NSColor *)colorWithDeviceWhite:(float)white alpha:(float)alpha;
  52. + (NSColor *)colorWithDeviceHue:(float)hue saturation:(float)saturation brightness:(float)brightness alpha:(float)alpha;
  53. + (NSColor *)colorWithDeviceRed:(float)red green:(float)green blue:(float)blue alpha:(float)alpha;
  54. + (NSColor *)colorWithDeviceCyan:(float)cyan magenta:(float)magenta yellow:(float)yellow black:(float)black alpha:(float)alpha;
  55.  
  56.  
  57. /* Create named colors from standard color catalogs (such as Pantone).
  58. */
  59. + (NSColor *)colorWithCatalogName:(NSString *)listName colorName:(NSString *)colorName;
  60.  
  61.  
  62. /* Some convenience methods to create colors in the calibrated color spaces...
  63. */
  64. + (NSColor *)blackColor;    /* 0.0 white */
  65. + (NSColor *)darkGrayColor;    /* 0.333 white */
  66. + (NSColor *)lightGrayColor;    /* 0.667 white */
  67. + (NSColor *)whiteColor;    /* 1.0 white */
  68. + (NSColor *)grayColor;        /* 0.5 white */
  69. + (NSColor *)redColor;        /* 1.0, 0.0, 0.0 RGB */
  70. + (NSColor *)greenColor;    /* 0.0, 1.0, 0.0 RGB */
  71. + (NSColor *)blueColor;        /* 0.0, 0.0, 1.0 RGB */
  72. + (NSColor *)cyanColor;        /* 0.0, 1.0, 1.0 RGB */
  73. + (NSColor *)yellowColor;    /* 1.0, 1.0, 0.0 RGB */
  74. + (NSColor *)magentaColor;    /* 1.0, 0.0, 1.0 RGB */
  75. + (NSColor *)orangeColor;    /* 1.0, 0.5, 0.0 RGB */
  76. + (NSColor *)purpleColor;    /* 0.5, 0.0, 0.5 RGB */
  77. + (NSColor *)brownColor;    /* 0.6, 0.4, 0.2 RGB */
  78. + (NSColor *)clearColor;    /* 0.0 white, 0.0 alpha */
  79.  
  80. #if !defined(STRICT_OPENSTEP)
  81.  
  82. + (NSColor *)controlShadowColor;
  83. + (NSColor *)controlDarkShadowColor;
  84. + (NSColor *)controlColor;
  85. + (NSColor *)controlBackgroundColor;
  86. + (NSColor *)controlHighlightColor;
  87. + (NSColor *)controlLightHighlightColor;
  88. + (NSColor *)textColor;
  89. + (NSColor *)textBackgroundColor;
  90. + (NSColor *)selectedTextColor;
  91. + (NSColor *)selectedTextBackgroundColor;
  92. + (NSColor *)controlTextColor;
  93. + (NSColor *)selectedControlTextColor;
  94. + (NSColor *)selectedControlColor;
  95. + (NSColor *)scrollBarColor;
  96. + (NSColor *)gridColor;
  97.  
  98. #endif    /* !defined(STRICT_OPENSTEP) */
  99.  
  100. /* Set the color: Sets the color in the current drawing context. If drawing to the screen, this method also sets the alpha; if the color doesn't know about alpha, it's set to 1.0. Should be implemented by subclassers.
  101. */
  102. - (void)set;
  103.  
  104.  
  105. /* Get the color space of the color. Should be implemented by subclassers.
  106. */
  107. - (NSString *)colorSpaceName;
  108.  
  109.  
  110. /* Convert the color to another colorspace. This may return nil if the specified conversion cannot be done. The abstract implementation of this method returns the receiver if the specified colorspace matches that of the receiver; otherwise it returns nil. Subclassers who can convert themselves to other colorspaces override this method to do something better.
  111.  
  112. The version of this method which takes a device description allows the color to specialize itself for the given device.  Device descriptions can be obtained from windows, screens, and printers with the "deviceDescription" method.
  113.  
  114. If device is nil then the current device (as obtained from the currently lockFocus'ed view's window or, if printing, the current printer) is used. The method without the device: argument passes nil for the device.
  115.  
  116. If colorSpace is nil, then the most appropriate color space is used.
  117. */ 
  118. - (NSColor *)colorUsingColorSpaceName:(NSString *)colorSpace;
  119. - (NSColor *)colorUsingColorSpaceName:(NSString *)colorSpace device:(NSDictionary *)deviceDescription;
  120.  
  121.  
  122. /* Blend using the NSCalibratedRGB color space. Both colors are converted into the calibrated RGB color space, and they are blended by taking fraction of color and 1 - fraction of the receiver. The result is in the calibrated RGB color space. If the colors cannot be converted into the calibrated RGB color space the blending fails and nil is returned.
  123. */
  124. - (NSColor *)blendedColorWithFraction:(float)fraction ofColor:(NSColor *)color;
  125.  
  126.  
  127. /* Returns a color in the same color space as the receiver with the specified alpha component. The abstract implementation of this method returns the receiver if alpha is 1.0, otherwise it returns nil; subclassers who have explicit opacity components override this method to actually return a color with the specified alpha.
  128. */
  129. - (NSColor *)colorWithAlphaComponent:(float)alpha;
  130.  
  131.  
  132. /*** Methods to get various components of colors. Not all of the methods apply to all colors; if called, they raise. ***/
  133.  
  134. /* Get the catalog and color name of standard colors from catalogs. These colors are special colors which are usually looked up on each device by their name.
  135. */
  136. - (NSString *)catalogNameComponent;
  137. - (NSString *)colorNameComponent;
  138.  
  139. /* Return localized versions of the above.
  140. */
  141. - (NSString *)localizedCatalogNameComponent;
  142. - (NSString *)localizedColorNameComponent;
  143.  
  144. /* Get the red, green, or blue components of NSCalibratedRGB or NSDeviceRGB colors.
  145. */
  146. - (float)redComponent;
  147. - (float)greenComponent;
  148. - (float)blueComponent;
  149. - (void)getRed:(float *)red green:(float *)green blue:(float *)blue alpha:(float *)alpha;
  150.  
  151. /* Get the components of NSCalibratedRGB or NSDeviceRGB colors as hue, saturation, or brightness.
  152. */
  153. - (float)hueComponent;
  154. - (float)saturationComponent;
  155. - (float)brightnessComponent;
  156. - (void)getHue:(float *)hue saturation:(float *)saturation brightness:(float *)brightness alpha:(float *)alpha;
  157.  
  158.  
  159. /* Get the white component of NSCalibratedWhite or NSDeviceWhite colors.
  160. */
  161. - (float)whiteComponent;
  162. - (void)getWhite:(float *)white alpha:(float *)alpha;
  163.  
  164.  
  165. /* Get the CMYK components of NSDeviceCMYK colors.
  166. */
  167. - (float)cyanComponent;
  168. - (float)magentaComponent;
  169. - (float)yellowComponent;
  170. - (float)blackComponent;
  171. - (void)getCyan:(float *)cyan magenta:(float *)magenta yellow:(float *)yellow black:(float *)black alpha:(float *)alpha;
  172.  
  173.  
  174. /* Get the alpha component. For colors which do not have alpha components, this will return 1.0 (opaque).
  175. */
  176. - (float)alphaComponent;
  177.  
  178.  
  179. /* Pasteboard methods
  180. */
  181. + (NSColor *)colorFromPasteboard:(NSPasteboard *)pasteBoard;
  182. - (void)writeToPasteboard:(NSPasteboard *)pasteBoard;
  183.  
  184.  
  185. /* Draws the color and adorns it to indicate the type of color. Used by colorwells, swatches, and other UI objects that need to display colors. Implementation in NSColor simply draws the color (with an indication of transparency if the color isn't fully opaque); subclassers can draw more stuff as they see fit.
  186. */
  187. - (void)drawSwatchInRect:(NSRect)rect;
  188.  
  189.  
  190. /* Global flag for determining whether an application supports alpha.  This flag is consulted when an application imports alpha (through color dragging, for instance). The value of this flag also determines whether the color panel has an opacity slider. This value is YES by default, indicating that the opacity components of imported colors will be set to 1.0. If an application wants alpha, it can either set the "NSIgnoreAlpha" default to NO or call the set method below.
  191.  
  192. This method provides a global approach to removing alpha which might not always be appropriate. Applications which need to import alpha sometimes should set this flag to NO and explicitly make colors opaque in cases where it matters to them.
  193. */
  194. + (void)setIgnoresAlpha:(BOOL)flag;
  195. + (BOOL)ignoresAlpha;
  196.  
  197. @end
  198.  
  199.  
  200. @interface NSCoder(NSAppKitColorExtensions)
  201.  
  202. /* To decode NXColors... Will return nil if the archived color was "invalid" (written out by the kit in a few instances). Otherwise returns autoreleased NSColor. Can't write NSColors as NXColors, so we have no corresponding encode method.
  203. */
  204. - (NSColor *)decodeNXColor;
  205.  
  206. @end
  207.  
  208. #if !defined(STRICT_OPENSTEP)
  209.  
  210. APPKIT_EXTERN NSString *NSSystemColorsDidChangeNotification;
  211.  
  212. #endif /* !defined(STRICT_OPENSTEP) */
  213.