NSImageDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSImage.h

Overview

The NSImageDelegate protocol defines the optional methods implemented by delegates of NSImage objects.

Tasks

Responding to Drawing Failure

Managing Incremental Loads

Instance Methods

image:didLoadPartOfRepresentation:withValidRows:

During incremental loading, this method is called repeatedly to inform the delegate that more of the image data is available.

- (void)image:(NSImage *)image didLoadPartOfRepresentation:(NSImageRep *)rep withValidRows:(NSInteger)rows
Parameters
image

The image object whose contents are being loaded.

rep

The image representation object that is receiving and processing the image data.

rows

The number of rows of data that have been decompressed.

Discussion

This method is optional; incremental loading will continue if the delegate does not implement it.

Availability
  • Available in OS X v10.2 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSImage.h

image:didLoadRepresentation:withStatus:

For incremental loading, this method is invoked when the specified image has been loaded and decompressed as fully as is possible.

- (void)image:(NSImage *)image didLoadRepresentation:(NSImageRep *)rep withStatus:(NSImageLoadStatus)status
Parameters
image

The image object whose contents are being loaded.

rep

The image representation object that loaded the image data.

status

The status of the load operation. For a list of possible values, see NSImageLoadStatus in NSImage Class Reference.

Discussion

The delegate must implement this method if it wants to support the incremental loading of images. In that case, you must also set up the image object to be loaded lazily, by initializing it using the initByReferencingFile: or initByReferencingURL: method.

If an error occurs during downloading or decompression, the status parameter is set to NSImageLoadStatusInvalidData, NSImageLoadStatusUnexpectedEOF, or NSImageLoadStatusReadError. If the download was cancelled, the status parameter is set to NSImageLoadStatusCancelled.

Availability
  • Available in OS X v10.2 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSImage.h

image:didLoadRepresentationHeader:

During incremental loading, this method is called once enough data has been read to determine the size of the image.

- (void)image:(NSImage *)image didLoadRepresentationHeader:(NSImageRep *)rep
Parameters
image

The image object whose contents are being loaded.

rep

The image representation object that is receiving and processing the image data.

Discussion

By the time this method is called, the NSBitmapImageRep object specified in the rep parameter is valid and has allocated the memory needed to store the bitmap. The bitmap itself is filled with the image's background color. This method is optional; incremental loading will continue if the delegate does not implement it.

Availability
  • Available in OS X v10.2 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSImage.h

image:willLoadRepresentation:

For incremental loading, this method is invoked when you first attempt to draw the image or otherwise access the bitmap data.

- (void)image:(NSImage *)image willLoadRepresentation:(NSImageRep *)rep
Parameters
image

The image object whose contents need to be loaded.

rep

The image representation object that was accessed.

Discussion

Downloading of the image begins immediately after this method returns. This method is optional; incremental loading will continue if the delegate does not implement it.

Availability
  • Available in OS X v10.2 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSImage.h

imageDidNotDraw:inRect:

Sent to the delegate when the image object is unable, for whatever reason, to lock focus on its image or draw in the specified rectangle.

- (NSImage *)imageDidNotDraw:(id)sender inRect:(NSRect)aRect
Parameters
sender

The NSImage object that encountered the problem.

aRect

The rectangle that the image object was attempting to draw.

Return Value

An NSImage to draw in place of the one in sender, or nil if the delegate wants to draw the image itself.

Discussion

The delegate can do one of the following:

  • Return another NSImage object to draw in the sender’s place.

  • Draw the image itself and return nil,.

  • Simply return nil to indicate that sender should give up on the attempt at drawing the image.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSImage.h