Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC
ADC Home > Reference Library > Reference > Carbon > User Experience > Window Manager Reference >

Next Page > Hide TOC

Window Manager Reference

Framework
Carbon/Carbon.h
Declared in
HIToolboxDebugging.h
HIWindowViews.h
IOMacOSTypes.h
MacWindows.h
QuickdrawTypes.h

Overview

Your application uses the Window Manager to create and manage windows. For example, your application uses the Window Manager to create and display a new window when the user creates a new document or opens an existing document. When the user clicks or holds down the mouse button while the cursor is in a window created by your application, you use the Window Manager to determine the location of the mouse action and to alter the window display as appropriate. When the user closes a window, you use the Window Manager to remove the window from the screen.

A Macintosh application uses windows for most communication with the user, from discrete interactions such as presenting and acknowledging alert boxes to open-ended interactions such as creating and editing documents. Users generally type words and formulas, draw pictures, or otherwise enter data in a window on the screen. Your application typically lets the user save this data in a file, open saved files, and view the saved data in a window.

A window can be any size or shape, and the user can display any number of windows, within the limits of available memory, on the screen at once.

The Window Manager defines a set of standard windows and provides a set of routines for managing them. The Window Manager helps your application display windows that are consistent with the Macintosh user interface.

Note:  Historically, the Window Manager has offered different successive methods for creating and manipulating windows. Many of the older functions have been deprecated and, in most cases, this reference provides a recommended replacement. For the most up-to-date information about creating windows, see the document Handling Carbon Windows and Controls.

Carbon supports the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must move them out of resources and compile them into your application. In addition:

Functions by Task

Accessing Information About a Window

Activating Window Path Pop-Up Menus

Associating Data With Windows

Collapsing Windows

Creating, Storing, and Closing Windows

Displaying Floating Windows and Window Animations

Displaying Windows

Dragging Proxy Icons

Establishing Proxy Icons

Getting and Setting Window Structure Fields

Handling Mouse Events in Windows

Locating Windows

Maintaining the Update Region

Managing Activation Scope

Managing Dock Tiles

Managing Modality

Managing Themes

Managing Toolbars

Managing Transitions

Managing Transparency

Managing UPPs

Managing Window Attributes

Managing Window Availability

Managing Window Classes

Managing Window Features

Managing Window Focus

Managing Window Groups

Managing Window Titles

Manipulating Drawers

Manipulating Sheets

Manipulating Window Color Information

Referencing Windows

Scrolling

Sizing and Positioning Windows

Updating the Screen

Using Default and Cancel Buttons

You can use these functions to add dialog-like button controls to normal windows.

Zooming Windows

Miscellaneous

Legacy Functions

Functions

ActivateWindow

Activates or deactivates a window. 

OSStatus ActivateWindow (
   WindowRef inWindow,
   Boolean inActivate
);

Parameters
inWindow

The window to activate or deactivate.

inActivate

Pass true to activate the window, false otherwise.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Related Sample Code
Declared In
MacWindows.h

ActiveNonFloatingWindow

Returns the currently active nonfloating window. 

WindowRef ActiveNonFloatingWindow (
   void
);

Return Value

A reference to the active window.

Discussion

Note that the active window is not necessarily the frontmost window, and it is not necessarily the window with user focus. Call GetUserFocusWindow to get the window that has user focus.

Availability
Declared In
MacWindows.h

AreFloatingWindowsVisible

Indicates whether an application’s floating windows are currently visible.

Boolean AreFloatingWindowsVisible (
   void
);

Return Value

A Boolean whose value is true if the application’s floating windows are currently shown or false if the application’s floating windows are currently hidden.

Discussion

This function checks the visibility state of an application’s floating windows, which are hidden automatically when the application receives a suspend event and are made visible automatically when the application receives a resume event.

Special Considerations

The AreFloatingWindowsVisible function operates only upon windows created with the kFloatingWindowClass constant; see “Window Class Constants” for more details on this constant.

Availability
Declared In
MacWindows.h

BeginUpdate

Starts updating a window when you receive an update event for that window.

void BeginUpdate (
   WindowRef window
);

Parameters
window

The window that is to be updated when an update event is received. Your application gets this information from the message field in the update event structure.

Discussion

The BeginUpdate function limits the visible region of the window’s graphics port to the intersection of the visible region and the update region it then sets the window’s update region to an empty region. After calling BeginUpdate, your application redraws either the entire content region or only the visible region. In either case, only the parts of the window that require updating are actually redrawn on the screen.

Every call to BeginUpdate must be matched with a subsequent call to EndUpdate after your application redraws the content region. BeginUpdate and EndUpdate can’t be nested. That is, you must call EndUpdate before the next call to BeginUpdate.

In Mac OS X, you only receive one update event. If you don’t call BeginUpdate, you won’t receive any further update events until the window is invalidated again.

Special Considerations

This function should not be used on composited windows. Modifying a composited window's update region does not affect the area of the window to be drawn. A composited window does not use its window update region to control drawing. Instead, a composited window determines what to draw by looking at the invalid regions of the views contained in the window.

Availability
Related Sample Code
Declared In
MacWindows.h

BeginWindowProxyDrag

Creates the drag reference and the drag image when the user drags a proxy icon.

OSStatus BeginWindowProxyDrag (
   WindowRef window,
   DragRef *outNewDrag,
   RgnHandle outDragOutlineRgn
);

Parameters
window

The window whose proxy icon is being dragged.

outNewDrag

On input, a pointer to a value of type DragRef. On return, the value refers to the current drag process.

outDragOutlineRgn

On input, a value of type RgnHandle. Your application can create this handle with a call to the QuickDraw function NewRgn. On return, this region is set to the outline of the icon being dragged.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Typically, if the proxy icon represents a type of object (currently, file system entities such as files, folders, and volumes) supported by the Window Manager, the Window Manager can handle all aspects of the drag process itself, and your application should call the function TrackWindowProxyDrag. However, if the proxy icon represents a type of data that the Window Manager does not support, or if you want to implement custom dragging behavior, your application should call the function TrackWindowProxyFromExistingDrag.

The TrackWindowProxyFromExistingDrag function accepts an existing drag reference and adds file data if the window contains a file proxy. If your application uses TrackWindowProxyFromExistingDrag, you then have the choice of using this function in conjunction with the functions BeginWindowProxyDrag and EndWindowProxyDrag or simply calling TrackWindowProxyFromExistingDrag and handling all aspects of creating and disposing of the drag yourself.

Specifically, your application can call BeginWindowProxyDrag to set up the drag image and drag reference. Your application must then track the drag, using TrackWindowProxyFromExistingDrag, and do any required moving of data and, finally, call EndWindowProxyDrag to dispose of the drag reference. BeginWindowProxyDrag should not be used for types handled by the Window Manager unless the application wants to implement custom dragging behavior for those types.

Your application detects a drag when the function FindWindow returns the inProxyIcon result code.

Availability
Declared In
MacWindows.h

BringToFront

Brings a window to the front.

void BringToFront (
   WindowRef window
);

Parameters
window

The window that is to be brought to the front.

Discussion

The BringToFront function puts the specified window at the beginning of the window list and redraws the window in front of all others on the screen. It does not change the window’s highlighting or make it active.

Your application does not ordinarily call BringToFront. The user interface guidelines specify that the frontmost window should be the active window. To bring a window to the front and make it active, call the function SelectWindow.

Availability
Related Sample Code
Declared In
MacWindows.h

ChangeWindowAttributes

Changes a window’s attributes. 

OSStatus ChangeWindowAttributes (
   WindowRef window,
   WindowAttributes setTheseAttributes,
   WindowAttributes clearTheseAttributes
);

Parameters
window

The window whose attributes you want to change.

setTheseAttributes

The attributes you want to set. Pass kWindowNoAttributes if you do not want to set any attributes. See “Window Attributes” for a list of window attributes.

clearTheseAttributes

The attributes you want to clear (if any). Pass kWindowNoAttributes if you do not want to clear any attributes. See “Window Attributes” for a list of window attributes.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If the changed attributes affect the visible window’s frame, the window regions are recalculated and the window is redrawn.

Availability
Related Sample Code
Declared In
MacWindows.h

ChangeWindowGroupAttributes

Changes the attributes of a window group. 

OSStatus ChangeWindowGroupAttributes (
   WindowGroupRef inGroup,
   WindowGroupAttributes setTheseAttributes,
   WindowGroupAttributes clearTheseAttributes
);

Parameters
inGroup

The window group whose attributes you want to set.

setTheseAttributes

The attributes you want to set. See “Window Group Attributes” for a list of possible attributes.

clearTheseAttributes

The attributes you want to clear (if any). See “Window Group Attributes” for a list of possible attributes.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

ChangeWindowPropertyAttributes

Changes attributes associated with a window property. 

OSStatus ChangeWindowPropertyAttributes (
   WindowRef window,
   OSType propertyCreator,
   OSType propertyTag,
   OptionBits attributesToSet,
   OptionBits attributesToClear
);

Parameters
window

The window whose property attributes are to be changed.

propertyCreator

The property creator.

propertyTag

The property tag.

attributesToSet

The attributes to set. For a possible value, see “Window Property Persistent Constant.”

attributesToClear

The attributes to clear. For a possible value, see “Window Property Persistent Constant.”

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

CloseDrawer

Closes a drawer.

OSStatus CloseDrawer (
   WindowRef inDrawerWindow,
   Boolean inAsync
);

Parameters
inDrawerWindow

The drawer window that is to be closed.

inAsync

Pass true for asynchronous closing; otherwise, pass false.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

CloseDrawer may close the drawer either synchronously or asynchronously, depending on the value of the inAsync parameter. If inAsync is true, CloseDrawer installs an event loop timer that closes the drawer after CloseDrawer returns to the caller; therefore, the caller must be running its event loop for the drawer to close. If inAsync is false, CloseDrawer closes the drawer completely before returning to the caller. CloseDrawer retains the drawer window while the drawer is closing, and releases it when the drawer is fully closed. CloseDrawer sends the kEventWindowDrawerClosing event to the drawer, the drawer’s parent, and the application before closing the drawer. If an event handler for this event returns userCanceledErr, CloseDrawer will return immediately without closing the drawer. CloseDrawer sends the kEventWindowDrawerClosed event to the drawer, the drawer’s parent, and the application after the drawer has finished closing.

Availability
Declared In
MacWindows.h

CollapseAllWindows

Collapses or expands all collapsable windows in an application.

OSStatus CollapseAllWindows (
   Boolean collapse
);

Parameters
collapse

Set to true to collapse all windows in the application. Set to false to expand all windows in the application.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

In Mac OS X, this function works with any window that has the kWindowCollapseBoxAttribute. If that attribute is not present, the Window Manager checks for the kWindowCanCollapse feature bit.

Availability
Declared In
MacWindows.h

CollapseWindow

Collapses or expands a window to the dock.

OSStatus CollapseWindow (
   WindowRef window,
   Boolean collapse
);

Parameters
window

The window that is to be collapsed or expanded.

collapse

Indicates whether the window should be collapsed or expanded.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The CollapseWindow function tells the Window Manager to collapse or expand a window depending upon the value passed in the collapse parameter. In Mac OS X, any window that has the kWindowCollapseBoxAttribute can be collapsed. If that attribute is not present, the Window Manager checks for the kWindowCanCollapse feature bit.

Availability
Declared In
MacWindows.h

ConstrainWindowToScreen

Moves and resizes a window so that it’s contained entirely on a single screen.

OSStatus ConstrainWindowToScreen (
   WindowRef inWindowRef,
   WindowRegionCode inRegionCode,
   WindowConstrainOptions inOptions,
   const Rect *inScreenRect,
   Rect *outStructure
);

Parameters
inWindowRef

The window to constrain.

inRegionCode

The window region to constrain. See “Window Region Constants” for a list of possible constants to pass.

inOptions

Flags controlling how the window is constrained.

inScreenRect

A rectangle, in global coordinates, in which to constrain the window. May be NULL. If NULL, the window is constrained to the screen with the greatest intersection with the specified window region.

outStructure

On exit, contains the new structure bounds of the window, in global coordinates. May be NULL.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
See Also
Declared In
MacWindows.h

CopyWindowAlternateTitle

Obtains a copy of the alternate window title. 

OSStatus CopyWindowAlternateTitle (
   WindowRef inWindow,
   CFStringRef *outTitle
);

Parameters
inWindow

The window to get the alternate title from.

outTitle

Receives the alternate title for the window. If the window does not have an alternate title, NULL will be returned in outTitle.

Return Value

A result code. See “Window Manager Result Codes.” An operating system status code.

Discussion

See the discussion of SetWindowAlternateTitle for more information about alternate window titles.

Availability
Declared In
MacWindows.h

CopyWindowGroupName

Obtains a copy of the window group name. 

OSStatus CopyWindowGroupName (
   WindowGroupRef inGroup,
   CFStringRef *outName
);

Parameters
inGroup

The window group to query. For information on this data type,

outName
Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

CopyWindowTitleAsCFString

Copies the window title into a Core Foundation string.

OSStatus CopyWindowTitleAsCFString (
   WindowRef inWindow,
   CFStringRef *outString
);

Parameters
inWindow

The window whose title is to be copied.

outString

On output, the window’s title.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Related Sample Code
Declared In
MacWindows.h

CountWindowGroupContents

Counts the number of members of a window group. 

ItemCount CountWindowGroupContents (
   WindowGroupRef inGroup,
   WindowGroupContentOptions inOptions
);

Parameters
inGroup

The window group whose members are to be counted.

inOptions

Counting options. See “Window Group Content Options” for possible constants to pass.

Availability
Declared In
MacWindows.h

CreateCustomWindow

Creates a custom window based on a registered toolbox object class or a custom window root view.

OSStatus CreateCustomWindow (
   const WindowDefSpec *def,
   WindowClass windowClass,
   WindowAttributes attributes,
   const Rect *contentBounds,
   WindowRef *outWindow
);

Parameters
def

For information on this data type, see WindowDefSpec.

windowClass

The class the custom window should belong to. This value determines the layer ordering of the custom window.

attributes

Attributes for the window. See “Window Attributes” for a list of possible attributes.

contentBounds

Pointer to a Rect structure in global coordinates indicating the dimensions of the window’s content region.

outWindow

On return, the newly-created window.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
See Also
Declared In
MacWindows.h

CreateNewWindow

Creates a window from parameter data.

OSStatus CreateNewWindow (
   WindowClass windowClass,
   WindowAttributes attributes,
   const Rect *contentBounds,
   WindowRef *outWindow
);

Parameters
windowClass

A constant that categorizes the class of window to be created. For certain classes, the window class can be altered after the window is created by calling HIWindowChangeClass. See “Window Class Constants” for a description of possible values for this parameter.

attributes

Attributes for the window. See “Window Attributes” for a list of possible attributes.

contentBounds

Pointer to a Rect structure in global coordinates indicating the dimensions of the window’s content region.

outWindow

On input, a pointer to a value of type WindowRef. On return, the window pointer points to the newly created window.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The CreateNewWindow function creates a window based on the attributes and class you specify in the attributes and windowClass parameters. CreateNewWindow sets the new window’s content region to the size and location specified by the rectangle passed in the bounds parameter, which in turn determines the dimensions of the entire window. The Window Manager creates the window invisibly and places it at the front of the window’s window group. After calling CreateNewWindow, you should set any desired associated data—using Window Manager or Control Manager accessor functions—then call the function TransitionWindow or ShowWindow to display the window.

Availability
See Also
Related Sample Code
Declared In
MacWindows.h

CreateStandardWindowMenu

Creates a standard window menu for your application. 

OSStatus CreateStandardWindowMenu (
   OptionBits inOptions,
   MenuRef *outMenu
);

Parameters
inOptions

Option bits. Pass 0 or kWindowMenuIncludeRotate. For information on the kWindowMenuIncludeRotate constant, see “Window Menu Item Property Constants.”

outMenu

On output, a new menu reference that contains the standard window menu items and commands.

Return Value

A result code. See “Window Manager Result Codes.” An operating system status code.

Discussion

You can call this function to create a window menu for your application. To register a window to be tracked by this menu, you either create your window with CreateNewWindow, passing the kWindowInWindowMenuAttribute, or you can use ChangeWindowAttributes after the window is created. The Toolbox takes care of acting on the standard items such as zoom and minimize, as well as bringing selected windows to the front. All you need to do is insert the menu in your menu bar (typically at the end of your menu list) and register your windows, and the Toolbox does the rest.

Availability
Declared In
MacWindows.h

CreateWindowGroup

Creates a window group. 

OSStatus CreateWindowGroup (
   WindowGroupAttributes inAttributes,
   WindowGroupRef *outGroup
);

Parameters
inAttributes

Attributes for the new window group. See “Window Group Attributes” for a listing of possible attributes.

outGroup

For information on this data type, see WindowGroupRef.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

DebugPrintAllWindowGroups

Debugging utility function listing all window groups. 

void DebugPrintAllWindowGroups (
   void
);

Carbon Porting Notes
Availability
Declared In
HIToolboxDebugging.h

DebugPrintWindowGroup

Debugging utility functions for use with window groups. 

void DebugPrintWindowGroup (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group. For information on this data type,

Availability
Declared In
HIToolboxDebugging.h

DetachSheetWindow

Detaches a sheet window from its parent window.

OSStatus DetachSheetWindow (
   WindowRef inSheet
);

Parameters
inSheet

The window sheet that is to be detached from its parent window.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function detaches a sheet window from its parent window without affecting the visibility or position of the sheet or its parent. This function is useful for hiding a sheet window without an animation effect. To do so, call DetachSheetWindow to detach the sheet from the parent, and then call HideWindow to hide the sheet. Call DisposeWindow to destroy the sheet.

Availability
Declared In
MacWindows.h

DisableScreenUpdates

Disables updates for changes to the current application’s windows.

OSStatus DisableScreenUpdates (
   void
);

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

DisposeWindow

Removes a window.

void DisposeWindow (
   WindowRef window
);

Parameters
window

On input, the window to be closed.

Discussion

The DisposeWindow function reduces a window’s reference count by one. If the resulting reference count is zero, then DisposeWindow removes the window from the screen and deletes it from the window list, then releases the memory occupied by all structures associated with the window, including the window structure.

Note that DisposeWindow assumes that any picture pointed to by the window structure field windowPic is data, not a resource, and it calls the QuickDraw function KillPicture to delete it. If your application uses a picture stored as a resource, you must release the resource or release the memory it occupies with the ReleaseResource function and set the windowPic field to NULL before closing the window.

Any pending update events for the window are discarded. If the window being removed is the frontmost window, the window behind it, if any, becomes the active window.

Availability
Related Sample Code
Declared In
MacWindows.h

DragWindow

Moves a window on the screen when the user drags it by its drag region.

void DragWindow (
   WindowRef window,
   Point startPt,
   const Rect *boundsRect
);

Parameters
window

The window that is to be dragged.

startPt

On input, the location, in global coordinates, of the cursor at the time the user pressed the mouse button. Your application retrieves this point from the where field of the event structure.

boundsRect

On input, a pointer to a rectangle, given in global coordinates, that limits the region to which a window can be dragged. If the mouse button is released when the cursor is outside the limits of boundsRect, DragWindow returns without moving the window (or, if it was inactive, without making it the active window).

In CarbonLib and Mac OS X, this parameter can be NULL to indicate that there are no restrictions on window movement. This parameter is ignored by CarbonLib and Mac OS X v10.0 through v10.2; it is obeyed in Mac OX v10.3 and later.

Discussion

The DragWindow function moves the window around the screen, following the movement of the cursor until the user releases the mouse button. If the Command key was not pressed when the mouse button was pressed, DragWindow calls SelectWindow to make the window active before it drags the window. If the Command key was pressed when the mouse button was pressed, DragWindow moves the window without making it active.

Availability
Related Sample Code
Declared In
MacWindows.h

EnableScreenUpdates

Enables screen updates for changes to the current application’s windows.

OSStatus EnableScreenUpdates (
   void
);

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

EndUpdate

Finishes updating a window.

void EndUpdate (
   WindowRef window
);

Parameters
window

The window for which updating is to be finished.

Discussion

The EndUpdate function restores the normal visible region of a window’s graphics port. When you receive an update event for a window, you call BeginUpdate, redraw the update region, and then call EndUpdate. Each call to BeginUpdate must be balanced by a subsequent call to EndUpdate.

Special Considerations

This function should not be used on composited windows. Modifying a composited window's update region does not affect the area of the window to be drawn. A composited window does not use its window update region to control drawing. Instead, a composited window determines what to draw by looking at the invalid regions of the views contained in the window.

Availability
Related Sample Code
Declared In
MacWindows.h

EndWindowProxyDrag

Disposes of the drag reference when the user completes the drag of a proxy icon.

OSStatus EndWindowProxyDrag (
   WindowRef window,
   DragRef theDrag
);

Parameters
window

The window whose proxy icon is being dragged.

theDrag

A value that refers to the current drag process. Pass in the value produced in the outNewDrag parameter of BeginWindowProxyDrag.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Typically, if the proxy icon represents a type of object (currently, file system entities such as files, folders, and volumes) supported by the Window Manager, the Window Manager can handle all aspects of the drag process itself, and your application should call the function TrackWindowProxyDrag. However, if the proxy icon represents a type of data that the Window Manager does not support, or if you want to implement custom dragging behavior, your application should call the function TrackWindowProxyFromExistingDrag.

The TrackWindowProxyFromExistingDrag function accepts an existing drag reference and adds file data if the window contains a file proxy. If your application uses TrackWindowProxyFromExistingDrag, you then have the choice of using this function in conjunction with the functions BeginWindowProxyDrag and EndWindowProxyDrag or simply calling TrackWindowProxyFromExistingDrag and handling all aspects of creating and disposing of the drag yourself.

Specifically, your application can call BeginWindowProxyDrag to set up the drag image and drag reference. Your application must then track the drag, using TrackWindowProxyFromExistingDrag, and do any required moving of data and, finally, call EndWindowProxyDrag to dispose of the drag reference and its associated image data. The EndWindowProxyDrag function does not dispose of the region created for use by BeginWindowProxyDrag, however, so this remains the application’s responsibility to dispose. The EndWindowProxyDrag function should not be used for types handled by the Window Manager unless you want to implement custom dragging behavior for those types.

Availability
Declared In
MacWindows.h

FindWindow

Maps the location of the cursor to a part of the screen or a region of a window when your application receives a mouse-down event.

WindowPartCode FindWindow (
   Point thePoint,
   WindowRef *window
);

Parameters
thePoint

The point, in global coordinates, where the mouse-down event occurred. Your application retrieves this information from the where field of the event structure.

window

A pointer to the window in which the mouse-down event occurred. FindWindow produces NULL if the mouse-down event occurred outside a window.

Return Value

The location of the cursor when the user pressed the mouse button; see “Window Part Code Constants.”

Discussion

You typically call the function FindWindow whenever you receive a mouse-down event. The FindWindow function helps you dispatch the event by reporting whether the cursor was in the menu bar or in a window when the mouse button was pressed. If the cursor was in a window, the function will produce both a pointer to the window and a constant that identifies the region of the window in which the event occurred.

If you are using the Carbon event handlers to handle events, a faster way of getting the window and part that received a mouse-down event is to get the kEventParamWindowRef and kEventParamWindowPartCode parameters from the event.

Availability
See Also
Related Sample Code
Declared In
MacWindows.h

FindWindowOfClass

Finds a window of a specific class at the specified point onscreen.

OSStatus FindWindowOfClass (
   const Point *where,
   WindowClass inWindowClass,
   WindowRef *outWindow,
   WindowPartCode *outWindowPart
);

Parameters
where

The point, in global coordinates, at which to search for a window.

inWindowClass

The class of window for which to search. Passing kAllWindowClasses returns any window found at where.

outWindow

On return, a pointer to the window, if it is of the specified class. If no window was found, this value is NULL. Note that you can pass NULL for this parameter.

outWindowPart

On return, the part code of the window part under the mouse. If no window was found, this value is inDesk. Note that you can pass NULL for this parameter.

Return Value

A result code. If no window of the specified class is found at the specified point, this function returns errWindowNotFound. For other possible return values, see “Window Manager Result Codes.”

Discussion

This function is similar to FindWindow, but lets you restrict the search to windows of a particular class.

Availability
See Also
Declared In
MacWindows.h

FrontNonFloatingWindow

Returns to the application the frontmost visible window that is not a floating window.

WindowRef FrontNonFloatingWindow (
   void
);

Return Value

The first visible window in the window list that is of a nonfloating class. See “Window Class Constants” for a description of window classes.

Discussion

Your application should call the FrontNonFloatingWindow function when you want to identify the frontmost visible window that is not a floating window. If you want to identify the frontmost visible window, whether floating or not, your application should call the function FrontWindow.

Availability
Related Sample Code
Declared In
MacWindows.h

GetAvailableWindowAttributes

Returns the window attributes that are valid for a window class

WindowAttributes GetAvailableWindowAttributes (
   WindowClass inClass
);

Parameters
inClass

The window class to query.

Return Value

The window attributes that are valid for the window class specified by inClass. See “Window Attributes” for a list of possible attributes.

Discussion

Some window classes support different attributes on different platforms. For example, floating windows can have collapse boxes in Mac OS 9, but not in Mac OS X. The Window Manager returns an error if you attempt to create a window with attributes that aren’t supported for the requested window class.

You can use this API to determine those attributes that are supported by the current platform and remove those attributes that are not supported by the current platform before calling CreateNewWindow.

Availability
Declared In
MacWindows.h

GetAvailableWindowPositioningBounds

Obtains the available window positioning bounds.

OSStatus GetAvailableWindowPositioningBounds (
   GDHandle inDevice,
   Rect *outAvailableRect
);

Parameters
inDevice

The screen for which the available window positioning bounds are to be obtained.

outAvailableRect

On return, a pointer to the available bounds for the device specified by inDevice.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The available window positioning bounds is that area on the screen inside which a window may be positioned without intersecting or overlapping the menu bar, Dock, or other UI provided by the operating system.

Availability
Declared In
MacWindows.h

GetAvailableWindowPositioningRegion

Obtains the available window positioning region.

OSStatus GetAvailableWindowPositioningRegion (
   GDHandle inDevice,
   RgnHandle ioRgn
);

Parameters
inDevice

The screen for which the available window positioning region is to be obtained.

ioRgn

On input, contains a preallocated RgnHandle. On return, the RgnHandle has been modified to contain the available region for the given screen.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The available window positioning region is that area on the screen inside which a window may be positioned without intersecting or overlapping the menu bar, Dock, or other UI provided by the operating system. This function differs from GetAvailableWindowPositioningBounds in that the bounds version removes the entire area that may theoretically be covered by the Dock, even if the Dock does not currently reach from edge to edge of the device on which it is positioned. The region version includes the area at the sides of the Dock that is not covered by the Dock in the available region.

Availability
Declared In
MacWindows.h

GetDrawerCurrentEdge

Obtains the current window edge from which the drawer appears. 

OptionBits GetDrawerCurrentEdge (
   WindowRef inDrawerWindow
);

Parameters
inDrawerWindow

The drawer window whose window edge is to be obtained.

Return Value

The current window edge. See “Window Edge Constants” for a list of possible return values.

Availability
Declared In
MacWindows.h

GetDrawerOffsets

Obtains the positioning offsets of a drawer. 

OSStatus GetDrawerOffsets (
   WindowRef inDrawerWindow,
   CGFloat *outLeadingOffset,
   CGFloat *outTrailingOffset
);

Parameters
inDrawerWindow

The drawer window whose positioning offsets are to be obtained.

outLeadingOffset

On exit, a pointer to the drawer’s leading offset. Pass NULL if you don’t need this information.

outTrailingOffset

On exit, a pointer to the drawer’s trailing offset. Pass NULL if you don’t need this information.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetDrawerParent

Obtains the parent window of a drawer. 

WindowRef GetDrawerParent (
   WindowRef inDrawerWindow
);

Parameters
inDrawerWindow

The drawer window whose parent window is to be obtained.

Return Value

The window that is the parent of the drawer specified by inDrawerWindow.

Availability
Declared In
MacWindows.h

GetDrawerPreferredEdge

Obtains the preferred opening edge for a drawer. 

OptionBits GetDrawerPreferredEdge (
   WindowRef inDrawerWindow
);

Parameters
inDrawerWindow

The drawer window whose preferred opening edge is to be obtained.

Return Value

See “Window Edge Constants” for a list of possible values.

Discussion

Note that the preferred edge may not be the same as the current edge, due to window positioning. For example, the right edge may be the preferred edge, but if the window is placed such that the right edge is offscreen, the drawer will appear on the left edge instead.

Availability
Declared In
MacWindows.h

GetDrawerState

Determines the current state of the drawer. 

WindowDrawerState GetDrawerState (
   WindowRef inDrawerWindow
);

Parameters
inDrawerWindow

The drawer window whose state is to be determined.

Return Value

See “Drawer State Constants” for a list of possible values.

Availability
Declared In
MacWindows.h

GetFrontWindowOfClass

Obtains the frontmost window of a given class. 

WindowRef GetFrontWindowOfClass (
   WindowClass inWindowClass,
   Boolean mustBeVisible
);

Parameters
inWindowClass

The class of the window you want to obtain. If you pass kAllWindowClasses, the function returns the frontmost window in the window list.

mustBeVisible

If set to true, the function returns the frontmost visible window. If set to false, the function returns the frontmost window of the specified class, regardless of whether the window is visible.

Return Value

A reference to the frontmost window of the class specified by inWindowClass.

Carbon Porting Notes
Availability
Related Sample Code
Declared In
MacWindows.h

GetIndexedWindow

Obtains the window at the given index in the window group. 

OSStatus GetIndexedWindow (
   WindowGroupRef inGroup,
   ItemCount inIndex,
   WindowGroupContentOptions inOptions,
   WindowRef *outWindow
);

Parameters
inGroup

The window group. For information on this data type,

inIndex

The index of the window. This parameter may range from 1 to the value returned by CountWindowGroupContents.

inOptions

Options for determining the number of windows. See “Window Group Content Options” for possible values.

outWindow

The window at the index specified by inIndex in the group specified by inGroup.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetNextWindow

Returns the next window in a window list.

WindowRef GetNextWindow (
   WindowRef window
);

Parameters
window

The window to start from.

Return Value

The next window in a window list.

Availability
Declared In
MacWindows.h

GetNextWindowOfClass

Obtains the next window in a given window group. 

WindowRef GetNextWindowOfClass (
   WindowRef inWindow,
   WindowClass inWindowClass,
   Boolean mustBeVisible
);

Parameters
inWindow

The window at which to start.

inWindowClass

The class of window to obtain. If you pass kAllWindowClasses, the function returns the window directly behind the input window. If no windows exist behind the front window, the function returns NULL.

mustBeVisible

If set to true, this function returns the next visible window of the specified window class. If set to false, this function returns the next window of the specified window class, regardless of whether it is visible.

Return Value

A reference for the next window of the specified class after the window specified by inWindow.

Availability
Related Sample Code
Declared In
MacWindows.h

GetPreviousWindow

Returns the window above the specified window in the window list.

WindowRef GetPreviousWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window at which to start.

Return Value

A reference for the previous window of the specified class.

Availability
Declared In
MacWindows.h

GetSheetWindowParent

Obtains the parent window of a sheet. 

OSStatus GetSheetWindowParent (
   WindowRef inSheet,
   WindowRef *outParentWindow
);

Parameters
inSheet

The window sheet whose parent is to be obtained.

outParentWindow

A pointer to the reference for the parent of the window sheet specified by inSheet.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetUserFocusWindow

Returns the current user focus window.

WindowRef GetUserFocusWindow (
   void
);

Return Value

The window receiving user focus.

Discussion

This function returns the window that receives menu commands and keyboard input as part of the standard event dispatching.

Availability
Declared In
MacWindows.h

GetWindowActivationScope

Obtains a window’s activation scope. 

OSStatus GetWindowActivationScope (
   WindowRef inWindow,
   WindowActivationScope *outScope
);

Parameters
inWindow

The window whose activation scope is to be obtained.

outScope

On return, a pointer to the window’s activation scope.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowAlpha

Returns the current alpha channel value for the window. 

OSStatus GetWindowAlpha (
   WindowRef inWindow,
   CGFloat *outAlpha
);

Parameters
inWindow

The window for which the value of the alpha channel is to be obtained.

outAlpha

The current alpha value. This value can range from 0.0 (completely transparent) to 1.0 (opaque).

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowAttributes

Obtains the attributes of a window.

OSStatus GetWindowAttributes (
   WindowRef window,
   WindowAttributes *outAttributes
);

Parameters
window

The window whose attributes you want to obtain.

outAttributes

On input, a pointer to an unsigned 32-bit value of type WindowAttributes. On return, the bits are set to the attributes of the specified window. See “Window Attributes” for a description of possible attributes.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Window attributes specify a window’s features (such as whether the window has a close box) and logical attributes (such as whether the window receives update and activate events).

Availability
Declared In
MacWindows.h

GetWindowBounds

Obtains the size and position of the bounding rectangle of the specified window region.

OSStatus GetWindowBounds (
   WindowRef window,
   WindowRegionCode regionCode,
   Rect *globalBounds
);

Parameters
window

The window whose bounds you want to obtain.

regionCode

A constant identifying the window region whose bounds you want to obtain. See “Window Region Constants” for a list of possible values.

globalBounds

A pointer to a structure of type Rect. On return, the rectangle contains the dimensions and position, in global coordinates, of the window region specified in the regionCode parameter.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Use the GetWindowBounds function to obtain the bounding rectangle for the specified window region for the specified window.

Availability
See Also
Related Sample Code
Declared In
MacWindows.h

GetWindowCancelButton

Returns the current Cancel button for a window.

OSStatus GetWindowCancelButton (
   WindowRef inWindow,
   ControlRef *outControl
);

Parameters
inWindow

The window whose Cancel button you want to obtain.

outControl

A pointer to a control. On output, the control is the Cancel button.

Return Value

A result code.

Discussion

You can use this function to determine which button or control is the specified Cancel button for a given window. This button would be considered to have been clicked if the user instead presses Command-period or the Escape key.

Availability
Declared In
MacWindows.h

GetWindowClass

Obtains the class of a window.

OSStatus GetWindowClass (
   WindowRef window,
   WindowClass *outClass
);

Parameters
window

The window whose class you want to obtain.

outClass

On input, a pointer to a value of type WindowClass. On return, this value identifies the class of the specified window. See “Window Class Constants” for a list of possible window classes. In Mac OS 8 and Mac OS 9, for windows not originally created by CreateNewWindow, the class pointed to by the outClass parameter is always identified by the constant kDocumentWindowClass.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowContentColor

Obtains the color to which a window’s content region is redrawn.

OSStatus GetWindowContentColor (
   WindowRef window,
   RGBColor *color
);

Parameters
window

The window whose content color is being retrieved.

color

On input, a pointer to an RGBColor structure. On return, the structure contains the content color for the specified window.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The GetWindowContentColor function obtains the color to which the window’s content region is redrawn.

See also the function SetWindowContentColor.

Availability
Declared In
MacWindows.h

GetWindowContentPattern

Obtains the pattern to which a window’s content region is redrawn.

OSStatus GetWindowContentPattern (
   WindowRef window,
   PixPatHandle outPixPat
);

Parameters
window

The window whose content pattern is being retrieved.

outPixPat

On input, a handle to a structure of type PixPat. On return, the structure contains a copy of the content pattern data for the specified window, which your application is responsible for disposing.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The GetWindowContentPattern function obtains the pattern to which the window’s content region is redrawn.

See also the function SetWindowContentPattern.

Availability
Declared In
MacWindows.h

GetWindowDefaultButton

Returns the current default button for a window.

OSStatus GetWindowDefaultButton (
   WindowRef inWindow,
   ControlRef *outControl
);

Parameters
inWindow

The window whose default button you want to obtain.

outControl

A pointer to a control. On output, the control is the default button.

Return Value

A result code.

Discussion

You can use this function to determine which button or control is the default for a given window. This button would be considered to have been clicked if the user instead presses the Return or Enter keys on the keyboard.

Availability
Declared In
MacWindows.h

GetWindowDockTileMenu

Returns the menu to be displayed by a window’s dock tile. 

MenuRef GetWindowDockTileMenu (
   WindowRef inWindow
);

Parameters
inWindow

The window whose menu is to be obtained.

Return Value

The menu reference for the window specified by inWindow. See the Menu Manager documentation for a description of the MenuRef data type.

Availability
Declared In
MacWindows.h

GetWindowFeatures

Obtains the features that a window supports. 

OSStatus GetWindowFeatures (
   WindowRef window,
   UInt32 *outFeatures
);

Parameters
window

A pointer to the window to be examined.

outFeatures

On input, a pointer to an unsigned 32-bit value. On return, the bits of the value specify the features the window supports; see “Window Feature Bits.”

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The GetWindowFeatures function produces a window definition function’s features in response to a kWindowMsgGetFeatures message.

Instead of calling this function, most applications should call GetWindowAttributes to check for specific attributes, such as kWindowCollapseBoxAttribute and kWindowResizableAttribute.

Availability
Declared In
MacWindows.h

GetWindowFromPort

Gets a window reference from a CGrafPtr data type.

WindowRef GetWindowFromPort (
   CGrafPtr port
);

Parameters
port

The port to query.

Return Value

The window reference obtained from the port specified by port, or NULL if the port parameter is not actually attached to a window.

Availability
Declared In
MacWindows.h

GetWindowGreatestAreaDevice

Returns the graphics device with the greatest area of intersection with a specified window region.

OSStatus GetWindowGreatestAreaDevice (
   WindowRef inWindow,
   WindowRegionCode inRegion,
   GDHandle *outGreatestDevice,
   Rect *outGreatestDeviceRect
);

Parameters
inWindow

The window to compare against.

inRegion

The window region to compare against. See “Window Region Constants” for a list of possible values.

outGreatestDevice

On return, the graphics device with the greatest intersection. May be NULL.

outGreatestDeviceRect

On return, the bounds of the graphics device with the greatest intersection. May be NULL. If the device with the greatest intersection also contains the menu bar, the device rect will exclude the menu bar area.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowGroup

Obtains the window group associated with a window. 

WindowGroupRef GetWindowGroup (
   WindowRef inWindow
);

Parameters
inWindow

The window whose window group is to be obtained.

Return Value

The window group reference for the window specified by inWindow. For information on this data type, see WindowGroupRef.

Availability
Declared In
MacWindows.h

GetWindowGroupAttributes

Obtains the attributes of a window group. 

OSStatus GetWindowGroupAttributes (
   WindowGroupRef inGroup,
   WindowGroupAttributes *outAttributes
);

Parameters
inGroup

The window group whose attributes are to be changed. For information on this data type,

outAttributes

On return, the attributes of the group. See “Window Group Attributes” for a list of possible values.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowGroupContents

Obtains the contents of a window group. 

OSStatus GetWindowGroupContents (
   WindowGroupRef inGroup,
   WindowGroupContentOptions inOptions,
   ItemCount inAllowedItems,
   ItemCount *outNumItems,
   void **outItems
);

Parameters
inGroup

The window group whose contents you want to obtain. For information on this data type, see WindowGroupRef.

inOptions

Options for determining how to count the group members. See “Window Group Content Options” for a list of possible values.

inAllowedItems

The number of items that will fit in outItems.

outNumItems

On return, the number of items in the group.

outItems

On entry, this parameter must be a pointer to a pre-allocated buffer in which the window group contents (either window references or window group references) are to be placed. On return, the buffer pointed to by this parameter contains the requested window references or window group references.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowGroupLevel

Obtains the level of the group in the window class hierarchy. 

OSStatus GetWindowGroupLevel (
   WindowGroupRef inGroup,
   SInt32 *outLevel
);

Parameters
inGroup

The window group. For information on this data type,

outLevel

On exit, the window level of the windows in this group.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The window group’s level is only used to set the level of its windows if the window group is a child of the root group. If there is another group in the group hierarchy between this group and the root group, this group’s level is ignored.

See the Core Graphics frameworks header CGWindowLevel.h for a listing of window levels.

Availability
Declared In
MacWindows.h

GetWindowGroupLevelOfType

Obtains the Core Graphics window level of a window group.

OSStatus GetWindowGroupLevelOfType (
   WindowGroupRef inGroup,
   UInt32 inLevelType,
   CGWindowLevel *outLevel
);

Parameters
inGroup

The window group whose Core Graphics window level is to be obtained.

inLevelType

The level type to obtain. Specify kWindowGroupLevelActive, kWindowGroupLevelInactive, or kWindowGroupLevelPromoted. For details, see “Window Group Level Constants.”

outLevel

On output, the Core Graphics window level for the windows in this group.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

In Mac OS X v10.4 and later, multiple Core Graphics window levels may be associated with a window group: one level for when the application is active and another for when the application is inactive. The Window Manager automatically switches each group’s Core Graphics window level as the application becomes active or inactive. Use GetWindowGroupLevelOfType to get each Core Graphics window level associated with a window group, including the promoted window level that is actually in use for windows in the group when the application is active.

Availability
Declared In
MacWindows.h

GetWindowGroupOfClass

Obtains the window group corresponding to a given window class. 

WindowGroupRef GetWindowGroupOfClass (
   WindowClass windowClass
);

Parameters
windowClass

The window class to query.

Return Value

For information on this data type, see WindowGroupRef.

Discussion

Each window class has an associated pre-defined window group. This function returns the window group reference for the window group that is associated with windowClass. Note that all windows in a group do not have to be of the same window class.

Availability
Declared In
MacWindows.h

GetWindowGroupOwner

Obtains the window that owns a window group. (if any)

WindowRef GetWindowGroupOwner (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group to query. For information on this data type,

Return Value

The window reference for the window that owns the group specified by inGroup.

Discussion

You call SetWindowGroupOwner to associate a window group with a particular window.

Availability
Declared In
MacWindows.h

GetWindowGroupParent

Obtains the parent group of a window group. 

WindowGroupRef GetWindowGroupParent (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group whose parent is to be obtained.

Return Value

The parent of the window group specified by inGroup.

Discussion

You can nest window groups within each other.

Availability
Declared In
MacWindows.h

GetWindowGroupRetainCount

Determines the current reference count for a window group. 

ItemCount GetWindowGroupRetainCount (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group for which the current reference count is to be obtained. For information on this data type, see WindowGroupRef.

Availability
Declared In
MacWindows.h

GetWindowGroupSibling

Obtains the next or previous group of a window group.

WindowGroupRef GetWindowGroupSibling (
   WindowGroupRef inGroup,
   Boolean inNextGroup
);

Parameters
inGroup

The window group for which the next or previous group is to be obtained. For information on this data type, see WindowGroupRef.

inNextGroup

Pass true to obtain the next sibling; false to obtain the previous sibling.

Return Value

The next or previous group. For information on this data type, see WindowGroupRef.

Availability
Declared In
MacWindows.h

GetWindowIdealUserState

Obtains the size and position of a window in its user state.

OSStatus GetWindowIdealUserState (
   WindowRef inWindow,
   Rect *outUserState
);

Parameters
inWindow

The window for which you want to obtain the user state.

outUserState

On input, a pointer to a structure of type Rect. On return, this rectangle specifies the current size and position of the window’s user state, in global coordinates.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Because the window definition function relies upon the WStateData structure, it is unaware of the ideal standard state, and this causes the user state data that it stores in the WStateData structure to be unreliable. While the Window Manager is reliably aware of the window’s zoom state, it cannot record the current user state in the WStateData structure, because the window definition function can overwrite that data. Therefore, the function ZoomWindowIdeal maintains the window’s user state independently of the WStateData structure. The GetWindowIdealUserState function gives your application access to the user state data maintained by ZoomWindowIdeal. However, your application should not typically need to use this function; it is supplied for completeness.

Availability
See Also
Declared In
MacWindows.h

GetWindowIndex

Obtains the index number of a specified window in a group. 

OSStatus GetWindowIndex (
   WindowRef inWindow,
   WindowGroupRef inStartGroup,
   WindowGroupContentOptions inOptions,
   ItemCount *outIndex
);

Parameters
inWindow

The window whose window group index number is to be obtained.

inStartGroup

The window group to query.

inOptions

Specifies how to enumerate the specified window; kWindowGroupContentsReturnWindows is implied and does not need to be specified explicitly.

outIndex

A pointer to a variable that, on return, contains the window’s z-order index. The frontmost window in a window group has an index of 1. Window indexes increase as the window gets lower in z-order (that is, visually further from the top of the window list and closer to the desktop.)

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowKind

Returns a window’s window kind.

short GetWindowKind (
   WindowRef window
);

Parameters
window

The window whose window kind is to be returned.

Return Value

An integer representing the window kind; see “Window Kinds.”

Availability
Declared In
MacWindows.h

GetWindowList

Obtains the first window in a window list.

WindowRef GetWindowList (
   void
);

Return Value

A window reference for the first window in the list.

Availability
Declared In
MacWindows.h

GetWindowModality

Obtains the modality of a window.

OSStatus GetWindowModality (
   WindowRef inWindow,
   WindowModality *outModalKind,
   WindowRef *outUnavailableWindow
);

Parameters
inWindow

The window whose modality is to be obtained.

outModalKind

On return, contains the modality of the window.

outUnavailableWindow

On return, if the window is window-modal, contains the target window of the specified window’s modality.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowPort

Gets the window’s color graphics port.

CGrafPtr GetWindowPort (
   WindowRef window
);

Parameters
window

The window whose color graphics port is to be obtained.

Return Value

A pointer to the window’s color graphics port. See the QuickDraw Manager documentation for a description of the CGrafPtr data type.

Availability
Related Sample Code
Declared In
MacWindows.h

GetWindowPortBounds

Obtains the bounds of the window port. 

Rect * GetWindowPortBounds (
   WindowRef window,
   Rect *bounds
);

Parameters
window

The window whose port bounds you want.

bounds

A pointer to a Rect structure. On return, the Rect structure contains the bounds of the window port.

Return Value

The same value (pointer to a Rect structure) that was passed to GetWindowPortBounds in the bounds parameter.

Availability
Related Sample Code
Declared In
MacWindows.h

GetWindowProperty

Obtains a piece of data that is associated with a window.

OSStatus GetWindowProperty (
   WindowRef window,
   PropertyCreator propertyCreator,
   PropertyTag propertyTag,
   ByteCount bufferSize,
   ByteCount *actualSize,
   void *propertyBuffer
);

Parameters
window

The window to be examined for associated data.

propertyCreator

The creator code (typically, the application’s signature) of the associated data to be obtained.

propertyTag

The application-defined code identifying the associated data to be obtained.

bufferSize

The size of the associated data to be obtained. If the size of the data is unknown, use the function GetWindowPropertySize to get the data’s size. If the size specified does not match the actual size of the property, GetWindowProperty only retrieves data up to the size specified or up to the actual size of the property, whichever is smaller, and an error is returned.

actualSize

On input, a pointer to a value. On return, the value specifies the actual size of the obtained data. You may pass NULL for the actualSize parameter if you are not interested in this information.

propertyBuffer

On input, a pointer to a buffer. On return, this buffer contains a copy of the data that is associated with the specified window.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The data retrieved by the GetWindowProperty function must have been previously associated with the window with the function SetWindowProperty.

Availability
Related Sample Code
Declared In
MacWindows.h

GetWindowPropertyAttributes

Obtains the attributes of a window property. 

OSStatus GetWindowPropertyAttributes (
   WindowRef window,
   OSType propertyCreator,
   OSType propertyTag,
   OptionBits *attributes
);

Parameters
window

The window having a property whose attributes are to be obtained.

propertyCreator

The property creator.

propertyTag

The property tag.

attributes

On return, the property’s attributes. Currently, the only valid property is kWindowPropertyPersistent. For a description of this property, see “Window Property Persistent Constant.”

Return Value

A result code. See “Window Manager Result Codes.”

Carbon Porting Notes
Availability
Declared In
MacWindows.h

GetWindowPropertySize

Obtains the size of a piece of data that is associated with a window.

OSStatus GetWindowPropertySize (
   WindowRef window,
   PropertyCreator creator,
   PropertyTag tag,
   ByteCount *size
);

Parameters
window

The window to be examined for associated data.

creator

The creator code (typically, the application’s signature) of the associated data whose size is to be obtained.

tag

The application-defined code identifying the associated data whose size is to be obtained.

size

A pointer to a value that, on return, specifies the size of the associated data.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If you want to retrieve a piece of associated data with the GetWindowProperty function, you typically need to use the GetWindowPropertySize function to determine the size of the data beforehand.

Availability
Declared In
MacWindows.h

GetWindowProxyAlias

Obtains an alias for the file that is associated with a window.

OSStatus GetWindowProxyAlias (
   WindowRef window,
   AliasHandle *alias
);

Parameters
window

The window for which you want to determine the associated file.

alias

On input, a pointer to a value of type AliasHandle. On return, the AliasRecord structure referenced by the alias handle contains a copy of the alias data for the file associated with the specified window. Your application must dispose of this handle.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Your application can call the GetWindowProxyAlias function to retrieve alias data for the file associated with a window.

See also the function SetWindowProxyAlias.

Availability
Declared In
MacWindows.h

GetWindowProxyIcon

Obtains a window’s proxy icon.

OSStatus GetWindowProxyIcon (
   WindowRef window,
   IconRef *outIcon
);

Parameters
window

The window for which you want to obtain the proxy icon.

outIcon

A pointer to a variable of type IconRef that, on return, identifies the window’s proxy icon. Your application must not dispose of this icon.

Return Value

A result code. If no proxy icon is found, this function returns errWindowDoesNotHaveProxy. For other possible return values, see “Window Manager Result Codes.”

Discussion

There are several different ways to associate a proxy icon with a window:

Availability
Declared In
MacWindows.h

GetWindowResizeLimits

Returns the minimum and maximum content sizes for a window. 

OSStatus GetWindowResizeLimits (
   WindowRef inWindow,
   HISize *outMinLimits,
   HISize *outMaxLimits
);

Parameters
inWindow

The window whose minimum and maximum content sizes are to be obtained.

outMinLimits

On return, the window’s minimum content size. Pass NULL if you don’t want this information. For information on the HISize data type, see HIGeometry.h.

outMaxLimits

On return, the window’s maximum content size. Pass NULL if you don’t want this information. For information on the HISize data type, see HIGeometry.h.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowStandardState

Obtains a window’s standard zoom rectangle.

Rect * GetWindowStandardState (
   WindowRef window,
   Rect *rect
);

Parameters
window

The window whose standard zoom rectangle is to be obtained.

rect

On input, a pointer to a Rect structure. On return, the Rect structure contains the window’s standard zoom rectangle, in global coordinates. A window’s standard zoom rectangle is the window content bounds when the window is zoomed out to its greatest extent.

Return Value

The same value (pointer to a Rect structure) that was passed to GetWindowStandardState in the rect parameter.

Availability
Declared In
MacWindows.h

GetWindowStructurePort

Obtains a graphics port that is used when drawing a window’s structure.

CGrafPtr GetWindowStructurePort (
   WindowRef inWindow
);

Parameters
inWindow

The window to query.

Return Value

The CGrafPtr that is used when drawing the window’s structure (window frame).

Availability
Declared In
MacWindows.h

GetWindowStructureWidths

Obtains the width of the structure region on each edge of a window.

OSStatus GetWindowStructureWidths (
   WindowRef inWindow,
   Rect *outRect
);

Parameters
inWindow

The window to query.

outRect

On return, the Rect structure is filled in with the widths of the structure.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowToolbar

Obtains the toolbar associated with a window. 

OSStatus GetWindowToolbar (
   WindowRef inWindow,
   HIToolbarRef *outToolbar
);

Parameters
inWindow

The window whose toolbar is to be obtained.

outToolbar

On return, the toolbar that is attached to the window, or NULL if the window has no toolbar.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWindowUserState

Returns a window’s user zoom rectangle.

Rect * GetWindowUserState (
   WindowRef window,
   Rect *rect
);

Parameters
window

The window whose user zoom rectangle is to be returned.

rect

On input, a pointer to a Rect structure. On return, the Rect structure contains the window’s user zoom rectangle, in global coordinates. A window’s user zoom rectangle is the window content bounds when the window is zoomed back in.

Return Value

The same value (pointer to a Rect structure) that was passed to GetWindowUserState in the rect parameter.

Availability
Declared In
MacWindows.h

GetWindowWidgetHilite

Obtains the window part code of the window widget that is currently highlighted.

OSStatus GetWindowWidgetHilite (
   WindowRef inWindow,
   WindowDefPartCode *outHilite
);

Parameters
inWindow

The window to query.

outHilite

The highlight.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

GetWRefCon

Returns the reference constant from a window.

SRefCon GetWRefCon (
   WindowRef window
);

Parameters
window

The window whose reference constant is to be returned.

Return Value

The long integer data stored in the refCon field of the window structure specified in the window parameter.

Availability
Related Sample Code
Declared In
MacWindows.h

HideFloatingWindows

Hides an application’s floating windows.

OSStatus HideFloatingWindows (
   void
);

Return Value

A result code. For details, see “Window Manager Result Codes.”

Discussion

When an application receives a suspend event, its floating windows are hidden automatically. When the application receives a resume event, the floating windows are made visible automatically. Call this function if you want to hide your floating windows manually.

See also the function ShowFloatingWindows.

Special Considerations

The HideFloatingWindows function operates only upon windows created with the kFloatingWindowClass constant; see “Window Class Constants” for more details on this constant.

Availability
Declared In
MacWindows.h

HideSheetWindow

Hides a sheet window using appropriate visual effects.

OSStatus HideSheetWindow (
   WindowRef inSheet
);

Parameters
inSheet

The window sheet that is to be hidden.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HideWindow

Makes a window invisible.

void HideWindow (
   WindowRef window
);

Parameters
window

The window that is to be made invisible.

Discussion

The HideWindow function make a visible window invisible. If you hide the frontmost window, HideWindow removes the highlighting, brings the window behind it to the front, highlights the new frontmost window, and generates the appropriate activate events.

To reverse the actions of HideWindow, you must call both ShowWindow, to make the window visible, and SelectWindow, to select it.

Availability
Declared In
MacWindows.h

HiliteWindow

Sets a window’s highlighting status.

void HiliteWindow (
   WindowRef window,
   Boolean fHilite
);

Parameters
window

On input, a pointer to the window structure.

fHilite

On input, a Boolean value that specifies the highlighting status: true highlights a window; false removes highlighting.

Discussion

The HiliteWindow function sets a window’s highlighting status to the specified state. If the value of the fHilite parameter is true, HiliteWindow highlights the specified window; if the specified window is already highlighted, the function has no effect. If the value of fHilite is false, HiliteWindow removes highlighting from the specified window; if the window is not already highlighted, the function has no effect.

Your application doesn’t normally need to call HiliteWindow. To make a window active, you can call SelectWindow or ActivateWindow, which handle highlighting for you.

Availability
Declared In
MacWindows.h

HiliteWindowFrameForDrag

Sets the highlight state of the window’s structure region to reflect the window’s validity as a drag-and-drop destination.

OSStatus HiliteWindowFrameForDrag (
   WindowRef window,
   Boolean hilited
);

Parameters
window

The window for which you want to set the highlight state.

hilited

Pass true if the window’s frame should be highlighted otherwise, pass false.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Applications typically call the Drag Manager functions ShowDragHilite and HideDragHilite to indicate that a window is a valid drag-and-drop destination. If your application does not do this—that is, if your application implements any type of custom drag highlighting, such as highlighting more than one area of a window at a time—it must call the HiliteWindowFrameForDrag function.

The HiliteWindowFrameForDrag function highlights a window’s proxy icon when the user drags content inside the window that is a valid content type for that destination. The default behavior of system-defined windows is to highlight the proxy icon along with the window’s content area when the window is a valid drag-and-drop destination. If you call the Drag Manager functions ShowDragHilite and HideDragHilite, you don’t need to use HiliteWindowFrameForDrag.

Availability
Declared In
MacWindows.h

HIWindowChangeAttributes

Changes the attributes of a window.

OSStatus HIWindowChangeAttributes (
   WindowRef inWindow,
   const int *inAttrToSet,
   const int *inAttrToClear
);

Parameters
inWindow

The window to change.

inAttrToSet

A zero-terminated array of window attribute constants. Possible values are described in “Window Attribute Identifiers”. Each array entry specifies an attribute of the window to set. You may pass NULL if you do not wish to set any attributes.

inAttrToClear

A zero-terminated array of window attribute constants. Possible values are described in “Window Attribute Identifiers”. Each array entry specifies an attribute of the window to clear. You may pass NULL if you do not wish to clear any attributes.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function takes two arrays of window attribute constants, as described in “Window Attribute Identifiers”. The first array specifies the attributes to set, and the second specifies the attributes to clear. For example, you might call this function as follows: 

int setAttr[] = { kHIWindowBitCloseBox, kHIWindowBitZoomBox, 0 };
int clearAttr[] = { kHIWindowBitNoTitleBar, 0 };
HIWindowChangeAttributes (window, setAttr, clearAttr);
Special Considerations

In Mac OS X v10.4 or earlier, you can use the function ChangeWindowAttributes to achieve similar results.

Availability
Declared In
MacWindows.h

HIWindowChangeAvailability

Changes the availability of a window during Exposé or in Spaces.

OSStatus HIWindowChangeAvailability (
   WindowRef inWindow,
   HIWindowAvailability inSetAvailability,
   HIWindowAvailability inClearAvailability
);

Parameters
inWindow

The window whose availability is to be changed.

inSetAvailability

The availability bits to set. For details, see “Window Availability Constants.”

inClearAvailability

The availability bits to clear. For details, see “Window Availability Constants.”

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function overrides the default behavior of the Window Manager in determining whether a window is visible during Exposé or in all Spaces workspaces. Most applications should not override the default behavior; these options should only be used in special cases. For example, accessibility assistance applications may need to create windows that are visible in all workspaces.

By default, newly created windows of class kDocumentWindowClass are given an availability of 0 (meaning that they are available during Exposé), and windows from all other window classes are given an availability of kHIWindowExposeHidden.

Availability
Declared In
MacWindows.h

HIWindowChangeClass

Changes the appearance and behavior of a window.

OSStatus HIWindowChangeClass (
   WindowRef inWindow,
   WindowClass inWindowClass
);

Parameters
window

The window whose class you want to change.

inClass

The new class that is to be applied to the window. See “Window Class Constants” for a list of possible window classes.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function changes the class of a window. Unlike SetWindowClass, HIWindowChangeClass effectively changes both the appearance and behavior of the window.

This function can convert a window between kDocumentWindowClass, kFloatingWindowClass, kUtilityWindowClass, and kMovableModalWindowClass only. It cannot, for example, change a document window into a plain window.

The attributes of the window are adjusted to contain only those that are allowed for the new class. It is the caller’s responsibility to adjust them further, as necessary, after HIWindowChangeClass returns.

Availability
Declared In
MacWindows.h

HIWindowChangeFeatures

Changes a window’s features.

OSStatus HIWindowChangeFeatures (
   WindowRef inWindow,
   UInt64 inSetThese,
   UInt64 inClearThese
);

Parameters
inWindow

The window whose features are to be changed.

inSetThese

The feature bits to set. For details, see “Window Feature Bits.”

inClearThese

The feature bits to clear. For details, see “Window Feature Bits.”

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

HIWindowChangeFeatures changes the features of a window on the fly. This function should only be used by custom window definitions or window frame views.

Availability
Declared In
MacWindows.h

HIWindowConstrain

Moves and resizes a window to be within a specified bounding rectangle.

OSStatus HIWindowConstrain (
   WindowRef inWindowRef,
   WindowRegionCode inRegionCode,
   WindowConstrainOptions inOptions,
   HICoordinateSpace inSpace,
   const HIRect *inScreenBounds,
   const HISize *inMinimumSize,
   HIRect *ioBounds
);

Parameters
inWindowRef

The window to constrain.

inRegionCode

The window region to constrain. For a list of possible values, see “Window Region Constants”.

inOptions

Flags controlling how the window is constrained. For a list of possible options, see “Window Constrain Options”.

inSpace

The coordinate space in which the inScreenBounds, inMinimumSize, and ioBounds parameters are expressed. This parameter must be either kHICoordSpaceScreenPixels or kHICoordSpace72DPIGlobal.

inScreenBounds

A rectangle within which to constrain the window. You may pass NULL if you don't need to specify a screen bounds. If NULL, the window is constrained to the screen that has the greatest intersection with the specified window region.

inMinimumSize

A minimum size that should be kept within the specified screen bounds. This parameter is ignored if the kWindowConstrainMoveMinimum option is not set. Even if that option is set, you may still pass NULL if you don't need to customize the minimum dimensions.

ioBounds

If the inOptions parameter contains kWindowConstrainUseSpecifiedBounds, then this parameter should be a bounding rectangle of the specified window region. The bounding rectangle does not have to match the actual current bounds of the specified region; it may be a hypothetical bounds that you would like to constrain without actually moving the window to that location. On output, contains the new structure bounds of the window. You may pass NULL if you don't need the window bounds returned.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HIWindowCopyAvailablePositioningShape

Copies the available window positioning shape on a display.

OSStatus HIWindowCopyAvailablePositioningShape (
   CGDirectDisplayID inDisplay,
   HICoordinateSpace inSpace,
   HIShapeRef *outShape
);

Parameters
inDisplay

The display for which to find the available shape. May be kCGNullDirectDisplay to request the shape of the main display.

inSpace

The coordinate space in which the positioning shape should be returned. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

outShape

A pointer to a shape (an HIShape object). On output, the shape describes the available bounds for the specified display. This shape is returned in the specified coordinate space. You should release the shape when you no longer need it.

Discussion

This function finds the area on the display in which a window may be positioned without intersecting or overlapping the menu bar, Dock, or other UI provided by the operating system. This function differs from HIWindowGetAvailablePositioningBounds in that the bounds version removes the entire area that may theoretically be covered by the Dock, even if the Dock does not currently reach from edge to edge of the display on which it is positioned. The shape version includes the area at the sides of the Dock that is not covered by the Dock.

Availability
Declared In
MacWindows.h

HIWindowCopyDrawers

Obtains an array of the drawers that are attached to a window.

OSStatus HIWindowCopyDrawers (
   WindowRef inWindow,
   CFArrayRef *outDrawers
);

Parameters
inWindow

The parent window to access.

outDrawers

A pointer to a Core Foundation array. On output, each array entry is a drawer window attached to the parent window specified in the inWindow parameter. The array will be valid, but empty, if the parent window has no drawers. You should release the array when you no longer need it.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HIWindowCopyShape

Retrieves a shape that describes a region of a window.

OSStatus HIWindowCopyShape (
   WindowRef inWindow,
   WindowRegionCode inRegion,
   HICoordinateSpace inSpace,
   HIShapeRef *outShape
);

Parameters
inWindow

The window to access.

inRegion

The window region whose shape you want to obtain. For a list of possible values, see “Window Region Constants.”

inSpace

The coordinate space in which the shape should be returned. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.

outShape

A pointer to a shape (an HIShape object). On output, the shape describes the specified window region. The shape is returned in the specified coordinate space. You should release the shape when you no longer need it. If the window does not support the specified window region, no shape is returned.

Return Value

A result code. If the window does not support the specified window region, the result returned is errWindowRegionCodeInvalid. For other possible values, see “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HIWindowCreate

Creates a standard or custom window.

OSStatus HIWindowCreate (
   WindowClass inClass,
   const int *inAttributes,
   const WindowDefSpec *inDefSpec,
   HICoordinateSpace inSpace,
   const HIRect *inBounds,
   WindowRef *outWindow
);

Parameters
inClass

The class of window to be created. For a list of possible classes, see “Window Class Constants”.

inAttributes

A zero-terminated array of window attribute constants. Each array entry specifies an attribute of the window to set. You may pass NULL if you don't need to set any attributes. For a list of possible attributes, see “Window Attribute Identifiers”.

inDefSpec

A pointer to a custom window proc ID or root view for the window. You may pass NULL if you don't need to customize the window.

inSpace

The coordinate space in which the content bounds is expressed. This parameter must be either kHICoordSpaceScreenPixels or kHICoordSpace72DPIGlobal.

inBounds

A pointer to the bounds of the content area of the window in the coordinate space specified by the inSpace parameter. If you specify non-integral coordinates, they will be rounded to the nearest integral value in screen pixel space when the window is actually positioned or sized.

outWindow

A pointer to a window variable. On output, the variable contains the new window.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function makes it possible to create windows with content bounds expressed in different coordinate spaces. In Mac OS X v10.5 and later, you can use this function in place of CreateNewWindow or CreateCustomWindow to create a window from a set of parameters.

Most developers will want to work primarily in the 72 DPI coordinate space. Doing so makes your code independent of the current user interface scale factor, and eases source compatibility with earlier versions of Mac OS X that do not support resolution independence. However, there are also certain cases where your application must express your window's bounds in pixel coordinates; primarily when you need to position your windows so they exactly align with each other or with some other fixed location, such as the edge of the display. For these cases, you should use the screen pixel coordinate space.

Availability
Declared In
MacWindows.h

HIWindowCreateCollapsedDockTileContext

Creates a Quartz graphics context for drawing a collapsed window’s Dock tile.

OSStatus HIWindowCreateCollapsedDockTileContext (
   WindowRef inWindow,
   CGContextRef *outContext,
   HISize *outContextSize
);

Parameters
inWindow

The collapsed window.

outContext

A pointer to a CGContextRef variable. On output, the variable contains the graphics context for drawing the window’s Dock tile.

outContextSize

A pointer to a HISize structure. On output, the structure contains the width and height of the area in which to draw.

Return Value

A result code. If the window is not collapsed, the result code is windowWrongStateErr. For other possible values, see “Window Manager Result Codes.”

Discussion

When you are finished drawing in the graphics context, you should:

  1. Call CGContextFlush to ensure that your drawing appears onscreen.

  2. Call HIWindowReleaseCollapsedDockTileContext to release the context. Do not call CFRelease or CGContextRelease to release the context, or you may leak system resources.

Availability
Declared In
MacWindows.h

HIWindowFindAtLocation

Finds a window in the current process at a specified location.

OSStatus HIWindowFindAtLocation (
   const HIPoint *inLocation,
   HICoordinateSpace inSpace,
   WindowRef inStartWindow,
   OptionBits inOptions,
   WindowRef *outWindow,
   WindowPartCode *outWindowPart,
   HIPoint *outWindowLocation
);

Parameters
inLocation

The location, in global coordinates, at which to search for a window.

inSpace

The coordinate space in which the location is expressed. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

inStartWindow

The window at which to start the search, inclusive. Pass kFirstWindowOfClass to start the search at the beginning of the window list. Passing NULL will cause the search to start at the end of the window list, and therefore no window will be found.

inOptions

Reserved. Pass zero.

outWindow

A pointer to a window variable. On output, the variable contains the window in the current process at the specified location, if any, or NULL if no window is found.

outWindowPart

A pointer to a window part code variable. On output, the variable contains the window part that was hit. You may pass NULL if you don't need this information.

outWindowLocation

A pointer to a point variable. On output, the variable contains the specified location transformed into window-relative coordinates, taking into account any window transform or magnification. You may pass NULL if you don't need this information.

Return Value

A result code. If no window is found that satisfies the search criteria, this function returns errWindowNotFound. For other possible return values, see “Window Manager Result Codes.”

Discussion

This function searches the window list of the current process for a window that contains the specified location. If you need to determine whether the window is of a particular class, you can use the function GetWindowClass and compare the result to the desired class.

Availability
Declared In
MacWindows.h

HIWindowFlush

Flushes any dirty areas a window might have.

OSStatus HIWindowFlush (
   WindowRef inWindow
);

Parameters
window

The window to flush.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function allows you to manually flush dirty areas of a window to the screen. This is the preferred way to flush window buffers in Mac OS X v10.3 and later. If called for a composited window, this function also renders any views in the window that are invalid.

Availability
Declared In
MacWindows.h

HIWindowFromCGWindowID

Returns the window in the current process with a specified Quartz window ID.

WindowRef HIWindowFromCGWindowID (
   CGWindowID inWindowID
);

Parameters
inWindowID

The window ID, as returned by HIWindowGetCGWindowID or CGWindowListCopyWindowInfo.

Return Value

The window to which the window ID is assigned. This function returns NULL if the window ID is invalid or if it refers to a window in another process.

Discussion

This function returns the window in the current process to which the specified window ID is assigned by the window server when the window is created.

Availability
See Also
Declared In
MacWindows.h

HIWindowGetAvailability

Obtains the availability of a window during Exposé or in Spaces.

OSStatus HIWindowGetAvailability (
   WindowRef inWindow,
   HIWindowAvailability *outAvailability
);

Parameters
inWindow

The window whose availability is to be obtained.

outAvailability

On exit, the current setting of the window’s availability bits. For details, see “Window Availability Constants.”

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HIWindowGetAvailablePositioningBounds

Gets the available window positioning bounds on a display.

OSStatus HIWindowGetAvailablePositioningBounds (
   CGDirectDisplayID inDisplay,
   HICoordinateSpace inSpace,
   HIRect *outAvailableRect
);

Parameters
inDisplay

The display for which to find the available bounds. May be kCGNullDirectDisplay to request the bounds of the main display.

inSpace

The coordinate space in which the positioning bounds should be returned. This must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

outAvailableRect

A pointer to a rectangle provided by the caller. On output, the rectangle contains the available bounds for the specified display. This rectangle is returned in the specified coordinate space.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function gets the bounds of the display not including the menu bar and Dock, if located on that display.

Availability
Declared In
MacWindows.h

HIWindowGetBounds

Gets the bounds of a specified region of a window.

OSStatus HIWindowGetBounds (
   WindowRef inWindow,
   WindowRegionCode inRegion,
   HICoordinateSpace inSpace,
   HIRect *outBounds
);

Parameters
inWindow

The window to access.

inRegion

The window region. For a list of possible values, see “Window Region Constants”.

inSpace

The coordinate space in which the bounds should be returned. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.

outBounds

A pointer to an HIRect structure. On output, the structure contains the origin and size of the bounding rectangle of the specified window region. If the window does not support the region, the structure is not modified.

Return Value

A result code. If the window does not support the specified window region, the result returned is errWindowRegionCodeInvalid.

Availability
See Also
Declared In
MacWindows.h

HIWindowGetCGWindowID

Returns the Quartz window ID assigned to a window.

CGWindowID HIWindowGetCGWindowID (
   WindowRef inWindow
);

Parameters
inWindow

The window to access.

Return Value

The window ID of the specified window, or zero if the window is invalid.

Discussion

This function returns the window ID assigned by the window server when a window is created. The window ID is not generally useful with any other Carbon function, but may be used with other Mac OS X functions that require a window ID, such as functions in OpenGL.

Availability
See Also
Declared In
MacWindows.h

HIWindowGetGreatestAreaDisplay

Finds the display with the greatest area of intersection with a window region.

OSStatus HIWindowGetGreatestAreaDisplay (
   WindowRef inWindow,
   WindowRegionCode inRegion,
   HICoordinateSpace inSpace,
   CGDirectDisplayID *outGreatestDisplay,
   HIRect *outGreatestDisplayRect
);

Parameters
inWindow

The window to compare against.

inRegion

The window region to compare against. See “Window Region Constants” for a list of possible values.

inSpace

The coordinate space in which the display bounds should be returned. This must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

outGreatestDisplay

A pointer to a display ID provided by the caller, or NULL if you don't need this information. On output, the display ID contains the display with the greatest intersection.

outGreatestDisplayRect

A pointer to a rectangle provided by the caller, or NULL if you don't need this information. On output, the rectangle contains the bounds of the display with the greatest intersection. If the display with the greatest intersection also contains the menu bar, the rectangle excludes the menu bar area. This rectangle is returned in the specified coordinate space.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

HIWindowGetIdealUserState

Gets the bounds of a window’s content region in its user state.

OSStatus HIWindowGetIdealUserState (
   WindowRef inWindow,
   HICoordinateSpace inSpace,
   HIRect *outUserState
);

Parameters
inWindow

The window to access.

inSpace

The coordinate space in which the user state bounds should be returned. This parameter must be kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

outUserState

A pointer to a structure of type HIRect. On return, this rectangle contains the global coordinates of the window’s content region when zoomed in. If the window has not yet been zoomed, this rectangle contains the window’s current content bounds.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function returns information about the window’s user state most recently recorded by the function ZoomWindowIdeal.

Availability
Declared In
MacWindows.h

HIWindowGetProxyFSRef

Obtains the FSRef used to determine the proxy icon for a window.

OSStatus HIWindowGetProxyFSRef (
   WindowRef window,
   FSRef *outRef
);

Parameters
inWindow

The window whose proxy FSRef is to be obtained.

outRef

On exit, the FSRef for the window’s proxy icon.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If the specified window’s proxy icon has been specified using HIWindowSetProxyFSRef or SetWindowProxyAlias, HIWindowGetProxyFSRef returns noErr and a valid FSRef for the window’s proxy icon. If the window has no proxy icon, or if the icon was specified by calling SetWindowProxyCreatorAndType or SetWindowProxyIcon, this function returns an error.

Availability
Declared In
MacWindows.h

HIWindowGetScaleMode

Obtains the window’s scale mode and the application’s display scale factor.

OSStatus HIWindowGetScaleMode (
   WindowRef inWindow,
   HIWindowScaleMode *outMode,
   CGFloat *outScaleFactor
);

Parameters
inWindow

The window whose scale mode is to be obtained.

outMode

On exit, an HIWindowScaleMode indicating the window’s scale mode. For details, see “Window Scale Mode Constants.”

outScaleFactor

On exit, a float indicating the display scale factor for the application. Pass NULL if you are not interested in acquiring the scale factor.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The window’s scale mode is based on the application’s display scale factor and any resolution-independent attributes specified at window creation time. Applications and the views within the window can use the scale mode and display scale factor to draw properly the content of a window for a particular scale mode.

Availability
Declared In
MacWindows.h

HIWindowGetThemeBackground

Gets the theme background brush for a window.

OSStatus HIWindowGetThemeBackground (
   WindowRef inWindow,
   ThemeBrush *outThemeBrush
);

Parameters
inWindow

The window from which to get the brush.

outThemeBrush

A pointer to a theme brush. On output, the brush is the window’s theme background brush.

Return Value

A result code. If no brush is found, themeNoAppropriateBrushErr is returned.

Discussion

This function gets the theme background brush previously set by calling the function SetThemeWindowBackground.

Availability
Declared In
MacWindows.h

HIWindowInvalidateShadow

Recalculates a window’s shadow.

OSStatus HIWindowInvalidateShadow (
   WindowRef inWindow
);

Parameters
inWindow

The window whose shadow is to be recalculated.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

HIWindowInvalidateShadow is not typically used by applications. It is useful if your application has customized window frames that change shape dynamically. After you have drawn the new window shape, you should call HIWindowInvalidateShadow to recalculate the shadow so that it follows the new window shape.

Availability
Declared In
MacWindows.h

HIWindowIsAttributeAvailable

Returns a Boolean value indicating whether a window attribute is valid for a specified window class.

Boolean HIWindowIsAttributeAvailable (
   WindowClass inClass,
   int inAttr
);

Parameters
inClass

The window class to test.

inAttr

The window attribute to test. You must specify one of the window attributes described in “Window Attribute Identifiers”.

Return Value

If true, the window class supports the specified attribute. Otherwise, false.

Availability
Declared In
MacWindows.h

HIWindowIsDocumentModalTarget

Determines if a window is currently the target window of another document modal window, such as a sheet.

Boolean HIWindowIsDocumentModalTarget (
   WindowRef inWindow,
   WindowRef *outOwner
);

Parameters
inWindow

The window to query.

outOwner

If this function returns true, inWindow is the target of a document modal window and outOwner is set to the document modal window. If this function does not return true, outOwner is undefined. Pass NULL if you don’t want the owner’s window reference.

Return Value

A Boolean whose value is true if the window specified by inWindow is currently the target of a document modal window; otherwise, false.

Availability
Declared In
MacWindows.h

HIWindowIsInStandardState

Returns a Boolean value indicating whether a window is zoomed out to its standard state.

Boolean HIWindowIsInStandardState (
   WindowRef inWindow,
   const HISize *inIdealSize,
   HICoordinateSpace inSpace,
   HIRect *outIdealStandardState
);

Parameters
inWindow

The window whose zoom state is to be determined.

inIdealSize

The ideal width and height of the window’s content region, regardless of the actual screen device dimensions. If you set inIdealSize to NULL, this function examines the dimensions stored in the stdState field of the WStateData structure.

inSpace

The coordinate space in which the ideal size is expressed and in which the standard state bounds should be returned. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

outIdealStandardState

A pointer to an HIRect variable. On return, the variable contains the bounds of the content region of the window in its standard state, based on the data supplied in the inIdealSize parameter. You may pass NULL if you do not need this information.

Return Value

If true, the window is currently in its standard state. If false, the window is currently in its user state.

Discussion

This function compares the window’s current dimensions to those in the inIdealSize parameter to determine if the window is currently in its standard state. You can use this function to decide whether a user’s click in the zoom box is a request to zoom to the user state or the standard state, as described in the function ZoomWindowIdeal. You can also use this function to determine the size and position of the standard state that the Window Manager would calculate for a window, given a specified ideal size; this value is returned in the outIdealStandardState parameter.

Availability
Declared In
MacWindows.h

HIWindowReleaseCollapsedDockTileContext

Releases a Quartz graphics context for drawing a collapsed window’s Dock tile.

OSStatus HIWindowReleaseCollapsedDockTileContext (
   WindowRef inWindow,
   CGContextRef inContext
);

Parameters
inWindow

The collapsed window.

inContext

The graphics context to release. On return, the context is invalid and should no longer be used.

Return Value

A result code. If the window is not collapsed, the result code is windowWrongStateErr. For other possible values, see “Window Manager Result Codes.”

Discussion

To ensure that your drawing appears onscreen, you should call CGContextFlush before calling this function to release the context. Do not call CFRelease or CGContextRelease to release the context, or you may leak system resources.

Availability
Declared In
MacWindows.h

HIWindowSetBounds

Sets the bounds of a window based on either the structure or content region.

OSStatus HIWindowSetBounds (
   WindowRef inWindow,
   WindowRegionCode inRegion,
   HICoordinateSpace inSpace,
   HIRect *inBounds
);

Parameters
inWindow

The window to access.

inRegion

The window region on which to base the window's new bounds. This parameter must be either kWindowStructureRgn or kWindowContentRgn.

inSpace

The coordinate space in which the bounds are expressed. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.

inBounds

A pointer to an HIRect structure that specifies the origin and size of the bounding rectangle of the specified window region. If the coordinate space is kHICoordSpaceWindow, then the origin of the bounds is a window-relative value. Therefore, you can use this coordinate space to resize a window without first getting its current bounds by setting the origin to (0,0), or you can offset a window from its current position by setting the origin to the offset amount and the size to the window's current size.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
See Also
Declared In
MacWindows.h

HIWindowSetIdealUserState

Sets the bounds of a window’s content region in its user state.

OSStatus HIWindowSetIdealUserState (
   WindowRef inWindow,
   HICoordinateSpace inSpace,
   const HIRect *inUserState
);

Parameters
inWindow

The window to access.

inSpace

The coordinate space in which the user state bounds are expressed. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.

inUserState

The new bounds (position and size) of the window’s content region in its user state.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

A window’s ideal user state is used by the function ZoomWindowIdeal when zooming in.

Availability
Declared In
MacWindows.h

HIWindowSetProxyFSRef

Sets the proxy icon for a window using an FSRef to a file system object.

OSStatus HIWindowSetProxyFSRef (
   WindowRef window,
   const FSRef *inRef
);

Parameters
inWindow

The window whose proxy icon is to be set.

inRef

The file system object the window represents.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

This function determines the window’s proxy icon by asking Icon Services for the icon for the object specified by inRef.

Availability
Declared In
MacWindows.h

HIWindowSetToolbarView

Sets a custom toolbar view for a window.

OSStatus HIWindowSetToolbarView (
   WindowRef inWindow,
   HIViewRef inView
);

Parameters
inWindow

The window whose toolbar view to set.

inView

The custom toolbar view for the window. You may pass NULL to remove the custom view from the window. Setting a custom view will also remove any HIToolbar that is associated with the window.

After a custom toolbar view has been set, the window owns the view and will release it automatically when the window is destroyed, or when a different custom view or standard HIToolbar is set for the window.

Return Value

A result code.

Discussion

This function is provided for use by applications that cannot use the HIToolbar API. For best compatibility with future versions of Mac OS X, you should use HIToolbar if possible. However, if HIToolbar is not sufficient for your needs, you can use this function to provide a custom toolbar view that will be placed at the standard location inside the window frame.

You are responsible for defining the appearance and behavior of the view. You cannot use this function to customize the view that is associated with an HIToolbar; a window with an HIToolbar uses a standard view that cannot be customized. When using a custom toolbar view, no function that takes an HIToolbar will work with that window. For more information about custom toolbar views, see MacWindows.h.

Availability
Declared In
MacWindows.h

HIWindowShowsFocus

Returns a Boolean value indicating whether a window's content should show focus indicators such as focus rings.

Boolean HIWindowShowsFocus (
   WindowRef inWindow
);

Parameters
inWindow

The window to access.

Return Value

If true, a window's content should show focus indicators; otherwise false.

Discussion

This function returns true if the window is either the modeless focus or the effective focus.

Availability
Declared In
MacWindows.h

HIWindowTestAttribute

Returns a Boolean value indicating whether a window has a specified attribute.

Boolean HIWindowTestAttribute (
   WindowRef inWindow,
   int inAttr
);

Parameters
inWindow

The window to test.

inAttr

The window attribute to test. You must specify one of the window attributes described in “Window Attribute Identifiers”.

Return Value

If true, the window has the specified attribute. Otherwise, false.

Availability
Declared In
MacWindows.h

HIWindowTrackProxyDrag

Tracks the drag of a window proxy icon.

OSStatus HIWindowTrackProxyDrag (
   WindowRef inWindow,
   EventRef inEvent,
   DragRef inDrag
);

Parameters
inWindow

The window whose proxy icon to drag.

inEvent

The event that resulted in starting a drag. This will most commonly be kEventControlTrack, but any event with kEventParamMouseLocation and kEventParamKeyModifiers parameters is all that is required.

inDrag

The proxy icon drag reference. You may pass NULL if you want the Window Manager to create and populate the drag reference. The Window Manager will add its own drag flavors to the drag even if you pass a pre-created drag reference.

Discussion

You can use this function to manage the dragging of the proxy icon in your application's windows. If you use the standard window event handler and you do not need to customize the proxy icon drag process, you may rely on the standard handler to call this function.

If you want to allow the Window Manager to create the drag reference and populate it with drag flavors, you should pass NULL in the inDrag parameter. If you want to create the drag reference yourself and add your own drag flavors, you should call BeginWindowProxyDrag to create the drag reference, add your own flavors, call HIWindowTrackProxyDrag to track the proxy icon drag, and then call EndWindowProxyDrag to release the drag reference.

A proxy icon may only be dragged if the window represented by the proxy icon is not modified, as indicated by the IsWindowModified function. This restriction exists because a proxy icon is a representation of a physical file system object, and dragging the proxy icon may result in the Finder making a copy of the file system object. If the window is modified, then it contains user data that has not yet been saved to disk; making a copy of the file system object would result in a stale copy that did not contain the user’s current data.

By default, all newly created windows are considered to be dirty. The application must pass false to SetWindowModified before the proxy icon will be draggable. In Mac OS X v10.3 and later, the proxy icon is also draggable in dirty windows if the proxy icon was provided using the SetWindowProxyIcon or SetWindowProxyCreatorAndType functions. Dragging is allowed in this case because the window does not represent an actual file system object, and therefore there is no risk of user data loss.

Availability
Declared In
MacWindows.h

InvalWindowRect

Adds a rectangle to a window’s update region.

OSStatus InvalWindowRect (
   WindowRef window,
   const Rect *bounds
);

Parameters
window

The window containing the rectangle you want to be updated.

bounds

Set this structure to specify, in local coordinates, a rectangle to be added to the window’s update region.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The InvalWindowRect function informs the Window Manager that an area of a window should be redrawn.

See also the functions ValidWindowRect and InvalWindowRgn.

Special Considerations

This function should not be used on composited windows. Modifying a composited window's update region does not affect the area of the window to be drawn. A composited window does not use its window update region to control drawing. Instead, a composited window determines what to draw by looking at the invalid regions of the views contained in the window.

Availability
Related Sample Code
Declared In
MacWindows.h

InvalWindowRgn

Adds a region to a window’s update region.

OSStatus InvalWindowRgn (
   WindowRef window,
   RgnHandle region
);

Parameters
window

The window containing the region that you want to update.

region

Set this region to specify, in local coordinates, the area to be added to the window’s update region.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The InvalWindowRgn function informs the Window Manager that an area of a window should be redrawn.

See also the functions InvalWindowRect and ValidWindowRgn.

Special Considerations

This function should not be used on composited windows. Modifying a composited window's update region does not affect the area of the window to be drawn. A composited window does not use its window update region to control drawing. Instead, a composited window determines what to draw by looking at the invalid regions of the views contained in the window.

Availability
Declared In
MacWindows.h

IsValidWindowClass

Determines whether a given window class is valid.

Boolean IsValidWindowClass (
   WindowClass inClass
);

Parameters
inClass

The window class to query.

Return Value

A Boolean whose value is true if the window class is valid; otherwise, false.

Availability
Declared In
MacWindows.h

IsValidWindowPtr

Reports whether a pointer is a valid window pointer.

Boolean IsValidWindowPtr (
   WindowRef possibleWindow
);

Parameters
possibleWindow

The window to query.

Return Value

A Boolean whose value is true if the specified pointer is a valid window pointer; otherwise, false.

Discussion

This function is primarily intended for use with debugging your application.

Special Considerations

The IsValidWindowPtr function is a processor-intensive call.

Availability
Declared In
MacWindows.h

IsWindowActive

Indicates whether the specified window is active. 

Boolean IsWindowActive (
   WindowRef inWindow
);

Parameters
inWindow

The window to query.

Return Value

Returns true if the window is active, false otherwise.

Discussion

Whether a window is considered active is determined by its activation scope, highlighting, and z-order. For windows that have an activation scope of kWindowActivationScopeAll, a window is active if it is the window returned by the ActiveNonFloatingWindow function or if it is in the same window group as the window returned by ActiveNonFloatingWindow and the window group has the kWindowGroupAttrSharedActivation attribute. For windows that have some other activation scope, the window is active if its window frame is highlighted and the window is the frontmost window in its window group.

Availability
Declared In
MacWindows.h

IsWindowCollapsable

Determines whether a window can be collapsed.

Boolean IsWindowCollapsable (
   WindowRef window
);

Parameters
window

The window to be examined.

Return Value

If true, the window can be collapsed; otherwise, false.

Discussion

You can call the IsWindowCollapsable function to determine if a given window can be collapsed by the CollapseWindow function. In Mac OS X, the presence or absence of the kWindowCollapseBoxAttribute is the primary way of determining whether a window can be collapsed. If that attribute is not present, the Window Manager checks for the kWindowCanCollapse feature bit.

Availability
Declared In
MacWindows.h

IsWindowCollapsed

Determines whether a window is currently collapsed.

Boolean IsWindowCollapsed (
   WindowRef window
);

Parameters
window

The window to be examined.

Return Value

If true, the window is collapsed. If false, the window is expanded.

Discussion

On Mac OS 9, only window definition functions that return the feature bit kWindowCanCollapse in response to a kWindowGetFeatures message support this function; for more information, see GetWindowFeatures. Typically, a window’s content region is empty in a collapsed state. In Mac OS X, the presence or absence of the kWindowCollapseBoxAttribute attribute determines whether a window can be collapsed.

Availability
Declared In
MacWindows.h

IsWindowContainedInGroup

Determines if a window is a member of a window group or any of its subgroups.

Boolean IsWindowContainedInGroup (
   WindowRef inWindow,
   WindowGroupRef inGroup
);

Parameters
inWindow

The window to query.

inGroup

The window group to query.

Return Value

A Boolean whose value is true if inWindow is a member of the window group specified by inGroup, or if inWindow is a member of a window group that is a member of the window group specified by inGroup. Otherwise, this function returns false.

Discussion

This function returns true if group A contains window A. It also returns true if group A contains group B and group B contains window A.

Availability
Declared In
MacWindows.h

IsWindowHilited

Indicates whether the window frame is currently highlighted.

Boolean IsWindowHilited (
   WindowRef window
);

Parameters
window

The window to query.

Return Value

A Boolean value indicating whether or not the window frame is highlighted. If true, the window is visible. If false, the window frame is not highlighted.

Availability
Declared In
MacWindows.h

IsWindowInStandardState

Determines whether a window is currently zoomed in to the user state or zoomed out to the standard state.

Boolean IsWindowInStandardState (
   WindowRef inWindow,
   const Point *inIdealSize,
   Rect *outIdealStandardState
);

Parameters
inWindow

The window whose zoom state is to be determined.

inIdealSize

Set the Point structure to contain the ideal width and height of the window’s content region, regardless of the actual screen device dimensions. If you set inIdealSize to NULL, IsWindowInStandardState examines the dimensions stored in the stdState field of the WStateData structure.

outIdealStandardState

On input, a pointer to a structure of type Rect. On return, the rectangle contains the global coordinates for the content region of the window in its standard state, based on the data supplied in the inIdealSize parameter. You may pass NULL if you do not want to receive this data.

Return Value

A Boolean whose value is true if the window is currently in its standard state; false if the window is currently in the user state.

Discussion

The IsWindowInStandardState function compares the window’s current dimensions to those referred to by the inIdealSize parameter to determine if the window is currently in the standard state. Your application may use IsWindowInStandardState to decide whether a user’s click of the zoom box is a request to zoom to the user state or the standard state, as described in the function ZoomWindowIdeal. Your application may also use IsWindowInStandardState to determine the size and position of the standard state that the Window Manager would calculate for a window, given a specified ideal size; this value is produced in the outIdealStandardState parameter.

Availability
See Also
Declared In
MacWindows.h

IsWindowLatentVisible

Indicates whether a window is visible onscreen or is latently visible but not currently onscreen.

Boolean IsWindowLatentVisible (
   WindowRef inWindow,
   WindowLatentVisibility *outLatentVisible
);

Parameters
inWindow

The window to query.

outLatentVisible

If the window is onscreen, the latent visibility is zero. If the window is offscreen, this parameter returns the latent visibility flags of the window. If any of the flags are set, the window is latently visible.

Return Value

A Boolean whose value is true if the window is currently onscreen; otherwise, false.

Discussion

All windows are either onscreen or offscreen. A window that is offscreen may still be latently visible. This occurs, for example, when a floating window is hidden as an application is suspended. The floating window is not visible onscreen, but it is latently visible and is only hidden due to the suspended state of the application. When the application becomes active again, the floating window will be placed back onscreen.

Availability
Declared In
MacWindows.h

IsWindowModified

Obtains the modification state of the specified window.

Boolean IsWindowModified (
   WindowRef window
);

Parameters
window

The window whose modification state is to be obtained.

Return Value

true if the content of the window has been modified; otherwise, false. Newly created windows start out with their modification state automatically set to true.

Discussion

Your application can use the functions IsWindowModified and SetWindowModified instead of maintaining its own separate record of the modification state of the content of a window.

Availability
Related Sample Code
Declared In
MacWindows.h

IsWindowPathSelectEvent

Determines whether a Carbon event describing a click on a window’s title should cause a path selection menu to be displayed.

Boolean IsWindowPathSelectEvent (
   WindowRef window,
   EventRef inEvent
);

Parameters
window

The window to query.

inEvent

The event. In CarbonLib and in Mac OS X v10.2 and earlier, the function only returns true for kEventClassMouse/kEventMouseDown events. In Mac OS X v10.3 and later, this function returns true for any event that has suitable kEventParamMouseLocation and kEventParamModifiers parameters.

Return Value

A Boolean whose value is true if the click should cause a path selection menu to be displayed; otherwise, false. If this function returns true, the application should call WindowPathSelect.

Discussion

Windows that have a proxy icon provided using an FSRef or alias can support a path selection menu, which displays the file system path to the object, one menu item per directory. Making a selection from this item automatically opens the corresponding object in the Finder.

Availability
Declared In
MacWindows.h

IsWindowToolbarVisible

Determines whether a window’s toolbar is visible. 

Boolean IsWindowToolbarVisible (
   WindowRef inWindow
);

Parameters
inWindow

The window to query.

Return Value

A Boolean whose value is true if the window’s toolbar is visible; otherwise, false.

Availability
Declared In
MacWindows.h

IsWindowUpdatePending

Determines whether a window update is pending.

Boolean IsWindowUpdatePending (
   WindowRef window
);

Parameters
window

The non-composited window to query.

Return Value

A Boolean whose value is true if an update is pending; otherwise, false.

Special Considerations

Modifying a composited window's update region does not affect the area of the window to be drawn. A composited window does not use its window update region to control drawing. Instead, a composited window determines what to draw by looking at the invalid regions of the views contained in the window.

Availability
Declared In
MacWindows.h

IsWindowVisible

Indicates whether the window frame is currently visible.

Boolean IsWindowVisible (
   WindowRef window
);

Parameters
window

The window to query.

Return Value

A Boolean value indicating whether or not the window is visible. If true, the window is visible. If false, the window is invisible.

Availability
Declared In
MacWindows.h

MoveWindow

Moves a window on the desktop.

void MoveWindow (
   WindowRef window,
   short hGlobal,
   short vGlobal,
   Boolean front
);

Parameters
window

The window that is to be moved on the desktop.

hGlobal

On input, the new location, in global coordinates, of the left edge of the window’s port rectangle.

vGlobal

On input, the new location, in global coordinates, of the top edge of the window’s port rectangle.

front

On input, a Boolean value specifying whether the window is to become the frontmost, active window. If the value of the front parameter is false, MoveWindow does not change its plane or status. If the value of the front parameter is true and the window isn’t active, MoveWindow makes it active by calling the SelectWindow function.

Discussion

The MoveWindow function moves the specified window to the location specified by the hGlobal and vGlobal parameters, without changing the window’s size. The upper-left corner of the window’s port rectangle is placed at the point (vGlobal, hGlobal). The local coordinates of the upper-left corner are unaffected.

Your application doesn’t normally call MoveWindow. When the user drags a window by dragging its title bar, you can call DragWindow which in turn calls MoveWindow when the user releases the mouse button.

Availability
Related Sample Code
Declared In
MacWindows.h

MoveWindowStructure

Positions a window relative to its structure region.

OSStatus MoveWindowStructure (
   WindowRef window,
   short hGlobal,
   short vGlobal
);

Parameters
window

The window that is to be moved.

hGlobal

A value specifying the horizontal position, in global coordinates, to which the left edge of the window’s structure region is to be moved.

vGlobal

A value specifying the vertical position, in global coordinates, to which the top edge of the window’s structure region is to be moved.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The MoveWindowStructure function moves the specified window, but does not change the window’s size. When your application calls MoveWindowStructure, the positioning of the specified window is determined by the positioning of its structure region. This is in contrast to the MoveWindow function, where the positioning of the window’s content region determines the positioning of the window. After moving the window, MoveWindowStructure displays the window in its new position.

Note that your application should not call the MoveWindowStructure function to position a window when the user drags the window by its drag region. When the user drags the window, your application should call the pre–Mac OS 8.5 Window Manager function DragWindow.

Availability
Related Sample Code
Declared In
MacWindows.h

OpenDrawer

Opens a drawer.

OSStatus OpenDrawer (
   WindowRef inDrawerWindow,
   OptionBits inEdge,
   Boolean inAsync
);

Parameters
inDrawerWindow

The drawer window to open.

inEdge

The parent window edge on which to open the drawer. Pass kWindowEdgeDefault to use the drawer’s preferred edge. If there is not enough room on the preferred edge, OpenDrawer tries the opposite edge. If there is insufficient room on both edges, the drawer will open on the preferred edge but may extend offscreen, under the Dock, or under the menu bar.

inAsync

Indicates whether to open the drawer synchronously (the drawer is entirely opened before the function call returns) or asynchronously (the drawer opens using an event loop timer after the function call returns). Specify true for asynchronous and false for synchronous.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

PinRect

Returns the point within the specified rectangle that is closest to the specified point.

long PinRect (
   const Rect *theRect,
   Point thePt
);

Parameters
theRect

On input, a pointer to a rectangle in which the point is to be contained.

thePt

On input, a pointer to the point to be contained.

Return Value

A long integer that specifies a point within the specified rectangle that is as close as possible to the specified point. (The high-order word of the returned long integer is the vertical coordinate; the low-order word is the horizontal coordinate.

Discussion

DragGrayRgn uses the PinRect function to contain a point within a specified rectangle. If the specified point is within the rectangle, PinRect returns the point itself. If not, then

The 1 is subtracted when the point is below or to the right of the rectangle so that a pixel drawn at that point lies within the rectangle.

Availability
Declared In
MacWindows.h

RegisterWindowDefinition

Registers a binding between a resource ID and a window definition function.

OSStatus RegisterWindowDefinition (
   SInt16 inResID,
   const WindowDefSpec *inDefSpec
);

Parameters
inResID

A WDEF proc ID, as used in a 'WIND' resource.

inDefSpec

Specifies the WindowDefUPP that should be used for windows with the given WDEF proc ID. Pass NULL to unregister a given WDEF proc ID.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

In the Mac OS 8.x Window Manager, a 'WIND' resource can contain an embedded WDEF procID that is used by the Window Manager as the resource ID of a 'WDEF' resource to lay out and draw the window. The 'WDEF' resource is loaded by the Window Manager when you load the window with GetNewWindow. Since WDEFs can no longer be packaged as code resources on Carbon, the procID can no longer refer directly to a WDEF resource. However, using RegisterWindowDefinition you can instead specify a UniversalProcPtr pointing to code in your application code fragment.

To unregister a window definition, pass NULL in the inDefSpec parameter for a given WDEF proc ID.

Availability
Declared In
MacWindows.h

ReleaseWindowGroup

Decrements the reference count for a window group.

OSStatus ReleaseWindowGroup (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group whose reference count is to be queried.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

RemoveWindowProperty

Removes a piece of data that is associated with a window.

OSStatus RemoveWindowProperty (
   WindowRef window,
   PropertyCreator propertyCreator,
   PropertyTag propertyTag
);

Parameters
window

The window whose data is to be removed.

propertyCreator

The creator code (typically, the application’s signature) of the associated data to be removed.

propertyTag

The application-defined code identifying the associated data to be removed.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The data removed by the RemoveWindowProperty function must have been previously associated with the window with the function SetWindowProperty.

Availability
Declared In
MacWindows.h

RemoveWindowProxy

Dissociates a file from a window.

OSStatus RemoveWindowProxy (
   WindowRef window
);

Parameters
window

The window for which you want to remove the associated file.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The RemoveWindowProxy function redraws the window title bar after removing all data associated with a given file, including the proxy icon, path menu, and file data.

Special Considerations

On Mac OS 8.x and Mac OS 9.x, you must save and restore the current graphics port—by calling the QuickDraw functions GetPort and SetPort—around each call to the RemoveWindowProxy function.

Availability
Related Sample Code
Declared In
MacWindows.h

RepositionWindow

Positions a window relative to another window or a display screen.

OSStatus RepositionWindow (
   WindowRef window,
   WindowRef parentWindow,
   WindowPositionMethod method
);

Parameters
window

The window whose position you want to set.

parentWindow

A pointer to the “parent” window, as defined by your application. In cases where the window positioning method does not require a parent window, you should set the parentWindow parameter to NULL.

method

A constant specifying the window positioning method to be used; see “Window Position Constants” for descriptions of possible values.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Your application may call the RepositionWindow function to position any window, relative to another window or to a display screen. After positioning the window, RepositionWindow displays the window in its new position.

Availability
Related Sample Code
Declared In
MacWindows.h

ReshapeCustomWindow

Notifies the Window Manager that a custom window’s shape has changed. 

OSStatus ReshapeCustomWindow (
   WindowRef window
);

Parameters
window

The window whose shape has changed.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If the shape of a custom window needs to change dynamically, outside of the context of normal Window Manager operations, you must use ReshapeCustomWindow to notify the Window Manager so that it can recalculate the window regions and update the screen. The Window Manager queries your custom window definition for the new structure and content regions and updates the screen with the new window shape.

Availability
Declared In
MacWindows.h

ResizeWindow

Handles all user interaction while a window is being resized.

Boolean ResizeWindow (
   WindowRef inWindow,
   Point inStartPoint,
   const Rect *inSizeConstraints,
   Rect *outNewContentRect
);

Parameters
window

The window that is to be resized.

inStartPoint

Set the Point structure to contain the location, specified in global coordinates, where the mouse-down event occurred. Your application may retrieve this value from the where field of the EventRecord structure.

inSizeConstraints

Set the rectangle to specify the limits on the vertical and horizontal measurements of the content rectangle, in pixels. Although this parameter gives the address of a structure that is in the form of the Rect data type, the four numbers in the structure represent limits, not screen coordinates. The top, left, bottom, and right fields of the structure specify the minimum vertical measurement (top), the minimum horizontal measurement (left), the maximum vertical measurement (bottom), and the maximum horizontal measurement (right). The minimum dimensions should be large enough to allow a manageable rectangle; 64 pixels on a side is typical. The maximum dimensions can be no greater than 32,767. You can pass NULL to allow the user to resize the window to any size that is contained onscreen.

outNewContentRect

On input, a pointer to a structure of type Rect. On return, the structure contains the new dimensions of the window’s content region, in global coordinates.

Return Value

true if the window was successfully resized; otherwise, false.

Discussion

The ResizeWindow function moves either an outline of the window’s edges (Mac OS 9.x and earlier) or the actual window (Mac OS X) around the screen, following the user’s cursor movements, and handles all user interaction until the mouse button is released. Unlike with the function GrowWindow, there is no need to follow this call with a call to the function SizeWindow, because once the mouse button is released, ResizeWindow resizes the window if the user has changed the window size. Once the resizing is complete, ResizeWindow draws the window in the new size.

Your application should call ResizeWindow instead of the earlier Window Manager functions SizeWindow and GrowWindow. The ResizeWindow function informs your application of the new window bounds, so that your application can respond to any changes in the window’s position.

Availability
Declared In
MacWindows.h

RetainWindowGroup

Increments the reference count for a window group. 

OSStatus RetainWindowGroup (
   WindowGroupRef inGroup
);

Parameters
inGroup

The window group whose reference count is to be incremented. For information on this data type, see WindowGroupRef.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

ScrollWindowRect

Scroll any area of a window. 

OSStatus ScrollWindowRect (
   WindowRef inWindow,
   const Rect *inScrollRect,
   SInt16 inHPixels,
   SInt16 inVPixels,
   ScrollWindowOptions inOptions,
   RgnHandle outExposedRgn
);

Parameters
inWindow

The window to scroll in.

inScrollRect

The rectangle to scroll, in local coordinates.

inHPixels

The number of pixels to scroll horizontally.

inVPixels

The number of pixels to scroll vertically.

inOptions

Options for the scroll. See “Window Scrolling Options” for a list of possible options.

outExposedRgn

A valid region handle for the area newly revealed by the scroll (can be NULL). If NULL, the exposed region is added to the window’s update region, regardless of the state of the kScrollWindowInvalidate option. This prevents updates from being lost in multiple monitor situations where the Window Manager can’t copy the entire region due to differing color tables.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Scrolls pixels that are inside the specified region of the input window. No other pixels or the bits they represent are affected. The pixels are shifted a distance of inHPixels horizontally and inVPixels vertically. The positive directions are to the right and down. The pixels that are shifted out of the specified window are not displayed, and the bits they represent are not saved. The exposed empty area created by the scrolling is returned in the update region parameter and optionally added to the window’s update region.

Availability
Declared In
MacWindows.h

ScrollWindowRegion

Scrolls a window’s region.

OSStatus ScrollWindowRegion (
   WindowRef inWindow,
   RgnHandle inScrollRgn,
   SInt16 inHPixels,
   SInt16 inVPixels,
   ScrollWindowOptions inOptions,
   RgnHandle outExposedRgn
);

Parameters
inWindow

The window to scroll in.

inScrollRgn

The region to scroll, in local coordinates.

inHPixels

The number of pixels to scroll horizontally.

inVPixels

The number of pixels to scroll vertically.

inOptions

Options for the scroll. See “Window Scrolling Options” for a list of possible options.

outExposedRgn

A valid region handle for the area newly revealed by the scroll (can be NULL). If NULL, the exposed region is added to the window’s update region, regardless of the state of the kScrollWindowInvalidate option. This prevents updates from being lost in multiple monitor situations where the Window Manager can’t copy the entire region due to differing color tables.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

Scrolls pixels that are inside the specified region of the input window. No other pixels or the bits they represent are affected. The pixels are shifted a distance of inHPixels horizontally and inVPixels vertically. The positive directions are to the right and down. The pixels that are shifted out of the specified window are not displayed, and the bits they represent are not saved. The exposed empty area created by the scrolling is returned in the update region parameter and optionally added to the window’s update region

Availability
Declared In
MacWindows.h

SelectWindow

Makes a window active.

void SelectWindow (
   WindowRef window
);

Parameters
window

The window that is to be made active.

Discussion

The SelectWindow function removes highlighting from the previously active window, brings the specified window to the front, highlights it, and generates the activate events to deactivate the previously active window and activate the specified window. If the specified window is already active, SelectWindow has no effect. Call SelectWindow when the user presses the mouse button while the cursor is in the content region of an inactive window.

Even if the specified window is invisible, SelectWindow brings the window to the front, activates the window, and deactivates the previously active window. Note that in this case, no active window is visible on the screen. If you do select an invisible window, be sure to call ShowWindow immediately to make the window visible (and accessible to the user).

Availability
Related Sample Code
Declared In
MacWindows.h

SendBehind

Moves one window behind another.

void SendBehind (
   WindowRef window,
   WindowRef behindWindow
);

Parameters
window

The window to be moved.

behindWindow

On input, a pointer to the window that is to be in front of the moved window.

Discussion

The SendBehind function moves the window pointed to by the parameter window behind the window pointed to by the parameter behindWindow. If the move exposes previously obscured windows or parts of windows, SendBehind redraws the frames as necessary and generates the appropriate update events to have any newly exposed content areas redrawn.

If the value of behindWindow is NULL, SendBehind sends the window to be moved behind all other windows on the desktop. If the window to be moved is the active window, SendBehind removes its highlighting, highlights the newly exposed frontmost window, and generates the appropriate activate events.

Do not use SendBehind to deactivate a window after you’ve made a new window active with the function SelectWindow. The SelectWindow function automatically deactivates the previously active window.

Availability
Declared In
MacWindows.h

SendWindowGroupBehind

Orders one window group behind another.

OSStatus SendWindowGroupBehind (
   WindowGroupRef inGroup,
   WindowGroupRef behindGroup
);

Parameters
inGroup

The window group.

behindGroup

The “behind” window group.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

A window group can contain multiple window groups. You can use this function to order nested groups.

Availability
Declared In
MacWindows.h

SetDrawerOffsets

Sets the positioning offsets for the drawer with respect to its parent window. 

OSStatus SetDrawerOffsets (
   WindowRef inDrawerWindow,
   CGFloat inLeadingOffset,
   CGFloat inTrailingOffset
);

Parameters
inDrawerWindow

The drawer window whose positioning offsets are to be set.

inLeadingOffset

The new leading offset, in pixels. Pass kWindowOffsetUnchanged if you don’t want to change the leading offset.

inTrailingOffset

The new trailing offset, in pixels. Pass kWindowOffsetUnchanged if you don’t want to change the trailing offset.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetDrawerParent

Sets the parent window for a drawer. 

OSStatus SetDrawerParent (
   WindowRef inDrawerWindow,
   WindowRef inParent
);

Parameters
inDrawerWindow

The drawer window whose parent window is to be set.

inParent

The window that is to be set as the parent of the window specified by inDrawerWindow.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetDrawerPreferredEdge

Set the preferred window edge from which the drawer should appear. 

OSStatus SetDrawerPreferredEdge (
   WindowRef inDrawerWindow,
   OptionBits inEdge
);

Parameters
inDrawerWindow

The drawer window whose preferred window edge is to be set.

inEdge

The preferred edge. See “Window Edge Constants” for a list of possible values.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetPortWindowPort

Sets the current graphics port to the window’s port.

void SetPortWindowPort (
   WindowRef window
);

Parameters
window

The window whose graphics port is to be set.

Availability
Related Sample Code
Declared In
MacWindows.h

SetThemeTextColorForWindow

Sets a text color that contrasts with a theme brush.

OSStatus SetThemeTextColorForWindow (
   WindowRef inWindow,
   Boolean inActive,
   SInt16 inDepth,
   Boolean inColorDev
);

Parameters
inWindow

The window whose text color is to be set.

inActive

A Boolean whose value is true to indicate an active state or false to indicate an inactive state.

inDepth

The bit depth of the window’s port. In Mac OS X, this parameter is ignored and should always be set to 32.

inColorDev

A Boolean whose value is true to indicate that the window’s port is color or false to indicate that the port is black and white. In Mac OS X, this parameter is ignored and should always be set to true.

Return Value

A result code. See “Window Manager Result Codes” for a list of possible values.

Discussion

SetThemeTextColorForWindow sets a text color in the specified window’s port that contrasts with the brush specified by SetThemeWindowBackground and also matches the inActive parameter.

Only a subset of the theme brushes have theme text colors. As of Mac OS 9 and Mac OS X v10.4 and later, the Alert, Dialog, Modeless Dialog, and Notification brushes have corresponding text colors. For any other brush, SetThemeTextColorForWindow returns themeNoAppropriateBrushErr and does not modify the text color.

Availability
Declared In
MacWindows.h

SetThemeWindowBackground

Sets a window’s background theme.

OSStatus SetThemeWindowBackground (
   WindowRef inWindow,
   ThemeBrush inBrush,
   Boolean inUpdate
);

Parameters
inWindow

The window whose background theme is to be set.

inBrush

The theme brush that determines how the window background is painted. For information on theme brushes, see the Appearance Manager documentation.

inUpdate

A Boolean whose value is true if you want the window to be redrawn immediately using the new background brush; otherwise, false.

Return Value

A result code. See “Window Manager Result Codes” for a list of possible values.

Availability
Declared In
MacWindows.h

SetUserFocusWindow

Designates a window to receive user focus.

OSStatus SetUserFocusWindow (
   WindowRef inWindow
);

Return Value

A result code.

Discussion

You can use this function to assign user focus to a specified window. This tells the Carbon Event Manager to route events that should go to the user focus (for example, commands and keyboard events) to the specified window. This can be used, for example, to route keyboard events to a floating palette, since floating palettes do not normally receive user focus.

Setting focus automatically defocuses whatever element formerly had user focus. If the focus changes to a new window, the kEventWindowFocusAcquired Carbon event will be sent to the newly focused window, and the kEventWindowFocusRelinquish Carbon event will be sent to the previously focused window.

If you pass kUserFocusAuto in the inWindow parameter, the system picks the best candidate for user focus (typically, this will be the active window). If you temporarily change the focus to a special window, you should use this option to restore the focus rather than setting the focus to an explicit window.

Availability
Declared In
MacWindows.h

SetWindowActivationScope

Sets a window’s activation scope.

OSStatus SetWindowActivationScope (
   WindowRef inWindow,
   WindowActivationScope inScope
);

Parameters
inWindow

The window whose activation scope is to be set.

inScope

The new activation scope.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetWindowAlpha

Sets the window’s alpha channel value. 

OSStatus SetWindowAlpha (
   WindowRef inWindow,
   CGFloat inAlpha
);

Parameters
inWindow

The window whose alpha channel value is to be set.

inAlpha

The alpha value to set. This value can range from 0.0 (completely transparent) to 1.0 (opaque).

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetWindowAlternateTitle

Sets an alternate window title. 

OSStatus SetWindowAlternateTitle (
   WindowRef inWindow,
   CFStringRef inTitle
);

Parameters
inWindow

The window for which to set the alternate title.

inTitle

The alternate title for the window. Passing NULL for this parameter will remove any alternate title that might be present.

Return Value

A result code. See “Window Manager Result Codes.” An operating system status code.

Discussion

This API sets an alternate title for a window. The alternate title overrides what is displayed in the Window menu. If you do not set an alternate title, the normal window title is used. You would normally use this if the window title was not expressive enough to be used in the Window menu (or similar text-only situation).

Availability
Declared In
MacWindows.h

SetWindowBounds

Sets a window’s size and position from the bounding rectangle of the specified window region.

OSStatus SetWindowBounds (
   WindowRef window,
   WindowRegionCode regionCode,
   const Rect *globalBounds
);

Parameters
window

The window whose bounds are to be set.

regionCode

A constant specifying the region to be used in determining the window’s size and position. The only region codes allowed for this parameter are kWindowStructureRgn and kWindowContentRgn.

globalBounds

Set the rectangle to specify the dimensions and position, in global coordinates, of the window region specified in the regionCode parameter.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The SetWindowBounds function sets a window’s size and position to that specified by the rectangle that your application passes in the globalBounds parameter. After doing so, SetWindowBounds redraws the window, if the window is visible.

When you call the SetWindowBounds function, your application specifies whether the window’s content region or its structure region is more important in determining the window’s ultimate size and position. This distinction can be important with versions of the Mac OS running the Appearance Manager, since the total dimensions of a window—and, therefore, its spatial relationship to the rest of the screen—may vary from appearance to appearance. In general, you should specify kWindowStructureRgn for the regionCode parameter if how the window as a whole relates to a given monitor is more important than the exact positioning of its content on the screen. On the other hand, if you specify kWindowContentRgn for the regionCode parameter because the positioning of your application’s content is of greatest concern, then it is important to note that with some appearances some part of the window’s structure region or “frame” may extend past the edge of a monitor and not be displayed.

See also the function GetWindowBounds.

Availability
See Also
Declared In
MacWindows.h

SetWindowCancelButton

Specifies a Cancel button for a window.

OSStatus SetWindowCancelButton (
   WindowRef inWindow,
   ControlRef inControl
);

Parameters
inWindow

The window whose Cancel button you want to set.

inControl

The control to designate as the Cancel button.

Return Value

A result code.

Discussion

You can use this function to specify a control (normally a button) to be the Cancel button for a given window. This button would be considered to have been clicked if the user instead presses Command-period or the Escape key.

The standard window event handler looks for keystrokes that correspond to the cancel button and generates events of type kEventControlHit when it detects the correct key being pressed. This is similar to the way the Dialog Manager responds to cancel buttons, except that instead of returning an item index for which button is pressed, the Carbon Event Manager generates a control hit event.

Availability
Declared In
MacWindows.h

SetWindowContentColor

Sets the color to which a window’s content region is redrawn.

OSStatus SetWindowContentColor (
   WindowRef window,
   const RGBColor *color
);

Parameters
window

The window whose content color is to be set.

color

Set this structure to specify the content color to be used.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If your application uses the SetWindowContentColor function, the window’s content region is redrawn to the color you specify, without affecting the value specified in the window’s CGrafPort structure for the current background color.

See also the function GetWindowContentColor.

Availability
Declared In
MacWindows.h

SetWindowContentPattern

Sets the pattern to which a window’s content region is redrawn.

OSStatus SetWindowContentPattern (
   WindowRef window,
   PixPatHandle pixPat
);

Parameters
window

A pointer to the window whose content pattern is being set.

pixPat

Set this structure to specify the content pattern to be used. This handle is copied by the Window Manager, and your application continues to own the original. Therefore there may be higher RAM requirements for applications with numerous identically patterned windows.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

If your application uses the SetWindowContentPattern function, the window’s content region is redrawn to the pattern you specify, without affecting the value specified in the window’s CGrafPort structure for the current background pattern.

See also the function GetWindowContentPattern.

Availability
Declared In
MacWindows.h

SetWindowDefaultButton

Specifies a default button for a window.

OSStatus SetWindowDefaultButton (
   WindowRef inWindow,
   ControlRef inControl
);

Parameters
inWindow

The window whose default button you want to set.

inControl

The control to designate as the default.

Return Value

A result code.

Discussion

You can use this function to specify a control (normally a button) to be the default for a given window. This button would be considered to have been clicked if the user instead presses the Return or Enter keys on the keyboard.

The standard window event handler looks for keystrokes that correspond to the default button and generates events of type kEventControlHit when it detects the correct key being pressed. This is similar to the way the Dialog Manager responds to default buttons, except that instead of returning an item index for which button is pressed, the Carbon Event Manager generates a control hit event.

Availability
Related Sample Code
Declared In
MacWindows.h

SetWindowDockTileMenu

Associates a pop-up menu with a window. 

OSStatus SetWindowDockTileMenu (
   WindowRef inWindow,
   MenuRef inMenu
);

Parameters
inWindow

The window with which a pop-up menu is to be associated.

inMenu

The pop-up menu that is to be associated with the window specified by inWindow

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

You specify a dock tile menu if you want to be able to present special selections when the user activates the pop-up menu associated with the window’s minimized dock tile.

Availability
Related Sample Code
Declared In
MacWindows.h

SetWindowGroup

Assigns a window to a window group. 

OSStatus SetWindowGroup (
   WindowRef inWindow,
   WindowGroupRef inNewGroup
);

Parameters
inWindow

The window that is to be assigned to a window group.

inNewGroup

The window group. For information on this data type, see WindowGroupRef.

Return Value

A result code. See “Window Manager Result Codes.”

Availability
Declared In
MacWindows.h

SetWindowGroupLevel

Sets the level of group in the window class hierarchy. 

OSStatus SetWindowGroupLevel (
   WindowGroupRef inGroup,
   SInt32 inLevel
);

Parameters
inGroup

The window group.

inLevel

The new level for the windows in this group.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

The window group’s level is only used to set the level of its windows if the window group is a child of the root group. If there is another group in the group hierarchy between this group and the root group, this group’s level is ignored.

In Mac OS X v10.4 and later, SetWindowGroupLevel sets all three window levels associated with a window group: active, inactive, and promoted. It then immediately determines if the active level needs to be promoted to a larger value, and if so, sets the promoted level to that value.

See the Core Graphics frameworks header CGWindowLevel.h for a listing of window levels.

Availability
Declared In
MacWindows.h

SetWindowGroupLevelOfType

Sets the window level of a window group.

OSStatus SetWindowGroupLevelOfType (
   WindowGroupRef inGroup,
   UInt32 inLevelType,
   CGWindowLevel inLevel
);

Parameters
inGroup

The window group whose Core Graphics window level is to be set.

inLevelType

The level type to set. Specify kWindowGroupLevelActive or kWindowGroupLevelInactive. For details, see “Window Group Level Constants.”

inLevel

The new level that is to be set for the windows in this group.

Return Value

A result code. See “Window Manager Result Codes.”

Discussion

In Mac OS X v10.4 and later, multiple window levels may be associated with a window group: one level for when the application is active and another for when the application is inactive. The Window Manager automatically switches each group’s level as the application becomes active or inactive. Call SetWindowGroupLevelOfType to set the active and inactive window level for a window group. The window group’s level is only used to set the level of its windows if the window group is a child of the root group. If there is another group in the group hierarchy between this group and the root group, this group’s level is ignored.

You can also use SetWindowGroupLevelOfType to set the promoted window level that is actually used for windows in the group. Doing so is not recommended, however, because the promoted window level is reset by the Window Manager whenever the window group hierarchy structure changes. Any changes that you make to the promoted level may, therefore, be overwritten. In general, you should only use SetWindowGroupLevelOfType to set the active and inactive window levels. When setting the active level of a group with the fixed-level window group attribute, this function also automatically sets the promoted level to the same value and updates the promoted level of any non-fixed-level groups above the group being modified.

Availability
Declared In
MacWindows.h

SetWindowGroupName

Assigns a name to a window group. 

OSStatus SetWindowGroupName (
   WindowGroupRef inGroup,
   CFStringRef inName
);

Parameters
inGroup

The window group. For information on this data type, s