---

Constants

Window Sharing Constants

Specifies whether and how windows are shared between applications.

enum {
   kCGWindowSharingNone      = 0,
   kCGWindowSharingReadOnly  = 1,
   kCGWindowSharingReadWrite = 2
};

Constants

kCGWindowSharingNone

The window is not shared.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowSharingReadOnly

The window is shared and its contents can be read by all processes but modified only by the process that created it.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowSharingReadWrite

The window is shared and its contents can be read and modified by any process.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Backing Store Types

Specifies how drawing commands are buffered by the window device.

enum {
   kCGBackingStoreRetained     = 0,
   kCGBackingStoreNonretained  = 1,
   kCGBackingStoreBuffered     = 2
};

Constants

kCGBackingStoreRetained

The window uses a buffer, but draws directly to the screen where possible and to the buffer for obscured portions.

You should typically not use this mode. It combines the limitations of kCGBackingStoreNonretained with the memory use of kCGBackingStoreBuffered. The original NeXTSTEP implementation was an interesting compromise that worked well with fast memory mapped framebuffers on the CPU bus—something that hasn't been in general use since around 1994. These tend to have performance problems.

In Mac OS X 10.5 and later, requests for retained windows will result in the window system creating a buffered window, as that better matches actual use

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGBackingStoreNonretained

The window draws directly to the screen without using any buffer.

You should typically not use this mode. It exists primarily for use in the original Classic Blue Box. It does not support Quartz drawing, alpha blending, or opacity. Moreover, it does not support hardware acceleration, and interferes with system-wide display acceleration. If you use this mode, your application must manage visibility region clipping itself, and manage repainting on visibility changes.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGBackingStoreBuffered

The window draws into a display buffer and then flushes that buffer to the screen.

You should typically use this mode. It supports hardware acceleration, Quartz drawing, and takes advantage of the GPU when possible. It also supports alpha channel drawing, opacity controls, using the compositor.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Window List Option Constants

Specifies which windows in the current user session to include in a generated list.

enum
{
   kCGWindowListOptionAll                 = 0,
   kCGWindowListOptionOnScreenOnly        = (1 << 0),
   kCGWindowListOptionOnScreenAboveWindow = (1 << 1),
   kCGWindowListOptionOnScreenBelowWindow = (1 << 2),
   kCGWindowListOptionIncludingWindow     = (1 << 3),
   kCGWindowListExcludeDesktopElements    = (1 << 4)
}

Constants

kCGWindowListOptionAll

List all windows, including both onscreen and offscreen windows. When retrieving a list with this option, the relativeToWindow parameter should be set to kCGNullWindowID.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowListOptionOnScreenOnly

List all windows that are currently onscreen. Windows are returned in order from front to back. When retrieving a list with this option, the relativeToWindow parameter should be set to kCGNullWindowID.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowListOptionOnScreenAboveWindow

List all windows that are currently onscreen and in front of the window specified in the relativeToWindow parameter. Windows are returned in order from front to back.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowListOptionOnScreenBelowWindow

List all windows that are currently onscreen and in behind the window specified in the relativeToWindow parameter. Windows are returned in order from front to back.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowListOptionIncludingWindow

Include the specified window (from the relativeToWindow parameter) in the returned list. You must combine this option with the kCGWindowListOptionOnScreenAboveWindow or kCGWindowListOptionOnScreenBelowWindow option to retrieve meaningful results.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowListExcludeDesktopElements

Exclude any windows from the list that are elements of the desktop, including the background picture and desktop icons. You may combine this option with the other options.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Discussion

The kCGWindowListOptionIncludingWindow and kCGWindowListExcludeDesktopElements constants may be combined with the other constants by adding (or ORing) them together and passing the resulting value to the appropriate function.

These constants let you retrieve windows in the current user session only. You cannot use them to retrieve windows from other active user sessions running on the system.

Window Image Types

Specifies the options for capturing an image of a window.

enum {
   kCGWindowImageDefault             = 0,
   kCGWindowImageBoundsIgnoreFraming = (1 << 0),
   kCGWindowImageShouldBeOpaque      = (1 << 1),
   kCGWindowImageOnlyShadows         = (1 << 2)
};

Constants

kCGWindowImageDefault

When the requested capture rectangle is CGRectNull, using this option captures the entire window plus the area required to display any framing effects, such as the window’s shadow. This is the default behavior.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowImageBoundsIgnoreFraming

When the requested capture rectangle is CGRectNull, using this option captures the window area only and does not capture the area occupied by any window framing effects.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowImageShouldBeOpaque

When capturing the window, partially transparent areas are backed by a solid white color so that the resulting image is fully opaque. You can combine this option with other options.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowImageOnlyShadows

When capturing the window, only the shadow effects are captured.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

CGWindowID Encoding Type

Defines the encoding type for window IDs.

#define kCGWindowIDCFNumberType kCFNumberSInt32Type

Constants

kCGWindowIDCFNumberType

The encoding type for window IDs inside a CFNumberRef opaque type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Null Window

Defines a guaranteed invalid window ID.

#define kCGNullWindowID ((CGWindowID)0)

Constants

kCGNullWindowID

A guaranteed invalid window ID.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Window Sharing Encoding Type

Defines the encoding type for window sharing values.

#define kCGWindowSharingCFNumberType kCFNumberSInt32Type

Constants

kCGWindowSharingCFNumberType

The encoding type for window sharing values inside a CFNumberRef opaque type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Window Backing Encoding Type

Defines the encoding type for window backing types.

#define kCGWindowBackingCFNumberType kCFNumberSInt32Type

Constants

kCGWindowBackingCFNumberType

The encoding type for window backing values inside a CFNumberRef opaque type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Required Window List Keys

The keys that are guaranteed to be available in a window’s information dictionary.

const CFStringRef kCGWindowNumber;
const CFStringRef kCGWindowStoreType;
const CFStringRef kCGWindowLayer;
const CFStringRef kCGWindowBounds;
const CFStringRef kCGWindowSharingState;
const CFStringRef kCGWindowAlpha;
const CFStringRef kCGWindowOwnerPID;
const CFStringRef kCGWindowMemoryUsage;

Constants

kCGWindowNumber

The value for this key is a CFNumberRef type (encoded as kCGWindowIDCFNumberType) that contains the window ID. The window ID is unique within the current user session.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowStoreType

The value for this key is a CFNumberRef type (encoded as kCFNumberIntType) that contains one of the constants defined in “Backing Store Types.”

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowLayer

The value for this key is a CFNumberRef type (encoded as kCFNumberIntType) that contains the window layer number.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowBounds

The value for this key is a CFDictionaryRef type that must be decoded to a CGRect type using the CGRectMakeWithDictionaryRepresentation function. The coordinates of the rectangle are specified in screen space, where the origin is in the upper-left corner of the main display.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowSharingState

The value for this key is a CFNumberRef type (encoded as kCFNumberIntType) that contains one of the constants defined in “Window Sharing Constants.”

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowAlpha

The value for this key is a CFNumberRef type (encoded as kCFNumberFloatType) that contains the window’s alpha fade level. This number is in the range 0.0 to 1.0, where 0.0 is fully transparent and 1.0 is fully opaque.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowOwnerPID

The value for this key is a CFNumberRef type (encoded as kCFNumberIntType) that contains the process ID of the application that owns the window.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowMemoryUsage

The value for this key is a CFNumberRef type (encoded as kCFNumberLongLongType) that contains an estimate of the amount of memory (measured in bytes) used by the window and its supporting data structures.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

Optional Window List Keys

The keys that may optionally be available inside a window’s information dictionary.

const CFStringRef kCGWindowWorkspace;
const CFStringRef kCGWindowOwnerName;
const CFStringRef kCGWindowName;
const CFStringRef kCGWindowIsOnscreen;
const CFStringRef kCGWindowBackingLocationVideoMemory;

Constants

kCGWindowWorkspace

The key that identifies the workspace to which the window belongs. The value for this key is a CFNumberRef type whose value is encoded using the kCFNumberIntType type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowOwnerName

The key that identifies the name of the application that owns the window. The value for this key is a CFStringRef type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowName

The key that identifies the name of the window, as configured in Quartz. The value for this key is a CFStringRef type. (Note that few applications set the Quartz window name.)

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowIsOnscreen

The key that identifies whether the window is currently onscreen. The value for this key is a CFBooleanRef type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

kCGWindowBackingLocationVideoMemory

The key that identifies whether the window’s backing store is located in video memory. The value for this key is a CFBooleanRef type.

Available in Mac OS X v10.5 and later.

Declared in CGWindow.h.

---