---

NSGraphicsContext

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 static methods currentContext, graphicsContextWithAttributes, , , 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

Constructors

• NSGraphicsContext

Creating a Graphics Context

• graphicsContextWithAttributes
• graphicsContextWithWindow

Testing the Drawing Destination

• currentContextDrawingToScreen
• isDrawingToScreen

Setting and Identifying the Current Context

• currentContext
• restoreGraphicsContext
• setCurrentContext
• saveGraphicsContext

Getting Information About a Context

• attributes

Controlling the Context Flush

• flush
• flushGraphics
• restoreGraphicsState
• saveGraphicsState
• setGraphicsState
• synchronize

Rendering Options

• imageInterpolation
• setImageInterpolation
• shouldAntialias
• setShouldAntialias
• patternPhase
• setPatternPhase

Static Methods

currentContext

Returns the current graphics context of the current thread.

public static NSGraphicsContext currentContext()

Discussion

Returns a concrete subclass of NSGraphicsContext.

currentContextDrawingToScreen

Convenience method equivalent to sending isDrawingToScreen to the result of currentContext.

public static boolean currentContextDrawingToScreen()

graphicsContextWithAttributes

Instantiates a concrete subclass of NSGraphicsContext using the information in attributes.

public static NSGraphicsContext graphicsContextWithAttributes(NSDictionary attributes)

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.

See the "Constants" section for the dictionary keys available for attributes.

graphicsContextWithWindow

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

public static NSGraphicsContext graphicsContextWithWindow(NSWindow aWindow)

restoreGraphicsContext

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

public static void restoreGraphicsContext()

saveGraphicsContext

Sends the current graphics context a saveGraphicsState message and pushes the context onto the per-thread stack

public static void saveGraphicsContext()

Discussion

.

setCurrentContext

Sets the current graphics context of the current thread to context.

public static void setCurrentContext(NSGraphicsContext context)

Discussion

context must be a concrete subclass of NSGraphicsContext.

setGraphicsState

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

public static void setGraphicsState(int graphicsState)

Discussion

The graphicState must be created in the calling thread.

Instance Methods

attributes

Returns the receiver’s attributes, if any.

public NSDictionary attributes()

Discussion

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

flush

Not implemented.

public void flush()

Discussion

Use flushGraphics.

flushGraphics

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

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

imageInterpolation

Returns the receiver’s interpolation (image smoothing).

public int imageInterpolation()

See Also

• setImageInterpolation

isDrawingToScreen

Returns true if the drawing destination is the screen or a bitmap, false otherwise.

public boolean isDrawingToScreen()

Discussion

You can interpret a return value of false to mean that the drawing destination is a printer, although it may also be a PDF or EPS file. The NSColor method set, for example, invokes isDrawingToScreen to determine whether it can apply an alpha value, which is not supported by printing contexts.

If this method returns false, you can call attributes to see if additional information is available about the drawing destination.

patternPhase

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

public NSPoint patternPhase()

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 Mac OS X v10.2 and later.

See Also

• setPatternPhase

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.

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

saveGraphicsState

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

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

setImageInterpolation

Sets the receiver’s interpolation (image smoothing) to interpolation.

public void setImageInterpolation(int interpolation)

Discussion

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

See Also

• imageInterpolation

setPatternPhase

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

public void setPatternPhase(NSPoint phase)

Discussion

Use it 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 Mac OS X v10.2 and later.

See Also

• patternPhase

setShouldAntialias

Sets whether the receiver should use antialiasing, depending on the Boolean value antialias.

public void setShouldAntialias(boolean antialias)

Discussion

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

See Also

• shouldAntialias

shouldAntialias

Returns whether the receiver uses antialiasing.

public boolean shouldAntialias()

See Also

• setShouldAntialias

synchronize

Not implemented.

public void synchronize()

Constants

The following constants are defined by NSGraphicsContext and are dictionary keys used by graphicsContextWithAttributes and attributes:

The following constants are possible values for the GraphicsContextRepresentationFormatAttributeName key in a graphic context’s attribute dictionary:

The following interpolations are defined by NSGraphicsContext and used by imageInterpolation and setImageInterpolation:

---