Functions

CGWindowListCopyWindowInfo

Generates and returns information about the selected windows in the current user session.

CFArrayRef CGWindowListCopyWindowInfo(
   CGWindowListOption option,
   CGWindowID relativeToWindow
);
Parameters
option

The options describing which window dictionaries to return. Typical options let you return dictionaries for all windows or for windows above or below the window specified in the relativeToWindow parameter. For more information, see “Window List Option Constants.”

relativeToWindow

The ID of the window to use as a reference point when determining which other window dictionaries to return. For options that do not require a reference window, this parameter can be kCGNullWindowID.

Return Value

An array of CFDictionaryRef types, each of which contains information about one of the windows in the current user session. If there are no windows matching the desired criteria, the function returns an empty array. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.

Discussion

You can use this function to get detailed information about the configuration of one or more windows in the current user session. For example, you can use this function to get the bounds of the window, its window ID, and information about how it is managed by the window server. For the list of keys and values that may be present in the dictionary, see “Required Window List Keys” and “Optional Window List Keys.”

Generating the dictionaries for system windows is a relatively expensive operation. As always, you should profile your code and adjust your usage of this function appropriately for your needs.

CGWindowListCreate

Returns the list of window IDs associated with the specified windows in the current user session.

CFArrayRef CGWindowListCreate(
   CGWindowListOption option,
   CGWindowID relativeToWindow
);
Parameters
option

The options describing which window IDs to return. Typical options let you obtain IDs for all windows or for windows above or below the window specified in the relativeToWindow parameter. For more information, see “Window List Option Constants.”

relativeToWindow

The ID of the window to use as a reference point when determining which other windows to return. For options that do not require a reference window, this parameter can be kCGNullWindowID.

Return Value

An array of CGWindowID values corresponding to the desired windows. If there are no windows matching the desired criteria, the function returns an empty array. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.

CGWindowListCreateDescriptionFromArray

Generates and returns information about windows with the specified window IDs.

CFArrayRef CGWindowListCreateDescriptionFromArray(
   CFArrayRef windowArray
);
Parameters
windowArray

An array of CGWindowID types, each of which corresponds to a window whose information you want to retrieve.

Return Value

An array of CFDictionaryRef types, each of which contains information about one of the windows in the current user session. If there are no windows matching the desired criteria, the function returns an empty array. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.

Discussion

This function ignores any window IDs in the windowArray parameter that refer to windows that no longer exist. (This can occur if the user closes a window between the time you retrieve its ID and the time you call this function.) You should therefore not assume that the returned array of dictionaries contains the same number of entries as this parameter. To make it easier to associate window IDs with the correct information, however, each dictionary does contain a kCGWindowNumber key whose value is the corresponding window ID. For the list of keys and values that may be present in the dictionary, see “Required Window List Keys” and “Optional Window List Keys.”

CGWindowListCreateImage

Returns a composite image based on a dynamically generated list of windows.

CGImageRef CGWindowListCreateImage(
   CGRect screenBounds,
   CGWindowListOption windowOption,
   CGWindowID windowID,
   CGWindowImageOption imageOption
);
Parameters
screenBounds

The rectangle that you want to capture. The coordinates of the rectangle must be specified in screen coordinates, where the screen origin is in the upper-left corner of the main display and y-axis values increase downward. Specify CGRectNull to indicate the minimum rectangle that encloses the specified windows. Specify CGRectInfinite to capture the entire desktop area.

windowOption

The options describing which windows to include in the image. Typical options let you choose all windows or windows above or below the window specified in the windowID parameter. For more information, see “Window List Option Constants.”

windowID

The ID of the window to use as a reference point when determining which other windows to include in the image. For options that do not require a reference window, this parameter can be kCGNullWindowID.

imageOption

The options that determine which parts of the window to capture. If you specified CGRectNull for the screenBounds parameter, these options affect the resulting bounding box used for the image. For example, if you include a window’s screen effects in the image, the bounding box may need to be slightly larger to accommodate those effects. For a list of possible options, see “Window Image Types.”

Return Value

A composite image formed from the contents of the specified set of windows. If the windows are unreadable or no windows meet the specified criteria, this function returns an image that is either 0 by 0 pixels in size or is of the specified size but is filled with the transparent black color. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.

Discussion

Any windows that are onscreen but whose sharing setting is set to kCGWindowSharingNone are skipped and not included in the resulting image. If this results in no windows being available in the selected range, this function returns NULL.

CGWindowListCreateImageFromArray

Returns a composite image of the specified windows.

CGImageRef CGWindowListCreateImageFromArray(
   CGRect screenBounds,
   CFArrayRef windowArray,
   CGWindowImageOption imageOption
);
Parameters
screenBounds

The rectangle that you want to capture. The coordinates of the rectangle must be specified in screen coordinates, where the screen origin is in the upper-left corner of the main display and y-axis values increase downward. Specify CGRectNull to indicate the minimum rectangle that encloses the specified windows. Specify CGRectInfinite to capture the entire desktop area.

windowArray

An array of CGWindowID types, each of which corresponds to a window whose information you want to retrieve. The order of the window IDs also affects the compositing order of the windows; see the discussion for more information about this behavior.

imageOption

The options that determine which parts of the window to capture. If you specified CGRectNull for the screenBounds parameter, these options help determine the resulting bounding box used for the image. For example, if you include a window’s screen effects in the image, the bounding box may need to be slightly larger to accommodate those effects. For a list of possible options, see “Window Image Types.”

Return Value

A composite image formed from the contents of the specified set of windows. Invalid window IDs are ignored. If the windows are unreadable (because their sharing setting is set to kCGWindowSharingNone, for example) or if no windows meet the specified criteria, this function returns an image that is either 0 by 0 pixels in size or is of the specified size but is filled with the transparent black color. If you call this function from outside of a GUI security session or when no window server is running, this function returns NULL.

Discussion

This function ignores any window IDs in the windowArray parameter that refer to windows that no longer exist. (This can occur if the user closes a window between the time you retrieve its ID and the time you call this function.) If this results in no windows being available in the selected range, this function returns NULL.

This function ignores the onscreen ordering of the windows and instead composites them using the order specified in the windowArray parameter. In other words, windows at the beginning of the array are composited in front of windows at the end of the array.