| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSGraphics.h NSGraphicsContext.h |
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.
+ graphicsContextWithAttributes:
+ graphicsContextWithBitmapImageRep:
+ graphicsContextWithGraphicsPort:flipped:
+ graphicsContextWithWindow:
+ setGraphicsState:
+ restoreGraphicsState
– restoreGraphicsState
+ saveGraphicsState
– saveGraphicsState
– focusStack Available in Mac OS X v10.0 through Mac OS X v10.5
– setFocusStack: Available in Mac OS X v10.0 through Mac OS X v10.5
– setCompositingOperation:
– compositingOperation
– setImageInterpolation:
– imageInterpolation
– setShouldAntialias:
– shouldAntialias
– setPatternPhase:
– patternPhase
Returns the current graphics context of the current thread.
+ (NSGraphicsContext *)currentContext
The current graphics context of the current thread.
Returns an instance of a concrete subclass of NSGraphicsContext.
NSGraphicsContext.hReturns a Boolean value that indicates whether the current context is drawing to the screen.
+ (BOOL)currentContextDrawingToScreen
This convenience method is equivalent to sending isDrawingToScreen to the result of currentContext.
NSGraphicsContext.hInstantiates and returns an instance of NSGraphicsContext using the specified attributes.
+ (NSGraphicsContext *)graphicsContextWithAttributes:(NSDictionary *)attributes
A dictionary of values associated with the keys described in “Attribute dictionary keys”. The attributes specify such things as representation format and destination.
A new NSGraphicsContext object or nil if the object could not be created.
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.
NSGraphicsContext.hInstantiates and returns a new graphics context using the supplied NSBitmapImageRep object as the context destination.
+ (NSGraphicsContext *)graphicsContextWithBitmapImageRep:(NSBitmapImageRep *)bitmapRep
The NSBitmapImageRep object to use as the destination.
The created NSGraphicsContext object or nil if the object could not be created.
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.
NSGraphicsContext.hInstantiates and returns a new graphics context from the given graphics port.
+ (NSGraphicsContext *)graphicsContextWithGraphicsPort:(void *)graphicsPort flipped:(BOOL)initialFlippedState
The graphics port used to create the graphics-context object. Typically graphicsPort is a CGContextRef (opaque type) object.
Specifies the receiver's initial flipped state. This is the value returned by isFlipped when no view has focus.
The created NSGraphicsContext object or nil if the object could not be created.
NSGraphicsContext.hCreates and returns a new graphics context for drawing into a window.
+ (NSGraphicsContext *)graphicsContextWithWindow:(NSWindow *)aWindow
The window object representing the window to use for drawing.
The created NSGraphicsContext object or nil if the object could not be created.
NSGraphicsContext.hPops a graphics context from the per-thread stack, makes it current, and sends the context a restoreGraphicsState message.
+ (void)restoreGraphicsState
NSGraphicsContext.hSaves the graphics state of the current graphics context.
+ (void)saveGraphicsState
This method sends the current graphics context a saveGraphicsState message and pushes the context onto the per-thread stack.
NSGraphicsContext.hSets the current graphics context of the current thread.
+ (void)setCurrentContext:(NSGraphicsContext *)context
The graphics-context object to set as the current one. This must be an instance of a concrete subclass of NSGraphicsContext.
NSGraphicsContext.hMakes the graphics context of the specified graphics state current, and resets graphics state.
+ (void)setGraphicsState:(NSInteger)graphicsState
The graphicState identifier must be created in the calling thread.
NSGraphicsContext.hReturns the receiver’s attributes.
- (NSDictionary *)attributes
The receiver’s attributes, if any.
Screen-based graphics contexts do not store attributes, even if you create them using graphicsContextWithAttributes:.
NSGraphicsContext.hReturns a CIContext object that you can use to render into the receiver.
- (CIContext *)CIContext
A CIContext object or nil if the object could not be created.
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.
NSGraphicsContext.hReturns the current rendering intent in the receiver’s graphics state.
- (NSColorRenderingIntent)colorRenderingIntent
An “Creating a Graphics Context”value that specifies the rendering intent currently used by the receiver. For possible values see “Color Rendering Intent Constants.”
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.
NSGraphicsContext.hReturns the receiver’s global compositing operation setting.
- (NSCompositingOperation)compositingOperation
The receiver’s global compositing operation setting. See NSCompositingOperation for valid constants.
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.
NSGraphicsContext.hForces any buffered operations or data to be sent to the receiver’s destination.
- (void)flushGraphics
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.
NSGraphicsContext.hReturns the low-level, platform-specific graphics context represented by the receiver.
- (void *)graphicsPort
In Mac OS X, this is the Core Graphics context, a CGContextRef object (opaque type).
NSGraphicsContext.hReturns a constant that specifies the receiver’s interpolation behavior.
- (NSImageInterpolation)imageInterpolation
The receiver’s interpolation (image smoothing) behavior.
The NSImageInterpolation constants are described in NSImageInterpolation.
NSGraphicsContext.hReturns a Boolean value that indicates whether the drawing destination is the screen.
- (BOOL)isDrawingToScreen
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.
NSGraphicsContext.hReturns a Boolean value that indicates the receiver’s flipped state.
- (BOOL)isFlipped
YES if the receiver is flipped, otherwise NO.
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.
NSGraphicsContext.hReturns the amount to offset the pattern color when filling the receiver.
- (NSPoint)patternPhase
The amount to offset the pattern color when filling the receiver.
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.
NSGraphicsContext.hRemoves 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
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.
NSGraphicsContext.hSaves the current graphics state and creates a new graphics state on the top of the stack.
- (void)saveGraphicsState
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.
NSGraphicsContext.hSets the rendering intent in the receiver’s graphics state.
- (void)setColorRenderingIntent:(NSColorRenderingIntent)renderingIntent
An “Creating a Graphics Context”value that specifies the rendering intent to be used. For possible values see “NSColorRenderingIntent.”
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
NSGraphicsContext.hSets the receiver’s global compositing operation.
- (void)setCompositingOperation:(NSCompositingOperation)operation
A constant that specifies a compositing operating. See NSCompositingOperation for valid constants.
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.
NSGraphicsContext.hSets the receiver’s interpolation behavior.
- (void)setImageInterpolation:(NSImageInterpolation)interpolation
A constant specifying the image-interpolation behavior. The NSImageInterpolation constants are described in NSImageInterpolation.
Note that this value is not part of the graphics state, so it cannot be reset using restoreGraphicsState.
NSGraphicsContext.hSets the amount to offset the pattern color when filling the receiver.
- (void)setPatternPhase:(NSPoint)phase
A point specifying the offset.
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.
NSGraphicsContext.hSets whether the receiver should use antialiasing.
- (void)setShouldAntialias:(BOOL)antialias
YES if the receiver should use antialiasing, otherwise NO.
This value is part of the graphics state and is restored by restoreGraphicsState.
NSGraphicsContext.hThese constants are dictionary keys used by graphicsContextWithAttributes: and attributes.
NSString *NSGraphicsContextDestinationAttributeName; NSString *NSGraphicsContextRepresentationFormatAttributeName;
NSGraphicsContextDestinationAttributeNameCan 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 Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSGraphicsContextRepresentationFormatAttributeNameSpecifies the destination file format.
This value should be retrieved only and not used to create a graphics context.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
These constants are possible values for the NSGraphicsContextRepresentationFormatAttributeName key in a graphic context’s attribute dictionary.
NSString *NSGraphicsContextPSFormat; NSString *NSGraphicsContextPDFFormat;
NSGraphicsContextPDFFormatDestination file format is PDF.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSGraphicsContextPSFormatDestination file format is PostScript.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
These interpolations are used by imageInterpolation and setImageInterpolation:.
enum {
NSImageInterpolationDefault,
NSImageInterpolationNone,
NSImageInterpolationLow,
NSImageInterpolationMedium,
NSImageInterpolationHigh
};
typedef NSUInteger NSImageInterpolation;
NSImageInterpolationDefaultUse the context’s default interpolation.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSImageInterpolationNoneNo interpolation.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSImageInterpolationLowFast, low-quality interpolation.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSImageInterpolationMediumMedium quality, slower than NSImageInterpolationLow.
Available in Mac OS X v10.6 and later.
Declared in NSGraphicsContext.h.
NSImageInterpolationHighSlower, higher-quality interpolation.
Available in Mac OS X v10.0 and later.
Declared in NSGraphicsContext.h.
NSGraphicsContext.hThese 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;
NSColorRenderingIntentDefaultUse the default rendering intent for the graphics context.
Available in Mac OS X v10.5 and later.
Declared in NSGraphics.h.
NSColorRenderingIntentAbsoluteColorimetricMap 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 Mac OS X v10.5 and later.
Declared in NSGraphics.h.
NSColorRenderingIntentRelativeColorimetricMap 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 Mac OS X v10.5 and later.
Declared in NSGraphics.h.
NSColorRenderingIntentPerceptualPreserve 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 Mac OS X v10.5 and later.
Declared in NSGraphics.h.
NSColorRenderingIntentSaturationPreserve 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 Mac OS X v10.5 and later.
Declared in NSGraphics.h.
Last updated: 2009-06-24