1 /* 2 NSImage.h 3 4 Load, manipulate and display images 5 6 Copyright (C) 1996-2016 Free Software Foundation, Inc. 7 8 Written by: Adam Fedor <fedor@colorado.edu> 9 Date: Feb 1996 10 11 This file is part of the GNUstep GUI Library. 12 13 This library is free software; you can redistribute it and/or 14 modify it under the terms of the GNU Lesser General Public 15 License as published by the Free Software Foundation; either 16 version 2 of the License, or (at your option) any later version. 17 18 This library is distributed in the hope that it will be useful, 19 but WITHOUT ANY WARRANTY; without even the implied warranty of 20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 Lesser General Public License for more details. 22 23 You should have received a copy of the GNU Lesser General Public 24 License along with this library; see the file COPYING.LIB. 25 If not, see <http://www.gnu.org/licenses/> or write to the 26 Free Software Foundation, 51 Franklin Street, Fifth Floor, 27 Boston, MA 02110-1301, USA. 28 */ 29 30 #ifndef _GNUstep_H_NSImage 31 #define _GNUstep_H_NSImage 32 #import <GNUstepBase/GSVersionMacros.h> 33 34 #import <AppKit/NSGraphicsContext.h> 35 #import <Foundation/NSBundle.h> 36 #import <AppKit/NSBitmapImageRep.h> 37 38 @class NSString; 39 @class NSMutableArray; 40 @class NSData; 41 @class NSURL; 42 43 @class NSPasteboard; 44 @class NSImageRep; 45 @class NSColor; 46 @class NSView; 47 48 /* Named images */ 49 50 APPKIT_EXPORT NSString *NSImageNameMultipleDocuments; 51 52 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST) 53 APPKIT_EXPORT NSString *NSImageNameUserAccounts; 54 APPKIT_EXPORT NSString *NSImageNamePreferencesGeneral; 55 APPKIT_EXPORT NSString *NSImageNameAdvanced; 56 APPKIT_EXPORT NSString *NSImageNameInfo; 57 APPKIT_EXPORT NSString *NSImageNameFontPanel; 58 APPKIT_EXPORT NSString *NSImageNameColorPanel; 59 #endif 60 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 61 APPKIT_EXPORT NSString *NSImageNameTrashEmpty; 62 APPKIT_EXPORT NSString *NSImageNameTrashFull; 63 APPKIT_EXPORT NSString *NSImageNameCaution; 64 #endif 65 66 /** Defines how an NSImage is to be cached. Possible values are: 67 * <list> 68 * <item>NSImageCacheDefault</item> 69 * <item>NSImageCacheAlways</item> 70 * <item>NSImageCacheBySize</item> 71 * <item>NSImageCacheNever</item> 72 * </list> 73 * <p>See Also:</p> 74 * <list> 75 * <item>-setCacheMode:</item> 76 * <item>-cacheMode</item> 77 * </list> 78 */ 79 typedef enum { 80 NSImageCacheDefault, 81 NSImageCacheAlways, 82 NSImageCacheBySize, 83 NSImageCacheNever 84 } NSImageCacheMode; 85 86 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST) 87 APPKIT_EXTERN NSString *const NSImageNameQuickLookTemplate; 88 APPKIT_EXTERN NSString *const NSImageNameBluetoothTemplate; 89 APPKIT_EXTERN NSString *const NSImageNameIChatTheaterTemplate; 90 APPKIT_EXTERN NSString *const NSImageNameSlideshowTemplate; 91 APPKIT_EXTERN NSString *const NSImageNameActionTemplate; 92 APPKIT_EXTERN NSString *const NSImageNameSmartBadgeTemplate; 93 APPKIT_EXTERN NSString *const NSImageNameIconViewTemplate; 94 APPKIT_EXTERN NSString *const NSImageNameListViewTemplate; 95 APPKIT_EXTERN NSString *const NSImageNameColumnViewTemplate; 96 APPKIT_EXTERN NSString *const NSImageNameFlowViewTemplate; 97 APPKIT_EXTERN NSString *const NSImageNamePathTemplate; 98 APPKIT_EXTERN NSString *const NSImageNameInvalidDataFreestandingTemplate; 99 APPKIT_EXTERN NSString *const NSImageNameLockLockedTemplate; 100 APPKIT_EXTERN NSString *const NSImageNameLockUnlockedTemplate; 101 APPKIT_EXTERN NSString *const NSImageNameGoRightTemplate; 102 APPKIT_EXTERN NSString *const NSImageNameGoLeftTemplate; 103 APPKIT_EXTERN NSString *const NSImageNameRightFacingTriangleTemplate; 104 APPKIT_EXTERN NSString *const NSImageNameLeftFacingTriangleTemplate; 105 APPKIT_EXTERN NSString *const NSImageNameAddTemplate; 106 APPKIT_EXTERN NSString *const NSImageNameRemoveTemplate; 107 APPKIT_EXTERN NSString *const NSImageNameRevealFreestandingTemplate; 108 APPKIT_EXTERN NSString *const NSImageNameFollowLinkFreestandingTemplate; 109 APPKIT_EXTERN NSString *const NSImageNameEnterFullScreenTemplate; 110 APPKIT_EXTERN NSString *const NSImageNameExitFullScreenTemplate; 111 APPKIT_EXTERN NSString *const NSImageNameStopProgressTemplate; 112 APPKIT_EXTERN NSString *const NSImageNameStopProgressFreestandingTemplate; 113 APPKIT_EXTERN NSString *const NSImageNameRefreshTemplate; 114 APPKIT_EXTERN NSString *const NSImageNameRefreshFreestandingTemplate; 115 APPKIT_EXTERN NSString *const NSImageNameBonjour; 116 APPKIT_EXTERN NSString *const NSImageNameComputer; 117 APPKIT_EXTERN NSString *const NSImageNameFolderBurnable; 118 APPKIT_EXTERN NSString *const NSImageNameFolderSmart; 119 APPKIT_EXTERN NSString *const NSImageNameNetwork; 120 #endif 121 122 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 123 APPKIT_EXTERN NSString *const NSImageNameFolder; 124 #endif 125 126 @interface NSImage : NSObject <NSCoding, NSCopying> 127 { 128 // Attributes 129 NSString *_name; 130 NSString *_fileName; 131 NSSize _size; 132 struct __imageFlags { 133 unsigned archiveByName: 1; 134 unsigned scalable: 1; 135 unsigned dataRetained: 1; 136 unsigned flipDraw: 1; 137 unsigned sizeWasExplicitlySet: 1; 138 unsigned useEPSOnResolutionMismatch: 1; 139 unsigned colorMatchPreferred: 1; 140 unsigned multipleResolutionMatching: 1; 141 unsigned cacheSeparately: 1; 142 unsigned unboundedCacheDepth: 1; 143 unsigned syncLoad: 1; 144 } _flags; 145 NSMutableArray *_reps; 146 NSColor *_color; 147 NSView *_lockedView; 148 id _delegate; 149 NSImageCacheMode _cacheMode; 150 } 151 152 // 153 // Initializing a New NSImage Instance 154 // 155 /** Initializes and returns a NSImage from the NSString fileName. 156 */ 157 - (id) initByReferencingFile: (NSString*)fileName; 158 159 /** Initializes and returns a new NSImage from the file 160 * fileName. fileName should be an absolute path. 161 * <p>See Also:</p> 162 * <list> 163 * <item>[NSImageRep+imageRepsWithContentsOfFile:]</item> 164 * </list> 165 */ 166 167 - (id) initWithContentsOfFile: (NSString*)fileName; 168 169 /** Initializes and returns a new NSImage from the NSData data. 170 * <p>See Also:</p> 171 * <list> 172 * <item>[NSBitmapImageRep+imageRepWithData:]</item> 173 * <item>[NSEPSImageRep+imageRepWithData:]</item> 174 * </list> 175 */ 176 - (id) initWithData: (NSData*)data; 177 178 /** Initializes and returns a new NSImage from the data in pasteboard. 179 * The pasteboard types can be whose defined in 180 * [NSImageRep+imagePasteboardTypes] or NSFilenamesPboardType 181 * <p>See Also:</p> 182 * <list> 183 * <item>[NSImageRep+imageRepsWithPasteboard:]</item> 184 * </list> 185 */ 186 - (id) initWithPasteboard: (NSPasteboard*)pasteboard; 187 188 /** Initialize and returns a new NSImage with aSize as specified 189 * size. 190 * <p>See Also:</p> 191 * <list> 192 * <item>-setSize:</item> 193 * <item>-size</item> 194 * </list> 195 */ 196 - (id) initWithSize: (NSSize)aSize; 197 198 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 199 - (id)initWithBitmapHandle:(void *)bitmap; 200 - (id)initWithContentsOfURL:(NSURL *)anURL; 201 - (id)initWithIconHandle:(void *)icon; 202 #endif 203 204 // 205 // Setting the Size of the Image 206 // 207 /** Sets the NSImage size to aSize. Changing the size recreate 208 * the cache. 209 * <p>See Also:</p> 210 * <list> 211 * <item>-size</item> 212 * <item>-initWithSize:</item> 213 * </list> 214 */ 215 - (void) setSize: (NSSize)aSize; 216 217 /** Returns NSImage size if the size have been set. Returns the 218 * size of the best representation otherwise. 219 * <p>See Also:</p> 220 * <list> 221 * <item>-setSize:</item> 222 * <item>-initWithSize:</item> 223 * </list> 224 */ 225 - (NSSize) size; 226 227 // 228 // Referring to Images by Name 229 // 230 /** Returns the NSImage named aName. The search is done in the main bundle 231 * first and then in the usual images directories. 232 */ 233 + (id) imageNamed: (NSString*)aName; 234 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 235 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 236 + (NSImage*) _standardImageWithName: (NSString*)name; 237 #endif 238 #endif 239 240 /** Sets aName as the name of the receiver. 241 */ 242 - (BOOL) setName: (NSString*)aName; 243 244 /** Returns the name of the receiver. 245 */ 246 - (NSString*) name; 247 248 // 249 // Specifying the Image 250 // 251 /** Adds the NSImageRep imageRep to the NSImage's representations array. 252 * <p>See Also:</p> 253 * <list> 254 * <item>-addRepresentations:</item> 255 * <item>-removeRepresentation:</item> 256 * </list> 257 */ 258 - (void) addRepresentation: (NSImageRep*)imageRep; 259 260 /** Adds the NSImageRep array imageRepArray to the NSImage's 261 * representations array. 262 * <p>See Also:</p> 263 * <list> 264 * <item>-addRepresentation:</item> 265 * <item>-removeRepresentation:</item> 266 * </list> 267 */ 268 - (void) addRepresentations: (NSArray*)imageRepArray; 269 270 /** Locks the focus on the best representation. 271 * <p>See Also:</p> 272 * <list> 273 * <item>-lockFocusOnRepresentation:</item> 274 * </list> 275 */ 276 - (void) lockFocus; 277 278 /** Locks the focus in the imageRep. If imageRep is nil this method 279 * locks the focus on the best representation. 280 */ 281 - (void) lockFocusOnRepresentation: (NSImageRep*)imageRep; 282 283 /** Unlocks the focus on the receiver. 284 * <p>See Also:</p> 285 * <list> 286 * <item>-lockFocus</item> 287 * </list> 288 */ 289 - (void) unlockFocus; 290 291 // 292 // Using the Image 293 // 294 - (void) compositeToPoint: (NSPoint)aPoint 295 operation: (NSCompositingOperation)op; 296 - (void) compositeToPoint: (NSPoint)aPoint 297 fromRect: (NSRect)aRect 298 operation: (NSCompositingOperation)op; 299 - (void) dissolveToPoint: (NSPoint)aPoint 300 fraction: (CGFloat)aFloat; 301 - (void) dissolveToPoint: (NSPoint)aPoint 302 fromRect: (NSRect)aRect 303 fraction: (CGFloat)aFloat; 304 305 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 306 - (void) compositeToPoint: (NSPoint)aPoint 307 fromRect: (NSRect)srcRect 308 operation: (NSCompositingOperation)op 309 fraction: (CGFloat)delta; 310 - (void) compositeToPoint: (NSPoint)aPoint 311 operation: (NSCompositingOperation)op 312 fraction: (CGFloat)delta; 313 #endif 314 315 // 316 // Choosing Which Image Representation to Use 317 // 318 /** Sets the preferred representation of a NSImage. 319 * <p>See Also:</p> 320 * <list> 321 * <item>-prefersColorMatch</item> 322 * <item>-bestRepresentationForDevice:</item> 323 * </list> 324 */ 325 - (void) setPrefersColorMatch: (BOOL)flag; 326 327 /** Returns YES if color matching is the preferred representation 328 * and NO otherwise. 329 */ 330 - (BOOL) prefersColorMatch; 331 - (void) setUsesEPSOnResolutionMismatch: (BOOL)flag; 332 - (BOOL) usesEPSOnResolutionMismatch; 333 - (void) setMatchesOnMultipleResolution: (BOOL)flag; 334 - (BOOL) matchesOnMultipleResolution; 335 336 // 337 // Getting the Representations 338 // 339 /** Finds the best representation for deviceDescription. If 340 * deviceDescription is nil, it guesses where drawing is taking 341 * place and finds the best representation. 342 */ 343 - (NSImageRep*) bestRepresentationForDevice: (NSDictionary*)deviceDescription; 344 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 345 /** 346 * Finds the best representation for drawing in the specified rect. 347 * 348 * context and hints are currently ignored. 349 */ 350 - (NSImageRep *)bestRepresentationForRect: (NSRect)rect 351 context: (NSGraphicsContext *)context 352 hints: (NSDictionary *)hints; 353 #endif 354 355 - (NSArray*) representations; 356 357 /** Remove the NSImageRep imageRep from the NSImage's representations 358 * array 359 * <p>See Also:</p> 360 * <list> 361 * <item>-addRepresentations:</item> 362 * <item>-addRepresentation:</item> 363 * </list> 364 */ 365 - (void) removeRepresentation: (NSImageRep*)imageRep; 366 367 // 368 // Determining How the Image is Stored 369 // 370 - (void) setCachedSeparately: (BOOL)flag; 371 - (BOOL) isCachedSeparately; 372 - (void) setDataRetained: (BOOL)flag; 373 - (BOOL) isDataRetained; 374 - (void) setCacheDepthMatchesImageDepth: (BOOL)flag; 375 - (BOOL) cacheDepthMatchesImageDepth; 376 - (void) setCacheMode: (NSImageCacheMode)mode; 377 - (NSImageCacheMode) cacheMode; 378 379 // 380 // Drawing 381 // 382 - (BOOL) drawRepresentation: (NSImageRep*)imageRep 383 inRect: (NSRect)aRect; 384 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 385 /** Calls -drawAtPoint:fromRect:operation:fraction: with 386 * <code>dstRect</code> given by <code>point</code> and the size of 387 * <code>srcRect</code>. 388 */ 389 - (void) drawAtPoint: (NSPoint)point 390 fromRect: (NSRect)srcRect 391 operation: (NSCompositingOperation)op 392 fraction: (CGFloat)delta; 393 394 /** <p>Takes the part of the receiver given by <code>srcRect</code> and 395 * draws it in <code>dstRect</code> in the current coordinate system, 396 * transforming the image as necessary. 397 * </p><p> 398 * The image is drawn as if it was drawn to a cleared window, then 399 * dissolved using the fraction <code>delta</code> to another cleared 400 * window, and finally composited using <code>op</code> to the 401 * destination. 402 * </p><p> 403 * Note that compositing and dissolving doesn't work on all devices 404 * (printers, in particular). 405 * </p> 406 */ 407 - (void) drawInRect: (NSRect)dstRect 408 fromRect: (NSRect)srcRect 409 operation: (NSCompositingOperation)op 410 fraction: (CGFloat)delta; 411 #endif 412 413 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 414 415 - (void) drawInRect: (NSRect)dstRect 416 fromRect: (NSRect)srcRect 417 operation: (NSCompositingOperation)op 418 fraction: (CGFloat)delta 419 respectFlipped: (BOOL)respectFlipped 420 hints: (NSDictionary*)hints; 421 422 #endif 423 424 /** 425 * <p>Draws the entire image in <code>rect</code> scaling if needed.<br> 426 * Drawing is done using <code>NSCompositeSourceOver</code>. 427 * </p> 428 */ 429 430 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 431 - (void) drawInRect: (NSRect)rect; 432 #endif 433 434 // 435 // Determining How the Image is Drawn 436 // 437 - (BOOL) isValid; 438 - (void) setScalesWhenResized: (BOOL)flag; 439 - (BOOL) scalesWhenResized; 440 441 /** Sets the color of the NSImage's background to aColor. 442 * <p>See Also:</p> 443 * <list> 444 * <item>-backgroundColor</item> 445 * </list> 446 */ 447 - (void) setBackgroundColor: (NSColor*)aColor; 448 449 /** Returns the color of the NSImage's background. 450 * <p>See Also:</p> 451 * <list> 452 * <item>-setBackgroundColor:</item> 453 * </list> 454 */ 455 - (NSColor*) backgroundColor; 456 - (void) recache; 457 - (void) setFlipped: (BOOL)flag; 458 - (BOOL) isFlipped; 459 460 // 461 // Assigning a Delegate 462 // 463 - (void) setDelegate: (id)anObject; 464 - (id) delegate; 465 466 // 467 // Producing TIFF Data for the Image 468 // 469 - (NSData*) TIFFRepresentation; 470 - (NSData*) TIFFRepresentationUsingCompression: (NSTIFFCompression)comp 471 factor: (float)aFloat; 472 473 // 474 // Managing NSImageRep Subclasses 475 // 476 + (NSArray*) imageUnfilteredFileTypes; 477 + (NSArray*) imageUnfilteredPasteboardTypes; 478 479 // 480 // Testing Image Data Sources 481 // 482 + (BOOL) canInitWithPasteboard: (NSPasteboard*)pasteboard; 483 + (NSArray*) imageFileTypes; 484 + (NSArray*) imagePasteboardTypes; 485 486 @end 487 488 @interface NSImage (GSQuartz) 489 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 490 - (CGImageRef)CGImageForProposedRect: (NSRect *)proposedDestRect 491 context: (NSGraphicsContext *)referenceContext 492 hints: (NSDictionary *)hints; 493 #endif 494 @end 495 496 @interface NSBundle (NSImageAdditions) 497 498 - (NSString*) pathForImageResource: (NSString*)name; 499 500 @end 501 502 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) 503 /* 504 * A formal protocol that duplicates the informal protocol for delegates. 505 */ 506 @protocol GSImageDelegateProtocol 507 508 - (NSImage*) imageDidNotDraw: (id)sender 509 inRect: (NSRect)aRect; 510 511 @end 512 #endif 513 514 #endif // _GNUstep_H_NSImage 515 516