NSGraphicsContext Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSGraphics.h
NSGraphicsContext.h
Related sample code

Overview

The NSGraphicsContext class is the programmatic interface to objects that represent graphics contexts. A context can be thought of as a destination to which drawing and graphics state operations are sent for execution. Each graphics context contains its own graphics environment and state.

The NSGraphicsContext class is an abstract superclass for destination-specific graphics contexts. You obtain instances of concrete subclasses with the class methods currentContext, graphicsContextWithAttributes:, graphicsContextWithBitmapImageRep:, graphicsContextWithGraphicsPort:flipped:, and graphicsContextWithWindow:.

At any time there is the notion of the current context. The current context for the current thread may be set using setCurrentContext:.

Graphics contexts are maintained on a stack. You push a graphics context onto the stack by sending it a saveGraphicsState message, and pop it off the stack by sending it a restoreGraphicsState message. By sending restoreGraphicsState to an NSGraphicsContext object you remove it from the stack, and the next graphics context on the stack becomes the current graphics context.

Tasks

Creating a Graphics Context

Managing the Current Context

Managing the Graphics State

Testing the Drawing Destination

Getting Information About a Context

Flushing Graphics to the Context

Managing the Focus Stack

Configuring Rendering Options

Getting the Core Image Context

Managing the Color Rendering Intent

Class Methods

currentContext

Returns the current graphics context of the current thread.

+ (NSGraphicsContext *)currentContext
Return Value

The current graphics context of the current thread.

Discussion

Returns an instance of a concrete subclass of NSGraphicsContext.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

currentContextDrawingToScreen

Returns a Boolean value that indicates whether the current context is drawing to the screen.

+ (BOOL)currentContextDrawingToScreen
Return Value

YES if the current context is drawing to the screen, otherwise NO.

Discussion

This convenience method is equivalent to sending isDrawingToScreen to the result of currentContext.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

graphicsContextWithAttributes:

Instantiates and returns an instance of NSGraphicsContext using the specified attributes.

+ (NSGraphicsContext *)graphicsContextWithAttributes:(NSDictionary *)attributes
Parameters
attributes

A dictionary of values associated with the keys described in “Attribute dictionary keys”. The attributes specify such things as representation format and destination.

Return Value

A new NSGraphicsContext object or nil if the object could not be created.

Discussion

Use this method to create a graphics context for a window or bitmap destination. If you want to create a graphics context for a PDF or PostScript destination, do not use this method; instead, use the NSPrintOperation class to set up the printing environment needed to generate that type of information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

graphicsContextWithBitmapImageRep:

Instantiates and returns a new graphics context using the supplied NSBitmapImageRep object as the context destination.

+ (NSGraphicsContext *)graphicsContextWithBitmapImageRep:(NSBitmapImageRep *)bitmapRep
Parameters
bitmapRep

The NSBitmapImageRep object to use as the destination.

Return Value

The created NSGraphicsContext object or nil if the object could not be created.

Discussion

This method accepts only single plane NSBitmapImageRep instances. It is the equivalent of using graphicsContextWithAttributes: and passing bitmapRep as the value for the dictionary’s NSGraphicsContextDestinationAttributeName key.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

graphicsContextWithGraphicsPort:flipped:

Instantiates and returns a new graphics context from the given graphics port.

+ (NSGraphicsContext *)graphicsContextWithGraphicsPort:(void *)graphicsPort flipped:(BOOL)initialFlippedState
Parameters
graphicsPort

The graphics port used to create the graphics-context object. Typically graphicsPort is a CGContextRef (opaque type) object.

initialFlippedState

Specifies the receiver's initial flipped state. This is the value returned by isFlipped when no view has focus.

Return Value

The created NSGraphicsContext object or nil if the object could not be created.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

graphicsContextWithWindow:

Creates and returns a new graphics context for drawing into a window.

+ (NSGraphicsContext *)graphicsContextWithWindow:(NSWindow *)aWindow
Parameters
aWindow

The window object representing the window to use for drawing.

Return Value

The created NSGraphicsContext object or nil if the object could not be created.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

restoreGraphicsState

Pops a graphics context from the per-thread stack, makes it current, and sends the context a restoreGraphicsState message.

+ (void)restoreGraphicsState
Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

saveGraphicsState

Saves the graphics state of the current graphics context.

+ (void)saveGraphicsState
Discussion

This method sends the current graphics context a saveGraphicsState message and pushes the context onto the per-thread stack.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

setCurrentContext:

Sets the current graphics context of the current thread.

+ (void)setCurrentContext:(NSGraphicsContext *)context
Parameters
context

The graphics-context object to set as the current one. This must be an instance of a concrete subclass of NSGraphicsContext.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

setGraphicsState:

Makes the graphics context of the specified graphics state current, and resets graphics state.

+ (void)setGraphicsState:(NSInteger)graphicsState
Discussion

The graphicState identifier must be created in the calling thread.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

Instance Methods

attributes

Returns the receiver’s attributes.

- (NSDictionary *)attributes
Return Value

The receiver’s attributes, if any.

Discussion

Screen-based graphics contexts do not store attributes, even if you create them using graphicsContextWithAttributes:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

CIContext

Returns a CIContext object that you can use to render into the receiver.

- (CIContext *)CIContext
Return Value

A CIContext object or nil if the object could not be created.

Discussion

The CIContext object is created on demand and remains in existence for the lifetime of its owning NSGraphicsContext object. A CIContext object is an evaluation context for rendering a CIImage object through Quartz 2D or OpenGL. You use CIContextobjects in conjunction with CIFilter, CIImage, CIVector, and CIColor objects to take advantage of the built-in Core Image filters when processing images.

For more on CIContext objects and related Core Image objects, see Core Image Programming Guide.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSGraphicsContext.h

colorRenderingIntent

Returns the current rendering intent in the receiver’s graphics state.

- (NSColorRenderingIntent)colorRenderingIntent
Return Value

An “Creating a Graphics Context”value that specifies the rendering intent currently used by the receiver. For possible values see “NSColorRenderingIntent.”

Discussion

The rendering intent specifies how Cocoa should handle colors that are not located within the gamut of the destination color space of a graphics context.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGraphicsContext.h

compositingOperation

Returns the receiver’s global compositing operation setting.

- (NSCompositingOperation)compositingOperation
Return Value

The receiver’s global compositing operation setting. See NSCompositingOperation for valid constants.

Discussion

The compositing operation is a global attribute of the graphics context and affects drawing operations that do not take an explicit compositing operation parameter. For methods that do take an explicit compositing operation parameter, the value of that parameter supersedes the global value.

The compositing operations are related to (but different from) the blend mode settings used in Quartz. Only the default compositing operation (NSCompositeCopy) is supported for PDF or PostScript content.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

flushGraphics

Forces any buffered operations or data to be sent to the receiver’s destination.

- (void)flushGraphics
Discussion

Graphics contexts use buffers to queue pending operations but for efficiency reasons may not always empty those buffers immediately. This method forces the buffers to be emptied.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

graphicsPort

Returns the low-level, platform-specific graphics context represented by the receiver.

- (void *)graphicsPort
Discussion

In OS X, this is the Core Graphics context, a CGContextRef object (opaque type).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

imageInterpolation

Returns a constant that specifies the receiver’s interpolation behavior.

- (NSImageInterpolation)imageInterpolation
Return Value

The receiver’s interpolation (image smoothing) behavior.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

isDrawingToScreen

Returns a Boolean value that indicates whether the drawing destination is the screen.

- (BOOL)isDrawingToScreen
Return Value

YES if the drawing destination is the screen, otherwise NO.

Discussion

A return value of NO may mean that the drawing destination is a printer, but the destination may also be a PDF or EPS file. If this method returns NO, you can call attributes to see if additional information is available about the drawing destination.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

isFlipped

Returns a Boolean value that indicates the receiver’s flipped state.

- (BOOL)isFlipped
Return Value

YES if the receiver is flipped, otherwise NO.

Discussion

The state is determined by sending isFlipped to the receiver’s view that has focus. If no view has focus, returns NO unless the receiver is instantiated using graphicsContextWithGraphicsPort:flipped: specifying YES as the flipped parameter.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSGraphicsContext.h

patternPhase

Returns the amount to offset the pattern color when filling the receiver.

- (NSPoint)patternPhase
Return Value

The amount to offset the pattern color when filling the receiver.

Discussion

The pattern phase is a translation (width, height) applied before a pattern is drawn in the current context and is part of the saved graphics state of the context. The default pattern phase is (0,0). Setting the pattern phase has the effect of temporarily changing the pattern matrix of any pattern you decide to draw. For example, setting the pattern phase to (2,3) has the effect of moving the start of pattern cell tiling to the point (2,3) in default user space.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSGraphicsContext.h

restoreGraphicsState

Removes the receiver’s graphics state from the top of the graphics state stack and makes the next graphics state the current graphics state.

- (void)restoreGraphicsState
Discussion

This method must have been preceded with a saveGraphicsState message to add the graphics state to the stack. Invocations of saveGraphicsState and restoreGraphicsState methods may be nested.

Restoring the graphics state restores such attributes as the current drawing style, transformation matrix, color, and font of the original graphics state.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

saveGraphicsState

Saves the current graphics state and creates a new graphics state on the top of the stack.

- (void)saveGraphicsState
Discussion

The new graphics state is a copy of the previous state that can be modified to handle new drawing operations.

Saving the graphics state saves such attributes as the current drawing style, transformation matrix, color, and font. To set drawing style attributes, use the methods of NSBezierPath. Other attributes are accessed through appropriate objects such as NSAffineTransform, NSColor, and NSFont.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

setColorRenderingIntent:

Sets the rendering intent in the receiver’s graphics state.

- (void)setColorRenderingIntent:(NSColorRenderingIntent)renderingIntent
Parameters
renderingIntent

An “Creating a Graphics Context”value that specifies the rendering intent to be used. For possible values see “NSColorRenderingIntent.”

Discussion

The rendering intent specifies how Cocoa should handle colors that are not located within the gamut of the destination color space of a graphics context. If you do not explicitly set the rendering intent, and sampled images are being drawn, NSGraphicsContext uses perceptual rendering intent. Otherwise, NSGraphicsContext uses relative colorimetric rendering intent

Availability
  • Available in OS X v10.5 and later.
Declared In
NSGraphicsContext.h

setCompositingOperation:

Sets the receiver’s global compositing operation.

- (void)setCompositingOperation:(NSCompositingOperation)operation
Parameters
operation

A constant that specifies a compositing operating. See NSCompositingOperation for valid constants.

Discussion

The compositing operation is a global attribute of the graphics context and affects drawing operations that do not take an explicit compositing operation parameter. For methods that do take an explicit compositing operation parameter, the value of that parameter supersedes the global value.

The compositing operations are related to (but different from) the blend mode settings used in Quartz. Only the default compositing operation (NSCompositeCopy) is supported when rendering PDF or PostScript content.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

setImageInterpolation:

Sets the receiver’s interpolation behavior.

- (void)setImageInterpolation:(NSImageInterpolation)interpolation
Parameters
interpolation

A constant specifying the image-interpolation behavior.

Discussion

Note that this value is not part of the graphics state, so it cannot be reset using restoreGraphicsState.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

setPatternPhase:

Sets the amount to offset the pattern color when filling the receiver.

- (void)setPatternPhase:(NSPoint)phase
Parameters
phase

A point specifying the offset.

Discussion

Use this method when you need to line up the pattern color with another pattern, such as the pattern in a superview.

The pattern phase is a translation (width, height) applied before a pattern is drawn in the current context and is part of the saved graphics state of the context. The default pattern phase is (0,0). Setting the pattern phase has the effect of temporarily changing the pattern matrix of any pattern you decide to draw. For example, setting the pattern phase to (2,3) has the effect of moving the start of pattern cell tiling to the point (2,3) in default user space.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSGraphicsContext.h

setShouldAntialias:

Sets whether the receiver should use antialiasing.

- (void)setShouldAntialias:(BOOL)antialias
Parameters
antialias

YES if the receiver should use antialiasing, otherwise NO.

Discussion

This value is part of the graphics state and is restored by restoreGraphicsState.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSGraphicsContext.h

shouldAntialias

Returns a Boolean value that indicates whether the receiver uses antialiasing.

- (BOOL)shouldAntialias
Return Value

YES if the receiver uses antialiasing, otherwise NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphicsContext.h

Constants

Attribute dictionary keys

These constants are dictionary keys used by graphicsContextWithAttributes: and attributes.

NSString *NSGraphicsContextDestinationAttributeName;
NSString *NSGraphicsContextRepresentationFormatAttributeName;
Constants
NSGraphicsContextDestinationAttributeName

Can be an instance of NSWindow or NSBitmapImageRep when creating a graphics context.

When determining the type of a graphics context, this value can be an NSMutableData, NSString, or NSURL object.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSGraphicsContextRepresentationFormatAttributeName

Specifies the destination file format.

This value should be retrieved only and not used to create a graphics context.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

Representation format attribute keys

These constants are possible values for the NSGraphicsContextRepresentationFormatAttributeName key in a graphic context’s attribute dictionary.

NSString *NSGraphicsContextPSFormat;
NSString *NSGraphicsContextPDFFormat;
Constants
NSGraphicsContextPDFFormat

Destination file format is PDF.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSGraphicsContextPSFormat

Destination file format is PostScript.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSImageInterpolation

These interpolations are used by imageInterpolation and setImageInterpolation:.

enum {
   NSImageInterpolationDefault = 0,
   NSImageInterpolationNone = 1,
   NSImageInterpolationLow = 2,
   NSImageInterpolationMedium = 4,
   NSImageInterpolationHigh = 3
};
typedef NSUInteger NSImageInterpolation;
Constants
NSImageInterpolationDefault

Use the context’s default interpolation.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSImageInterpolationNone

No interpolation.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSImageInterpolationLow

Fast, low-quality interpolation.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSImageInterpolationMedium

Medium quality, slower than NSImageInterpolationLow.

Available in OS X v10.6 and later.

Declared in NSGraphicsContext.h.

NSImageInterpolationHigh

Highest quality, slower than NSImageInterpolationMedium.

Available in OS X v10.0 and later.

Declared in NSGraphicsContext.h.

NSColorRenderingIntent

These constants specify how Cocoa should handle colors that are not located within the destination color space of a graphics context. These constants are used by the methods setColorRenderingIntent: and colorRenderingIntent.

enum {
   NSColorRenderingIntentDefault,
   NSColorRenderingIntentAbsoluteColorimetric,
   NSColorRenderingIntentRelativeColorimetric,
   NSColorRenderingIntentPerceptual,
   NSColorRenderingIntentSaturation
};
typedef NSInteger NSColorRenderingIntent;
Constants
NSColorRenderingIntentDefault

Use the default rendering intent for the graphics context.

Available in OS X v10.5 and later.

Declared in NSGraphics.h.

NSColorRenderingIntentAbsoluteColorimetric

Map colors outside of the gamut of the output device to the closest possible match inside the gamut of the output device.

This operation can produce a clipping effect, where two different color values in the gamut of the graphics context are mapped to the same color value in the output device’s gamut. Unlike the relative colorimetric, absolute colorimetric does not modify colors inside the gamut of the output device.

Available in OS X v10.5 and later.

Declared in NSGraphics.h.

NSColorRenderingIntentRelativeColorimetric

Map colors outside of the gamut of the output device to the closest possible match inside the gamut of the output device.

This operation can produce a clipping effect, where two different color values in the gamut of the graphics context are mapped to the same color value in the output device’s gamut. The relative colorimetric shifts all colors (including those within the gamut) to account for the difference between the white point of the graphics context and the white point of the output device.

Available in OS X v10.5 and later.

Declared in NSGraphics.h.

NSColorRenderingIntentPerceptual

Preserve the visual relationship between colors by compressing the gamut of the graphics context to fit inside the gamut of the output device.

Perceptual intent is good for photographs and other complex, detailed images.

Available in OS X v10.5 and later.

Declared in NSGraphics.h.

NSColorRenderingIntentSaturation

Preserve the relative saturation value of the colors when converting into the gamut of the output device.

The result is an image with bright, saturated colors. Saturation intent is good for reproducing images with low detail, such as presentation charts and graphs.

Available in OS X v10.5 and later.

Declared in NSGraphics.h.