Mac Developer Library

Developer

AppKit Framework Reference NSGraphicsContext Class Reference

Options
Deployment Target:

On This Page
Language:

NSGraphicsContext

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.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Instantiates and returns an instance of NSGraphicsContext using the specified attributes.

    Declaration

    Swift

    init?(attributes attributes: [NSObject : AnyObject]) -> NSGraphicsContext

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init?(bitmapImageRep bitmapRep: NSBitmapImageRep) -> NSGraphicsContext

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    init(graphicsPort graphicsPort: UnsafeMutablePointer<Void>, flipped initialFlippedState: Bool) -> NSGraphicsContext

    Objective-C

    + (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 flipped when no view has focus.

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    init(window aWindow: NSWindow) -> NSGraphicsContext

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current graphics context of the current thread.

    Declaration

    Swift

    class func currentContext() -> NSGraphicsContext?

    Objective-C

    + (NSGraphicsContext *)currentContext

    Return Value

    The current graphics context of the current thread.

    Discussion

    Returns an instance of a concrete subclass of NSGraphicsContext.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the current graphics context of the current thread.

    Declaration

    Swift

    class func setCurrentContext(_ context: NSGraphicsContext?)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • graphicsPort graphicsPort (OS X v10.10) Property

    The low-level, platform-specific graphics context represented by the graphic port. (read-only)

    Declaration

    Swift

    var graphicsPort: UnsafeMutablePointer<Void> { get }

    Objective-C

    @property(readonly) void *graphicsPort

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    class func setGraphicsState(_ gState: Int)

    Objective-C

    + (void)setGraphicsState:(NSInteger)gState

    Discussion

    The graphicState identifier must be created in the calling thread.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    class func restoreGraphicsState()

    Objective-C

    + (void)restoreGraphicsState

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func restoreGraphicsState()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Saves the graphics state of the current graphics context.

    Declaration

    Swift

    class func saveGraphicsState()

    Objective-C

    + (void)saveGraphicsState

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func saveGraphicsState()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func currentContextDrawingToScreen() -> Bool

    Objective-C

    + (BOOL)currentContextDrawingToScreen

    Return Value

    YEStrue if the current context is drawing to the screen, otherwise NOfalse.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the drawing destination is the screen. (read-only)

    Declaration

    Swift

    var drawingToScreen: Bool { get }

    Objective-C

    @property(getter=isDrawingToScreen, readonly) BOOL drawingToScreen

    Discussion

    YEStrue if the drawing destination is the screen. If the value of the property is NOfalse may mean that the drawing destination is a printer, but the destination may also be a PDF or EPS file. You can call attributes to see if additional information is available about the drawing destination.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Is a Attributes used to create this instance (read-only)

    Declaration

    Swift

    var attributes: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *attributes

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • flipped flipped Property

    A Boolean value indicating the receiver’s flipped state. (read-only)

    Declaration

    Swift

    var flipped: Bool { get }

    Objective-C

    @property(getter=isFlipped, readonly) BOOL flipped

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    func flushGraphics()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • focusStack - focusStack (OS X v10.6)

    Returns the object used by the context to track the hierarchy of views with locked focus.

    Declaration

    Objective-C

    - (id)focusStack

    Return Value

    The object used by the context to track the hierarchy of views with locked focus.

    Discussion

    You should never need to get or modify the focus stack information. The use of focus stacks may be deprecated in a future release.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets the object used by the receiver to track the hierarchy of views with locked focus.

    Declaration

    Objective-C

    - (void)setFocusStack:(id)stack

    Parameters

    stack

    The object used by the graphics context for view-hierarchy tracking.

    Discussion

    You should never need to get or modify the focus stack information. The use of focus stacks may be deprecated in a future release.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • The receiver’s global compositing operation setting.

    Declaration

    Swift

    var compositingOperation: NSCompositingOperation

    Objective-C

    @property NSCompositingOperation compositingOperation

    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. See NSCompositingOperation for valid constants.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • A constant that specifies the receiver’s interpolation (image smoothing) behavior.

    Declaration

    Swift

    var imageInterpolation: NSImageInterpolation

    Objective-C

    @property NSImageInterpolation imageInterpolation

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the receiver uses antialiasing.

    Declaration

    Swift

    var shouldAntialias: Bool

    Objective-C

    @property BOOL shouldAntialias

    Discussion

    YEStrue if the receiver uses antialiasing. This value is part of the graphics state and is restored by restoreGraphicsState.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var patternPhase: NSPoint

    Objective-C

    @property NSPoint patternPhase

    Discussion

    Use this property 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • CIContext CIContext Property

    A CIContext object that you can use to render into the receiver. (read-only)

    Declaration

    Swift

    var CIContext: CIContext? { get }

    Objective-C

    @property(readonly, strong) CIContext *CIContext

    Discussion

    ACIContext 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The current rendering intent in the receiver’s graphics state.

    Declaration

    Swift

    var colorRenderingIntent: NSColorRenderingIntent

    Objective-C

    @property NSColorRenderingIntent colorRenderingIntent

    Discussion

    An “Creating a Graphics Context”value that specifies the rendering intent currently used by the receiver. 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var NSGraphicsContextDestinationAttributeName: NSString! var NSGraphicsContextRepresentationFormatAttributeName: NSString!

    Objective-C

    NSString *NSGraphicsContextDestinationAttributeName; NSString *NSGraphicsContextRepresentationFormatAttributeName;

    Constants

    • NSGraphicsContextDestinationAttributeName

      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.

    • NSGraphicsContextRepresentationFormatAttributeName

      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.

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

    Declaration

    Swift

    var NSGraphicsContextPDFFormat: NSString! var NSGraphicsContextPSFormat: NSString!

    Objective-C

    NSString *NSGraphicsContextPSFormat; NSString *NSGraphicsContextPDFFormat;

    Constants

    • NSGraphicsContextPDFFormat

      NSGraphicsContextPDFFormat

      Destination file format is PDF.

      Available in OS X v10.0 and later.

    • NSGraphicsContextPSFormat

      NSGraphicsContextPSFormat

      Destination file format is PostScript.

      Available in OS X v10.0 and later.

  • These interpolations are used by imageInterpolation property.

    Declaration

    Swift

    enum NSImageInterpolation : UInt { case Default case None case Low case Medium case High }

    Objective-C

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

    Constants

    • Default

      NSImageInterpolationDefault

      Use the context’s default interpolation.

      Available in OS X v10.0 and later.

    • None

      NSImageInterpolationNone

      No interpolation.

      Available in OS X v10.0 and later.

    • Low

      NSImageInterpolationLow

      Fast, low-quality interpolation.

      Available in OS X v10.0 and later.

    • Medium

      NSImageInterpolationMedium

      Medium quality, slower than NSImageInterpolationLow.

      Available in OS X v10.6 and later.

    • High

      NSImageInterpolationHigh

      Highest quality, slower than NSImageInterpolationMedium.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • 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 property colorRenderingIntent.

    Declaration

    Swift

    enum NSColorRenderingIntent : Int { case Default case AbsoluteColorimetric case RelativeColorimetric case Perceptual case Saturation }

    Objective-C

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

    Constants

    • Default

      NSColorRenderingIntentDefault

      Use the default rendering intent for the graphics context.

      Available in OS X v10.5 and later.

    • AbsoluteColorimetric

      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.

    • RelativeColorimetric

      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.

    • Perceptual

      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.

    • Saturation

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.