---

NSGraphics

Overview

The NSGraphics class provides static methods for performing some basic drawing operations, view clipping, and inquiries about the application’s windows.

Tasks

Constructors

• NSGraphics

Obtaining Device Information

• availableWindowDepths
• bestDepth
• bitsPerPixelFromDepth
• bitsPerSampleFromDepth
• colorSpaceFromDepth
• numberOfColorComponents
• planarFromDepth

Working with NSAttributedStrings

• drawAttributedString
• sizeOfAttributedString

Working with Windows

• convertGlobalToWindowNumber
• convertWindowNumberToGlobal
• windowCount
• windowList

Working with Bitmap Images

• copyBitmapFromGState
• copyBits
• drawBitmap
• readPixel

Filling a List of Rectangles

• fillRectList
• fillRectListInRange
• fillRectListWithColors
• fillRectListWithColorsInRange

Clipping a List of Rectangles

• clipRectList
• clipRectListInRange

Working with Frame Rects

• frameRect
• frameRectWithWidth
• frameRectWithWidthUsingOperation

Drawing

• dottedFrameRect
• drawButton
• drawColorTiledRects
• drawDarkBezel
• drawGrayBezel
• drawGroove
• drawLightBezel
• drawWhiteBezel
• drawWindowBackground
• eraseRect
• highlightRect

Focus Rings

• setFocusRingStyle

Updating Screen

• disableScreenUpdates
• enableScreenUpdates

Static Methods

availableWindowDepths

Returns an array of values specifying which window depths are currently available.

public static int[] availableWindowDepths()

See Also

• bitsPerPixelFromDepth
• bitsPerSampleFromDepth
• colorSpaceFromDepth
• planarFromDepth

bestDepth

Returns a window depth deep enough for the given number of colors in colorSpace, bits per sample specified by bps, bits per pixel specified by bpp, and whether planar as specified by planar.

public static int bestDepth(String colorSpace, int bps, int bpp, boolean planar)

Discussion

This method tries to accommodate all the parameters (match or better); if there are multiple matches, it gives the closest, with matching colorSpace first, then bps, then planar, then bpp. bpp is “bits per pixel”; 0 indicates default (same as the number of bits per plane, either bps or bps * numberOfColorComponents); other values may be used as hints to provide backing stores of different configuration—for instance, 8-bit color.

See Also

• bitsPerPixelFromDepth
• bitsPerSampleFromDepth
• colorSpaceFromDepth
• planarFromDepth

bitsPerPixelFromDepth

Returns the number of bits per pixel for the window depth specified by depth.

public static int bitsPerPixelFromDepth(int depth)

See Also

• availableWindowDepths
• bestDepth

bitsPerSampleFromDepth

Returns the number of bits per sample (bits per pixel in each color component) for the window depth specified by depth.

public static int bitsPerSampleFromDepth(int depth)

See Also

• availableWindowDepths
• bestDepth

clipRectList

Takes an array of rectangles, rectangles, constructs a path that is the graphic union of those rectangles, and intersects that path with the current clipping path.

public static void clipRectList(NSRect[] rectangles)

Discussion

After computing the new clipping path, the current path is reset to empty.

See Also

• clipRectListInRange

clipRectListInRange

Extracts the subset aRange from the array of rectangles, rectangles, constructs a path that is the graphic union of those rectangles, and intersects that path with the current clipping path.

public static void clipRectListInRange(NSRect[] rectangles, NSRange aRange)

Discussion

After computing the new clipping path, the current path is reset to empty.

See Also

• clipRectList

colorSpaceFromDepth

Returns the color space name for the specified depth.

public static String colorSpaceFromDepth(int depth)

Discussion

For example, the returned color space name can be CalibratedRGBColorSpace or DeviceCMYKColorSpace.

See Also

• availableWindowDepths
• bestDepth

convertGlobalToWindowNumber

Deprecated.

public static int convertGlobalToWindowNumber(int globalNum)

Discussion

Local and global window numbers are identical, so this method returns globalNum.

See Also

• convertWindowNumberToGlobal

convertWindowNumberToGlobal

Deprecated.

public static int convertWindowNumberToGlobal(int winNum)

Discussion

Local and global window numbers are identical, so this method returns winNum.

See Also

• convertGlobalToWindowNumber

copyBitmapFromGState

Deprecated.

public static void copyBitmapFromGState(int srcGState, NSRect srcRect, NSRect destRect)

copyBits

Copies the pixels in the rectangle specified by srcRect to the location specified by destPoint.

public static void copyBits(int srcGState, NSRect srcRect, NSPoint destPoint)

Discussion

The source rectangle is defined in the graphics state designated by srcGState. If srcGState is NSNull, the current graphics state is assumed. The destPoint destination is defined in the current graphics state.

disableScreenUpdates

Disables screen updates.

public static void disableScreenUpdates()

Discussion

Prevents drawing operations from being flushed to the screen for all windows belonging to the calling process. When you reenable screen updates (with enableScreenUpdates) screen flushing for all windows belonging to the calling process appears to be simultaneous. You typically call this method so that operations on multiple windows appear atomic to the user. This is a technique particularly useful for synchronizing parent and child windows. Make sure that the period after calling this method and before reenabling updates is short; the system only allow updating to be disabled for a limited time (currently one second) before automatically reenabling updates. Multiple disableScreenUpdates calls stack and are popped off the stack by matching enableScreenUpdates calls.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• enableScreenUpdates

dottedFrameRect

Deprecated.

public static void dottedFrameRect(NSRect aRect)

Discussion

Use a dashed NSBezierPath instead.

drawAttributedString

Draws attributedString with its font and other display attributes at aPoint in the currently focused NSView.

public static void drawAttributedString(NSAttributedString attributedString, NSPoint aPoint)

Discussion

The width (height for vertical layout) of the rendering area is unlimited, unlike the two parameter version of this method, which uses a bounding rectangle. As a result, this method renders the text in a single line.

If the focus view is flipped, the origin is set at the upper-left corner of the drawing bounding box; otherwise the origin is set at the lower-left corner.

Don’t invoke this method while no NSView is focused.

See Also

• sizeOfAttributedString
• lockFocus (NSView)

Draws attributedString with its font and other display attributes within aRect in the currently focused NSView, clipping the drawing to this rectangle.

public static void drawAttributedString(NSAttributedString attributedString, NSRect aRect)

Discussion

Text is drawn within aRect according to its line sweep direction; for example, Arabic text will begin at the right edge and potentially be clipped on the left.

If the focus view is flipped, the origin is set at the upper-left corner of the drawing bounding box; otherwise the origin is set at the lower-left corner.

Don’t invoke this method while no NSView is focused.

See Also

• lockFocus (NSView)

drawBitmap

Renders a bitmap image using an appropriate display operator.

public static void drawBitmap(NSRect rect, int pixelsWide, int pixelsHigh, int bitsPerSample, int samplesPerPixel, int bitsPerPixel, int bytesPerRow, boolean isPlanar, boolean hasAlpha, String colorSpace, byte[] data)

Discussion

The image is put in the rectangular area specified by rect, which is specified in the current coordinate system and is located in the current window. pixelsWide and pixelsHigh give the width and height of the image in pixels. If either of these dimensions is larger or smaller than the corresponding dimension of the destination rectangle, the image is scaled to fit.

The bitsPerSample argument is the number of bits per sample for each pixel, and samplesPerPixel is the number of samples per pixel. bitsPerPixel is based on samplesPerPixel and the configuration of the bitmap: if the configuration is planar, then the value of bitsPerPixel should equal the value of bitsPerSample; if the configuration isn’t planar (is meshed instead), bitsPerPixel should equal bitsPerSample * samplesPerPixel.

The bytesPerRow argument is calculated in one of two ways, depending on the configuration of the image data (data configuration is described below). If the data is planar, bytesPerRow is (7 + (pixelsWide * bitsPerSample)) / 8. If the data is meshed, bytesPerRow is (7 + (pixelsWide * bitsPerSample * samplesPerPixel)) / 8.

A sample is data that describes one component of a pixel. In an RGB color system, the red, green, and blue components of a color are specified as separate samples, as are the cyan, magenta, yellow, and black components in a CMYK system. Color values in grayscale are a single sample. Alpha values that determine transparency and opaqueness are specified as a coverage sample separate from color. In bitmap images with alpha, the color (or gray) components have to be premultiplied with the alpha. Images with alpha are displayed, read back, and stored in TIFFs in this way.

The isPlanar argument refers to the way data is configured in the bitmap. This flag should be set true if a separate data channel is used for each sample. The function provides for up to five channels, data1, data2, data3, data4, and data5. It should be set false if sample values are interwoven in a single channel (meshed); all values for one pixel are specified before values for the next pixel.

Grayscale windows store pixel data in planar configuration; color windows store it in meshed configuration. This method can render meshed data in a planar window, or planar data in a meshed window. However, it’s more efficient if the image has a depth (bitsPerSample) and configuration (isPlanar) that matches the window.

The hasAlpha argument indicates whether the image contains alpha. If it does, the number of samples should be one greater than the number of color components in the model (for example, four for RGB).

The colorSpace argument can be CustomColorSpace, indicating that the image data is to be interpreted according to the current color space in the graphics state. This interpretation allows for imaging using custom color spaces. The image parameters supplied as the other arguments should match what the color space is expecting.

If the image data is planar, data[0] through data[samplesPerPixel–1] point to the planes; if the data is meshed, only data[0] needs to be set.

drawButton

Draws a gray-filled rectangle, used to signify a user interface button.

public static void drawButton(NSRect boundsRect, NSRect clipRect)

Discussion

For an Aqua button, use an NSButton object.

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Since this method is often used to draw the border of a view, this rectangle is typically that view’s bounds rectangle. Only those parts of boundsRect that lie within the clipRect, a clipping rectangle, are drawn.

The rectangle is filled with light gray. This method is designed for rectangles that are defined in unscaled, unrotated coordinate systems (that is, where the y axis is vertical, the x axis is horizontal, and a unit along either axis is equal to 1 screen pixel). The coordinate system can be either flipped or unflipped. The sides of the rectangle should lie on pixel boundaries.

drawColorTiledRects

Draws rectangles with colored borders.

public static void drawColorTiledRects(NSRect boundsRect, NSRect clipRect, int[] sides, NSColor[] colors, NSRange aRange)

Discussion

The drawColorTiledRects method is a generic method that can be used to draw different types of borders. These borders can be used to outline an area or to give rectangles the effect of being recessed from or elevated above the surface of the screen.

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Since this function is often used to draw the border of a view, this rectangle will typically be that view’s bounds rectangle. Only those parts of aRect that lie within clipRect, a clipping rectangle, are drawn.

In addition to its boundsRect and clipRect arguments, drawColorTiledRects takes three more arguments, which determine how thick the border is and what colors are used to form it. drawColorTiledRects takes successive 1.0-unit-wide slices from the sides of the rectangle specified by the sides argument. Each slice is then drawn using the corresponding color from colors. drawColorTiledRects makes and draws these slices for each pair of elements in sides and colors within the range aRange. If a side is used more than once, the second slice is made inside the first.

drawDarkBezel

Draws a dark gray–filled rectangle with a bezel border.

public static void drawDarkBezel(NSRect boundsRect, NSRect clipRect)

Discussion

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Only those parts of boundsRect that lie within clipRect, a clipping rectangle, are drawn.

drawGrayBezel

Draws a gray-filled rectangle with a bezel border.

public static void drawGrayBezel(NSRect boundsRect, NSRect clipRect)

Discussion

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Only those parts of boundsRect that lie within clipRect, a clipping rectangle, are drawn.

drawGroove

Draws a gray-filled rectangle with a groove border.

public static void drawGroove(NSRect boundsRect, NSRect clipRect)

Discussion

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Only those parts of boundsRect that lie within clipRect, a clipping rectangle, are drawn.

drawLightBezel

Draws a light gray–filled rectangle with a bezel border.

public static void drawLightBezel(NSRect boundsRect, NSRect clipRect)

Discussion

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Only those parts of boundsRect that lie within clipRect, a clipping rectangle, are drawn.

drawWhiteBezel

Draws a white-filled rectangle with a bezel border.

public static void drawWhiteBezel(NSRect boundsRect, NSRect clipRect)

Discussion

The boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. Only those parts of boundsRect that lie within clipRect, a clipping rectangle, are drawn.

drawWindowBackground

Draws the window’s default background pattern into the rectangle aRect of the currently focused view.

public static void drawWindowBackground(NSRect aRect)

enableScreenUpdates

Enables screen updates.

public static void enableScreenUpdates()

Discussion

Reenables, for all windows of a process, the flushing of drawing operations to the screen that was previously disabled by disableScreenUpdates. Multiple enableScreenUpdates calls pop matching disableScreenUpdates calls off a stack.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• disableScreenUpdates

eraseRect

Erases the rectangle referred to by boundsRect, filling it with white.

public static void eraseRect(NSRect boundsRect)

Discussion

It does not alter the current color.

fillRectList

Fills a list of rectangles, rectangles, with the current color.

public static void fillRectList(NSRect[] rectangles)

fillRectListInRange

Fills a subset aRange of rectangles from the array rectangles with the current color.

public static void fillRectListInRange(NSRect[] rectangles, NSRange aRange)

fillRectListWithColors

Takes a list of rectangles, rectangles, and a matching list of color values.

public static void fillRectListWithColors(NSRect[] rectangles, NSColor[] colors)

Discussion

The first rectangle is filled with the first color, the second rectangle with the second color, and so on. There must be an equal number of rectangles and color values. The rectangles should not overlap; the order in which they are filled cannot be guaranteed. This method alters the current color of the current graphics state, setting it unpredictably to one of the values passed in colors.

See Also

• fillRectListWithColorsInRange

fillRectListWithColorsInRange

Fills a subset aRange of rectangles from the array rectangles with the corresponding subset colors from the array colors.

public static void fillRectListWithColors(NSRect[] rectangles, NSColor[] colors, NSRange aRange)

See Also

• fillRectListWithColors

frameRect

Draws a frame around the inside of boundsRect in the current color.

public static void frameRect(NSRect boundsRect)

Discussion

The width is equal to 1.0 in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

frameRectWithWidth

Draws a frame around the inside of boundsRect in the current color.

public static void frameRectWithWidth(NSRect boundsRect, float width)

Discussion

The width is equal to width in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

frameRectWithWidthUsingOperation

Draws a frame around the inside of boundsRect in the current color, using the compositing operation operation.

public static void frameRectWithWidthUsingOperation(NSRect boundsRect, float width, int operation)

Discussion

The width is equal to width in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

highlightRect

Deprecated.

public static void highlightRect(NSRect aRect)

numberOfColorComponents

Returns the number of color components in the color space colorSpaceName.

public static int numberOfColorComponents(String colorSpaceName)

planarFromDepth

Returns true if the specified window depth is planar and false if it is not.

public static boolean planarFromDepth(int depth)

See Also

• availableWindowDepths
• bestDepth

readPixel

Returns the color of the pixel at the location specified by aPoint.

public static NSColor readPixel(NSPoint aPoint)

Discussion

The location argument is taken in the current coordinate system—in other words, you must lock focus on the view that contains the pixel that you wish to query and then pass the coordinate for the pixel in the view’s coordinate system.

setFocusRingStyle

Sets the style of the focus ring in the current graphics context in the current locked focus view.

public static void setFocusRingStyle(int style)

Discussion

This style affects all rendering until the graphics state is restored. style is one of the values discussed in “Constants.”

Note that the focus ring may actually be drawn outside the view, but will be clipped to any clipping superview or the window content view.

sizeOfAttributedString

Returns the bounding box of the marks that attributedString draws.

public static NSSize sizeOfAttributedString(NSAttributedString attributedString)

See Also

• drawAttributedString

windowCount

Returns the number of onscreen windows belonging to the application.

public static int windowCount()

windowList

Provides an ordered list of the application’s onscreen windows.

public static void windowList(int[] list)

Discussion

The order of windows in list is the same as their order in the window server’s screen list (their front-to-back order on the screen).

Constants

The following colors are the standard gray values for the 2-bit-deep grayscale color space:

• Black

• DarkGray

• LightGray

• White

The following color spaces are defined by NSGraphics and are described in “About Color Spaces”:

• CalibratedBlackColorSpace

• CalibratedRGBColorSpace

• CalibratedWhiteColorSpace

• CustomColorSpace

• DeviceBlackColorSpace

• DeviceCMYKColorSpace

• DeviceRGBColorSpace

• DeviceWhiteColorSpace

• DynamicSystemColorSpace

• NamedColorSpace

• PatternColorSpace

The following device constants are defined by NSGraphics. These are the keys for device description dictionaries, such as those returned by the deviceDictionary methods of NSPrinter, NSScreen, and NSWindow.

NSGraphics defines the following constants to specify where a focus ring should be drawn and is used by:

NSGraphics defines the following constants to specify focus ring types; the focus ring type is used by NSCell (and potentially by any NSView object) and to configure if and how a control or other view object should draw its focus ring.

Notifications

SystemColorsDidChangeNotification

Sent when the system colors have been changed (such as through a system control panel interface).

This notification contains no notification object and no userInfo dictionary.

---