| Framework | Carbon/Carbon.h |
| Declared in | HIToolboxDebugging.h HIWindowViews.h IOMacOSTypes.h MacWindows.h QuickdrawTypes.h |
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:
Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call Window Manager functions such as CreateNewWindow and DisposeWindow.
You must revise your application so that it accesses Window Manager data structures only through accessor functions.
You are encouraged to adopt the standard Mac OS window definition procedures in your application. Applications that use the standard Mac OS window definition procedures inherit the Mac OS human interface appearance on Mac OS 9 and Mac OS X. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, the Mac OS can’t draw these applications with the current appearance (unless you specifically use Appearance Manager drawing primitives).
IsValidWindowPtr
GetWindowGreatestAreaDevice
HIWindowGetGreatestAreaDisplay
HIWindowCopyShape
HIWindowGetScaleMode
GetWindowList
GetWindowWidgetHilite
IsWindowModified
SetWindowModified
HIWindowGetCGWindowID
HIWindowFromCGWindowID
GetWindowRegion Deprecated in Mac OS X v10.5
IsWindowPathSelectEvent
WindowPathSelect
IsWindowPathSelectClick Deprecated in Mac OS X v10.5
GetWindowProperty
SetWindowProperty
GetWindowPropertySize
RemoveWindowProperty
ChangeWindowPropertyAttributes
GetWindowPropertyAttributes
CreateNewWindow
CreateCustomWindow
HIWindowCreate
DisposeWindow
CreateWindowFromCollection Deprecated in Mac OS X v10.5
CreateWindowFromResource Deprecated in Mac OS X v10.5
StoreWindowIntoCollection Deprecated in Mac OS X v10.5
ActivateWindow
IsWindowActive
HiliteWindow
SelectWindow
ShowWindow
HideWindow
ShowHide
BringToFront
SendBehind
HIWindowInvalidateShadow
BeginWindowProxyDrag
EndWindowProxyDrag
HiliteWindowFrameForDrag
TrackWindowProxyDrag
TrackWindowProxyFromExistingDrag
HIWindowTrackProxyDrag
GetWindowProxyAlias
SetWindowProxyAlias
GetWindowProxyIcon
SetWindowProxyIcon
RemoveWindowProxy
SetWindowProxyCreatorAndType
HIWindowGetProxyFSRef
HIWindowSetProxyFSRef
GetNextWindow
GetWindowKind
SetWindowKind
GetWindowPort
SetPortWindowPort
GetWindowPortBounds
GetWindowStandardState
SetWindowStandardState
GetWindowUserState
SetWindowUserState
IsWindowHilited
IsWindowLatentVisible
IsWindowVisible
GetWindowStructurePort
GetWindowStructureWidths
ActiveNonFloatingWindow
FrontNonFloatingWindow
FindWindow
FindWindowOfClass
HIWindowFindAtLocation
GetFrontWindowOfClass
GetNextWindowOfClass
GetPreviousWindow
FrontWindow Deprecated in Mac OS X v10.5
BeginUpdate
EndUpdate
InvalWindowRect
InvalWindowRgn
IsWindowUpdatePending
ValidWindowRect
ValidWindowRgn
HIWindowCreateCollapsedDockTileContext
HIWindowReleaseCollapsedDockTileContext
GetWindowDockTileMenu
SetWindowDockTileMenu
UpdateCollapsedWindowDockTile
CreateQDContextForCollapsedWindowDockTile Deprecated in Mac OS X v10.5
ReleaseQDContextForCollapsedWindowDockTile Deprecated in Mac OS X v10.5
GetWindowToolbar
SetWindowToolbar
ShowHideWindowToolbar
IsWindowToolbarVisible
HIWindowSetToolbarView
DisposeWindowDefUPP Deprecated in Mac OS X v10.5
DisposeWindowPaintUPP Deprecated in Mac OS X v10.5
InvokeWindowDefUPP Deprecated in Mac OS X v10.5
InvokeWindowPaintUPP Deprecated in Mac OS X v10.5
NewWindowDefUPP Deprecated in Mac OS X v10.5
NewWindowPaintUPP Deprecated in Mac OS X v10.5
GetWindowAttributes
GetAvailableWindowAttributes
ChangeWindowAttributes
HIWindowTestAttribute
HIWindowChangeAttributes
HIWindowIsAttributeAvailable
GetWindowClass
HIWindowChangeClass
IsValidWindowClass
SetWindowClass Deprecated in Mac OS X v10.5
ChangeWindowGroupAttributes
CopyWindowGroupName
CountWindowGroupContents
CreateWindowGroup
DebugPrintAllWindowGroups
DebugPrintWindowGroup
GetIndexedWindow
GetWindowGroup
GetWindowGroupAttributes
GetWindowGroupContents
GetWindowGroupLevel
GetWindowGroupLevelOfType
GetWindowGroupOfClass
GetWindowGroupOwner
GetWindowGroupParent
GetWindowGroupRetainCount
GetWindowGroupSibling
GetWindowIndex
IsWindowContainedInGroup
ReleaseWindowGroup
RetainWindowGroup
SendWindowGroupBehind
SetWindowGroup
SetWindowGroupLevel
SetWindowGroupLevelOfType
SetWindowGroupName
SetWindowGroupOwner
SetWindowGroupParent
CopyWindowAlternateTitle
SetWindowAlternateTitle
CopyWindowTitleAsCFString
SetWindowTitleWithCFString
HIWindowCopyDrawers
OpenDrawer
CloseDrawer
GetDrawerCurrentEdge
GetDrawerPreferredEdge
SetDrawerPreferredEdge
GetDrawerOffsets
SetDrawerOffsets
GetDrawerParent
SetDrawerParent
GetDrawerState
ToggleDrawer
GetWindowContentColor
GetWindowContentPattern
SetWindowContentColor
GetWRefCon
SetWindowContentPattern
SetWRefCon
GetWindowPic Deprecated in Mac OS X v10.5
SetWindowPic Deprecated in Mac OS X v10.5
CloneWindow Deprecated in Mac OS X v10.5
GetWindowOwnerCount Deprecated in Mac OS X v10.5
GetWindowRetainCount Deprecated in Mac OS X v10.5
ReleaseWindow Deprecated in Mac OS X v10.5
RetainWindow Deprecated in Mac OS X v10.5
GetWindowBounds
HIWindowGetBounds
SetWindowBounds
HIWindowSetBounds
MoveWindowStructure
RepositionWindow
ResizeWindow
GetAvailableWindowPositioningBounds
HIWindowGetAvailablePositioningBounds
GetAvailableWindowPositioningRegion
HIWindowCopyAvailablePositioningShape
ConstrainWindowToScreen
HIWindowConstrain
GetWindowResizeLimits
SetWindowResizeLimits
You can use these functions to add dialog-like button controls to normal windows.
GetWindowIdealUserState
HIWindowGetIdealUserState
IsWindowInStandardState
HIWindowIsInStandardState
SetWindowIdealUserState
HIWindowSetIdealUserState
ZoomWindowIdeal
CreateStandardWindowMenu
GetWindowFromPort
HIWindowFlush
RegisterWindowDefinition
ReshapeCustomWindow
InstallWindowContentPaintProc Deprecated in Mac OS X v10.5
CalcVis Deprecated in Mac OS X v10.5
CalcVisBehind Deprecated in Mac OS X v10.5
CheckUpdate Deprecated in Mac OS X v10.5
ClipAbove Deprecated in Mac OS X v10.5
DragGrayRgn Deprecated in Mac OS X v10.5
DragTheRgn Deprecated in Mac OS X v10.5
DrawGrowIcon Deprecated in Mac OS X v10.5
GetGrayRgn Deprecated in Mac OS X v10.5
GetNewCWindow Deprecated in Mac OS X v10.5
GetNewWindow Deprecated in Mac OS X v10.5
GetWindowProxyFSSpec Deprecated in Mac OS X v10.5
GetWTitle Deprecated in Mac OS X v10.5
GetWVariant Deprecated in Mac OS X v10.5
GrowWindow Deprecated in Mac OS X v10.5
NewCWindow Deprecated in Mac OS X v10.5
NewWindow Deprecated in Mac OS X v10.5
PaintBehind Deprecated in Mac OS X v10.5
PaintOne Deprecated in Mac OS X v10.5
SetWindowProxyFSSpec Deprecated in Mac OS X v10.5
SetWTitle Deprecated in Mac OS X v10.5
Activates or deactivates a window.
OSStatus ActivateWindow ( WindowRef inWindow, Boolean inActivate );
The window to activate or deactivate.
Pass true to activate the window, false otherwise.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns the currently active nonfloating window.
WindowRef ActiveNonFloatingWindow ( void );
A reference to the active window.
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.
MacWindows.h
Indicates whether an application’s floating windows are currently visible.
Boolean AreFloatingWindowsVisible ( void );
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.
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.
The AreFloatingWindowsVisible function operates only upon windows created with the kFloatingWindowClass constant; see “Window Class Constants” for more details on this constant.
MacWindows.h
Starts updating a window when you receive an update event for that window.
void BeginUpdate ( WindowRef 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.
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.
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.
MacWindows.h
Creates the drag reference and the drag image when the user drags a proxy icon.
OSStatus BeginWindowProxyDrag ( WindowRef window, DragRef *outNewDrag, RgnHandle outDragOutlineRgn );
The window whose proxy icon is being dragged.
On input, a pointer to a value of type DragRef. On return, the value refers to the current drag process.
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.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Brings a window to the front.
void BringToFront ( WindowRef window );
The window that is to be brought to the front.
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.
MacWindows.h
Changes a window’s attributes.
OSStatus ChangeWindowAttributes ( WindowRef window, WindowAttributes setTheseAttributes, WindowAttributes clearTheseAttributes );
The window whose attributes you want to change.
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.
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.
A result code. See “Window Manager Result Codes.”
If the changed attributes affect the visible window’s frame, the window regions are recalculated and the window is redrawn.
MacWindows.h
Changes the attributes of a window group.
OSStatus ChangeWindowGroupAttributes ( WindowGroupRef inGroup, WindowGroupAttributes setTheseAttributes, WindowGroupAttributes clearTheseAttributes );
The window group whose attributes you want to set.
The attributes you want to set. See “Window Group Attributes” for a list of possible attributes.
The attributes you want to clear (if any). See “Window Group Attributes” for a list of possible attributes.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Changes attributes associated with a window property.
OSStatus ChangeWindowPropertyAttributes ( WindowRef window, OSType propertyCreator, OSType propertyTag, OptionBits attributesToSet, OptionBits attributesToClear );
The window whose property attributes are to be changed.
The property creator.
The property tag.
The attributes to set. For a possible value, see “Window Property Persistent Constant.”
The attributes to clear. For a possible value, see “Window Property Persistent Constant.”
A result code. See “Window Manager Result Codes.”
MacWindows.h
Closes a drawer.
OSStatus CloseDrawer ( WindowRef inDrawerWindow, Boolean inAsync );
The drawer window that is to be closed.
Pass true for asynchronous closing; otherwise, pass false.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Collapses or expands all collapsable windows in an application.
OSStatus CollapseAllWindows ( Boolean collapse );
Set to true to collapse all windows in the application. Set to false to expand all windows in the application.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Collapses or expands a window to the dock.
OSStatus CollapseWindow ( WindowRef window, Boolean collapse );
The window that is to be collapsed or expanded.
Indicates whether the window should be collapsed or expanded.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hMoves 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 );
The window to constrain.
The window region to constrain. See “Window Region Constants” for a list of possible constants to pass.
Flags controlling how the window is constrained.
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.
On exit, contains the new structure bounds of the window, in global coordinates. May be NULL.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains a copy of the alternate window title.
OSStatus CopyWindowAlternateTitle ( WindowRef inWindow, CFStringRef *outTitle );
The window to get the alternate title from.
Receives the alternate title for the window. If the window does not have an alternate title, NULL will be returned in outTitle.
A result code. See “Window Manager Result Codes.” An operating system status code.
See the discussion of SetWindowAlternateTitle for more information about alternate window titles.
MacWindows.h
Obtains a copy of the window group name.
OSStatus CopyWindowGroupName ( WindowGroupRef inGroup, CFStringRef *outName );
The window group to query. For information on this data type,
A result code. See “Window Manager Result Codes.”
MacWindows.h
Copies the window title into a Core Foundation string.
OSStatus CopyWindowTitleAsCFString ( WindowRef inWindow, CFStringRef *outString );
The window whose title is to be copied.
On output, the window’s title.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Counts the number of members of a window group.
ItemCount CountWindowGroupContents ( WindowGroupRef inGroup, WindowGroupContentOptions inOptions );
The window group whose members are to be counted.
Counting options. See “Window Group Content Options” for possible constants to pass.
MacWindows.h
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 );
For information on this data type, see WindowDefSpec.
The class the custom window should belong to. This value determines the layer ordering of the custom window.
Attributes for the window. See “Window Attributes” for a list of possible attributes.
Pointer to a Rect structure in global coordinates indicating the dimensions of the window’s content region.
On return, the newly-created window.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Creates a window from parameter data.
OSStatus CreateNewWindow ( WindowClass windowClass, WindowAttributes attributes, const Rect *contentBounds, WindowRef *outWindow );
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 for the window. See “Window Attributes” for a list of possible attributes.
Pointer to a Rect structure in global coordinates indicating the dimensions of the window’s content region.
On input, a pointer to a value of type WindowRef. On return, the window pointer points to the newly created window.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Creates a standard window menu for your application.
OSStatus CreateStandardWindowMenu ( OptionBits inOptions, MenuRef *outMenu );
Option bits. Pass 0 or kWindowMenuIncludeRotate. For information on the kWindowMenuIncludeRotate constant, see “Window Menu Item Property Constants.”
On output, a new menu reference that contains the standard window menu items and commands.
A result code. See “Window Manager Result Codes.” An operating system status code.
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.
MacWindows.h
Creates a window group.
OSStatus CreateWindowGroup ( WindowGroupAttributes inAttributes, WindowGroupRef *outGroup );
Attributes for the new window group. See “Window Group Attributes” for a listing of possible attributes.
For information on this data type, see WindowGroupRef.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Debugging utility function listing all window groups.
void DebugPrintAllWindowGroups ( void );
HIToolboxDebugging.h
Debugging utility functions for use with window groups.
void DebugPrintWindowGroup ( WindowGroupRef inGroup );
The window group. For information on this data type,
HIToolboxDebugging.h
Detaches a sheet window from its parent window.
OSStatus DetachSheetWindow ( WindowRef inSheet );
The window sheet that is to be detached from its parent window.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Disables updates for changes to the current application’s windows.
OSStatus DisableScreenUpdates ( void );
A result code. See “Window Manager Result Codes.”
MacWindows.h
Removes a window.
void DisposeWindow ( WindowRef window );
On input, the window to be closed.
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.
MacWindows.h
Moves a window on the screen when the user drags it by its drag region.
void DragWindow ( WindowRef window, Point startPt, const Rect *boundsRect );
The window that is to be dragged.
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.
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.
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.
MacWindows.h
Enables screen updates for changes to the current application’s windows.
OSStatus EnableScreenUpdates ( void );
A result code. See “Window Manager Result Codes.”
MacWindows.h
Finishes updating a window.
void EndUpdate ( WindowRef window );
The window for which updating is to be finished.
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.
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.
MacWindows.h
Disposes of the drag reference when the user completes the drag of a proxy icon.
OSStatus EndWindowProxyDrag ( WindowRef window, DragRef theDrag );
The window whose proxy icon is being dragged.
A value that refers to the current drag process. Pass in the value produced in the outNewDrag parameter of BeginWindowProxyDrag.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
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 );
The point, in global coordinates, where the mouse-down event occurred. Your application retrieves this information from the where field of the event structure.
A pointer to the window in which the mouse-down event occurred. FindWindow produces NULL if the mouse-down event occurred outside a window.
The location of the cursor when the user pressed the mouse button; see “Window Part Code Constants.”
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.
MacWindows.h
Finds a window of a specific class at the specified point onscreen.
OSStatus FindWindowOfClass ( const Point *where, WindowClass inWindowClass, WindowRef *outWindow, WindowPartCode *outWindowPart );
The point, in global coordinates, at which to search for a window.
The class of window for which to search. Passing kAllWindowClasses returns any window found at where.
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.
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.
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.”
This function is similar to FindWindow, but lets you restrict the search to windows of a particular class.
MacWindows.h
Returns to the application the frontmost visible window that is not a floating window.
WindowRef FrontNonFloatingWindow ( void );
The first visible window in the window list that is of a nonfloating class. See “Window Class Constants” for a description of window classes.
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.
MacWindows.h
Returns the window attributes that are valid for a window class
WindowAttributes GetAvailableWindowAttributes ( WindowClass inClass );
The window class to query.
The window attributes that are valid for the window class specified by inClass. See “Window Attributes” for a list of possible attributes.
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.
MacWindows.h
Obtains the available window positioning bounds.
OSStatus GetAvailableWindowPositioningBounds ( GDHandle inDevice, Rect *outAvailableRect );
The screen for which the available window positioning bounds are to be obtained.
On return, a pointer to the available bounds for the device specified by inDevice.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains the available window positioning region.
OSStatus GetAvailableWindowPositioningRegion ( GDHandle inDevice, RgnHandle ioRgn );
The screen for which the available window positioning region is to be obtained.
On input, contains a preallocated RgnHandle. On return, the RgnHandle has been modified to contain the available region for the given screen.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains the current window edge from which the drawer appears.
OptionBits GetDrawerCurrentEdge ( WindowRef inDrawerWindow );
The drawer window whose window edge is to be obtained.
The current window edge. See “Window Edge Constants” for a list of possible return values.
MacWindows.h
Obtains the positioning offsets of a drawer.
OSStatus GetDrawerOffsets ( WindowRef inDrawerWindow, CGFloat *outLeadingOffset, CGFloat *outTrailingOffset );
The drawer window whose positioning offsets are to be obtained.
On exit, a pointer to the drawer’s leading offset. Pass NULL if you don’t need this information.
On exit, a pointer to the drawer’s trailing offset. Pass NULL if you don’t need this information.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the parent window of a drawer.
WindowRef GetDrawerParent ( WindowRef inDrawerWindow );
The drawer window whose parent window is to be obtained.
The window that is the parent of the drawer specified by inDrawerWindow.
MacWindows.h
Obtains the preferred opening edge for a drawer.
OptionBits GetDrawerPreferredEdge ( WindowRef inDrawerWindow );
The drawer window whose preferred opening edge is to be obtained.
See “Window Edge Constants” for a list of possible values.
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.
MacWindows.h
Determines the current state of the drawer.
WindowDrawerState GetDrawerState ( WindowRef inDrawerWindow );
The drawer window whose state is to be determined.
See “Drawer State Constants” for a list of possible values.
MacWindows.h
Obtains the frontmost window of a given class.
WindowRef GetFrontWindowOfClass ( WindowClass inWindowClass, Boolean mustBeVisible );
The class of the window you want to obtain. If you pass kAllWindowClasses, the function returns the frontmost window in the window list.
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.
A reference to the frontmost window of the class specified by inWindowClass.
MacWindows.h
Obtains the window at the given index in the window group.
OSStatus GetIndexedWindow ( WindowGroupRef inGroup, ItemCount inIndex, WindowGroupContentOptions inOptions, WindowRef *outWindow );
The window group. For information on this data type,
The index of the window. This parameter may range from 1 to the value returned by CountWindowGroupContents.
Options for determining the number of windows. See “Window Group Content Options” for possible values.
The window at the index specified by inIndex in the group specified by inGroup.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns the next window in a window list.
WindowRef GetNextWindow ( WindowRef window );
The window to start from.
The next window in a window list.
MacWindows.h
Obtains the next window in a given window group.
WindowRef GetNextWindowOfClass ( WindowRef inWindow, WindowClass inWindowClass, Boolean mustBeVisible );
The window at which to start.
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.
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.
A reference for the next window of the specified class after the window specified by inWindow.
MacWindows.h
Returns the window above the specified window in the window list.
WindowRef GetPreviousWindow ( WindowRef inWindow );
The window at which to start.
A reference for the previous window of the specified class.
MacWindows.h
Obtains the parent window of a sheet.
OSStatus GetSheetWindowParent ( WindowRef inSheet, WindowRef *outParentWindow );
The window sheet whose parent is to be obtained.
A pointer to the reference for the parent of the window sheet specified by inSheet.
A result code. See “Window Manager Result Codes.”
MacWindows.hReturns the current user focus window.
WindowRef GetUserFocusWindow ( void );
The window receiving user focus.
This function returns the window that receives menu commands and keyboard input as part of the standard event dispatching.
MacWindows.h
Obtains a window’s activation scope.
OSStatus GetWindowActivationScope ( WindowRef inWindow, WindowActivationScope *outScope );
The window whose activation scope is to be obtained.
On return, a pointer to the window’s activation scope.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns the current alpha channel value for the window.
OSStatus GetWindowAlpha ( WindowRef inWindow, CGFloat *outAlpha );
The window for which the value of the alpha channel is to be obtained.
The current alpha value. This value can range from 0.0 (completely transparent) to 1.0 (opaque).
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the attributes of a window.
OSStatus GetWindowAttributes ( WindowRef window, WindowAttributes *outAttributes );
The window whose attributes you want to obtain.
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.
A result code. See “Window Manager Result Codes.”
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).
MacWindows.h
Obtains the size and position of the bounding rectangle of the specified window region.
OSStatus GetWindowBounds ( WindowRef window, WindowRegionCode regionCode, Rect *globalBounds );
The window whose bounds you want to obtain.
A constant identifying the window region whose bounds you want to obtain. See “Window Region Constants” for a list of possible values.
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.
A result code. See “Window Manager Result Codes.”
Use the GetWindowBounds function to obtain the bounding rectangle for the specified window region for the specified window.
MacWindows.hReturns the current Cancel button for a window.
OSStatus GetWindowCancelButton ( WindowRef inWindow, ControlRef *outControl );
The window whose Cancel button you want to obtain.
A pointer to a control. On output, the control is the Cancel button.
A result code.
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.
MacWindows.h
Obtains the class of a window.
OSStatus GetWindowClass ( WindowRef window, WindowClass *outClass );
The window whose class you want to obtain.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the color to which a window’s content region is redrawn.
OSStatus GetWindowContentColor ( WindowRef window, RGBColor *color );
The window whose content color is being retrieved.
On input, a pointer to an RGBColor structure. On return, the structure contains the content color for the specified window.
A result code. See “Window Manager Result Codes.”
The GetWindowContentColor function obtains the color to which the window’s content region is redrawn.
See also the function SetWindowContentColor.
MacWindows.h
Obtains the pattern to which a window’s content region is redrawn.
OSStatus GetWindowContentPattern ( WindowRef window, PixPatHandle outPixPat );
The window whose content pattern is being retrieved.
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.
A result code. See “Window Manager Result Codes.”
The GetWindowContentPattern function obtains the pattern to which the window’s content region is redrawn.
See also the function SetWindowContentPattern.
MacWindows.hReturns the current default button for a window.
OSStatus GetWindowDefaultButton ( WindowRef inWindow, ControlRef *outControl );
The window whose default button you want to obtain.
A pointer to a control. On output, the control is the default button.
A result code.
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.
MacWindows.h
Returns the menu to be displayed by a window’s dock tile.
MenuRef GetWindowDockTileMenu ( WindowRef inWindow );
The window whose menu is to be obtained.
The menu reference for the window specified by inWindow. See the Menu Manager documentation for a description of the MenuRef data type.
MacWindows.h
Obtains the features that a window supports.
OSStatus GetWindowFeatures ( WindowRef window, UInt32 *outFeatures );
A pointer to the window to be examined.
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.”
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Gets a window reference from a CGrafPtr data type.
WindowRef GetWindowFromPort ( CGrafPtr port );
The port to query.
The window reference obtained from the port specified by port, or NULL if the port parameter is not actually attached to a window.
MacWindows.h
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 );
The window to compare against.
The window region to compare against. See “Window Region Constants” for a list of possible values.
On return, the graphics device with the greatest intersection. May be NULL.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the window group associated with a window.
WindowGroupRef GetWindowGroup ( WindowRef inWindow );
The window whose window group is to be obtained.
The window group reference for the window specified by inWindow. For information on this data type, see WindowGroupRef.
MacWindows.h
Obtains the attributes of a window group.
OSStatus GetWindowGroupAttributes ( WindowGroupRef inGroup, WindowGroupAttributes *outAttributes );
The window group whose attributes are to be changed. For information on this data type,
On return, the attributes of the group. See “Window Group Attributes” for a list of possible values.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the contents of a window group.
OSStatus GetWindowGroupContents ( WindowGroupRef inGroup, WindowGroupContentOptions inOptions, ItemCount inAllowedItems, ItemCount *outNumItems, void **outItems );
The window group whose contents you want to obtain. For information on this data type, see WindowGroupRef.
Options for determining how to count the group members. See “Window Group Content Options” for a list of possible values.
The number of items that will fit in outItems.
On return, the number of items in the group.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the level of the group in the window class hierarchy.
OSStatus GetWindowGroupLevel ( WindowGroupRef inGroup, SInt32 *outLevel );
The window group. For information on this data type,
On exit, the window level of the windows in this group.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains the Core Graphics window level of a window group.
OSStatus GetWindowGroupLevelOfType ( WindowGroupRef inGroup, UInt32 inLevelType, CGWindowLevel *outLevel );
The window group whose Core Graphics window level is to be obtained.
The level type to obtain. Specify kWindowGroupLevelActive, kWindowGroupLevelInactive, or kWindowGroupLevelPromoted. For details, see “Window Group Level Constants.”
On output, the Core Graphics window level for the windows in this group.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains the window group corresponding to a given window class.
WindowGroupRef GetWindowGroupOfClass ( WindowClass windowClass );
The window class to query.
For information on this data type, see WindowGroupRef.
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.
MacWindows.h
Obtains the window that owns a window group. (if any)
WindowRef GetWindowGroupOwner ( WindowGroupRef inGroup );
The window group to query. For information on this data type,
The window reference for the window that owns the group specified by inGroup.
You call SetWindowGroupOwner to associate a window group with a particular window.
MacWindows.h
Obtains the parent group of a window group.
WindowGroupRef GetWindowGroupParent ( WindowGroupRef inGroup );
The window group whose parent is to be obtained.
The parent of the window group specified by inGroup.
You can nest window groups within each other.
MacWindows.h
Determines the current reference count for a window group.
ItemCount GetWindowGroupRetainCount ( WindowGroupRef inGroup );
The window group for which the current reference count is to be obtained. For information on this data type, see WindowGroupRef.
MacWindows.h
Obtains the next or previous group of a window group.
WindowGroupRef GetWindowGroupSibling ( WindowGroupRef inGroup, Boolean inNextGroup );
The window group for which the next or previous group is to be obtained. For information on this data type, see WindowGroupRef.
Pass true to obtain the next sibling; false to obtain the previous sibling.
The next or previous group. For information on this data type, see WindowGroupRef.
MacWindows.hObtains the size and position of a window in its user state.
OSStatus GetWindowIdealUserState ( WindowRef inWindow, Rect *outUserState );
The window for which you want to obtain the user state.
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.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains the index number of a specified window in a group.
OSStatus GetWindowIndex ( WindowRef inWindow, WindowGroupRef inStartGroup, WindowGroupContentOptions inOptions, ItemCount *outIndex );
The window whose window group index number is to be obtained.
The window group to query.
Specifies how to enumerate the specified window; kWindowGroupContentsReturnWindows is implied and does not need to be specified explicitly.
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.)
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns a window’s window kind.
short GetWindowKind ( WindowRef window );
The window whose window kind is to be returned.
An integer representing the window kind; see “Window Kinds.”
MacWindows.h
Obtains the first window in a window list.
WindowRef GetWindowList ( void );
A window reference for the first window in the list.
MacWindows.h
Obtains the modality of a window.
OSStatus GetWindowModality ( WindowRef inWindow, WindowModality *outModalKind, WindowRef *outUnavailableWindow );
The window whose modality is to be obtained.
On return, contains the modality of the window.
On return, if the window is window-modal, contains the target window of the specified window’s modality.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Gets the window’s color graphics port.
CGrafPtr GetWindowPort ( WindowRef window );
The window whose color graphics port is to be obtained.
A pointer to the window’s color graphics port. See the QuickDraw Manager documentation for a description of the CGrafPtr data type.
MacWindows.h
Obtains the bounds of the window port.
Rect * GetWindowPortBounds ( WindowRef window, Rect *bounds );
The window whose port bounds you want.
A pointer to a Rect structure. On return, the Rect structure contains the bounds of the window port.
The same value (pointer to a Rect structure) that was passed to GetWindowPortBounds in the bounds parameter.
MacWindows.h
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 );
The window to be examined for associated data.
The creator code (typically, the application’s signature) of the associated data to be obtained.
The application-defined code identifying the associated data to be obtained.
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.
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.
On input, a pointer to a buffer. On return, this buffer contains a copy of the data that is associated with the specified window.
A result code. See “Window Manager Result Codes.”
The data retrieved by the GetWindowProperty function must have been previously associated with the window with the function SetWindowProperty.
MacWindows.h
Obtains the attributes of a window property.
OSStatus GetWindowPropertyAttributes ( WindowRef window, OSType propertyCreator, OSType propertyTag, OptionBits *attributes );
The window having a property whose attributes are to be obtained.
The property creator.
The property tag.
On return, the property’s attributes. Currently, the only valid property is kWindowPropertyPersistent. For a description of this property, see “Window Property Persistent Constant.”
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the size of a piece of data that is associated with a window.
OSStatus GetWindowPropertySize ( WindowRef window, PropertyCreator creator, PropertyTag tag, ByteCount *size );
The window to be examined for associated data.
The creator code (typically, the application’s signature) of the associated data whose size is to be obtained.
The application-defined code identifying the associated data whose size is to be obtained.
A pointer to a value that, on return, specifies the size of the associated data.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Obtains an alias for the file that is associated with a window.
OSStatus GetWindowProxyAlias ( WindowRef window, AliasHandle *alias );
The window for which you want to determine the associated file.
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.
A result code. See “Window Manager Result Codes.”
Your application can call the GetWindowProxyAlias function to retrieve alias data for the file associated with a window.
See also the function SetWindowProxyAlias.
MacWindows.h
Obtains a window’s proxy icon.
OSStatus GetWindowProxyIcon ( WindowRef window, IconRef *outIcon );
The window for which you want to obtain the proxy icon.
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.
A result code. If no proxy icon is found, this function returns errWindowDoesNotHaveProxy. For other possible return values, see “Window Manager Result Codes.”
There are several different ways to associate a proxy icon with a window:
If you use the function SetWindowProxyIcon, GetWindowProxyIcon returns the proxy icon you set.
If you use the function SetWindowProxyCreatorAndType, that function uses Icon Services to find and set the proxy icon corresponding to the creator and type. GetWindowProxyIcon returns that icon.
If you use SetWindowProxyAlias, SetWindowProxyFSSpec, or HIWindowSetProxyFSRef, then GetWindowProxyIcon attempts to resolve the alias (if available) and returns the icon associated with the specified file.
MacWindows.h
Returns the minimum and maximum content sizes for a window.
OSStatus GetWindowResizeLimits ( WindowRef inWindow, HISize *outMinLimits, HISize *outMaxLimits );
The window whose minimum and maximum content sizes are to be obtained.
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.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains a window’s standard zoom rectangle.
Rect * GetWindowStandardState ( WindowRef window, Rect *rect );
The window whose standard zoom rectangle is to be obtained.
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.
The same value (pointer to a Rect structure) that was passed to GetWindowStandardState in the rect parameter.
MacWindows.h
Obtains a graphics port that is used when drawing a window’s structure.
CGrafPtr GetWindowStructurePort ( WindowRef inWindow );
The window to query.
The CGrafPtr that is used when drawing the window’s structure (window frame).
MacWindows.h
Obtains the width of the structure region on each edge of a window.
OSStatus GetWindowStructureWidths ( WindowRef inWindow, Rect *outRect );
The window to query.
On return, the Rect structure is filled in with the widths of the structure.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Obtains the toolbar associated with a window.
OSStatus GetWindowToolbar ( WindowRef inWindow, HIToolbarRef *outToolbar );
The window whose toolbar is to be obtained.
On return, the toolbar that is attached to the window, or NULL if the window has no toolbar.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns a window’s user zoom rectangle.
Rect * GetWindowUserState ( WindowRef window, Rect *rect );
The window whose user zoom rectangle is to be returned.
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.
The same value (pointer to a Rect structure) that was passed to GetWindowUserState in the rect parameter.
MacWindows.h
Obtains the window part code of the window widget that is currently highlighted.
OSStatus GetWindowWidgetHilite ( WindowRef inWindow, WindowDefPartCode *outHilite );
The window to query.
The highlight.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns the reference constant from a window.
SRefCon GetWRefCon ( WindowRef window );
The window whose reference constant is to be returned.
The long integer data stored in the refCon field of the window structure specified in the window parameter.
MacWindows.h
Hides an application’s floating windows.
OSStatus HideFloatingWindows ( void );
A result code. For details, see “Window Manager Result Codes.”
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.
The HideFloatingWindows function operates only upon windows created with the kFloatingWindowClass constant; see “Window Class Constants” for more details on this constant.
MacWindows.h
Hides a sheet window using appropriate visual effects.
OSStatus HideSheetWindow ( WindowRef inSheet );
The window sheet that is to be hidden.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Makes a window invisible.
void HideWindow ( WindowRef window );
The window that is to be made invisible.
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.
MacWindows.hSets a window’s highlighting status.
void HiliteWindow ( WindowRef window, Boolean fHilite );
On input, a pointer to the window structure.
On input, a Boolean value that specifies the highlighting status: true highlights a window; false removes highlighting.
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.
MacWindows.h
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 );
The window for which you want to set the highlight state.
Pass true if the window’s frame should be highlighted otherwise, pass false.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hChanges the attributes of a window.
OSStatus HIWindowChangeAttributes ( WindowRef inWindow, const int *inAttrToSet, const int *inAttrToClear );
The window to change.
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.
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.
A result code. See “Window Manager Result Codes.”
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); |
In Mac OS X v10.4 or earlier, you can use the function ChangeWindowAttributes to achieve similar results.
MacWindows.h
Changes the availability of a window during Exposé or in Spaces.
OSStatus HIWindowChangeAvailability ( WindowRef inWindow, HIWindowAvailability inSetAvailability, HIWindowAvailability inClearAvailability );
The window whose availability is to be changed.
The availability bits to set. For details, see “Window Availability Constants.”
The availability bits to clear. For details, see “Window Availability Constants.”
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Changes the appearance and behavior of a window.
OSStatus HIWindowChangeClass ( WindowRef inWindow, WindowClass inWindowClass );
The window whose class you want to change.
The new class that is to be applied to the window. See “Window Class Constants” for a list of possible window classes.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hChanges a window’s features.
OSStatus HIWindowChangeFeatures ( WindowRef inWindow, UInt64 inSetThese, UInt64 inClearThese );
The window whose features are to be changed.
The feature bits to set. For details, see “Window Feature Bits.”
The feature bits to clear. For details, see “Window Feature Bits.”
A result code. See “Window Manager Result Codes.”
HIWindowChangeFeatures changes the features of a window on the fly. This function should only be used by custom window definitions or window frame views.
MacWindows.h
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 );
The window to constrain.
The window region to constrain. For a list of possible values, see “Window Region Constants”.
Flags controlling how the window is constrained. For a list of possible options, see “Window Constrain Options”.
The coordinate space in which the inScreenBounds, inMinimumSize, and ioBounds parameters are expressed. This parameter must be either kHICoordSpaceScreenPixels or kHICoordSpace72DPIGlobal.
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.
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.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.hCopies the available window positioning shape on a display.
OSStatus HIWindowCopyAvailablePositioningShape ( CGDirectDisplayID inDisplay, HICoordinateSpace inSpace, HIShapeRef *outShape );
The display for which to find the available shape. May be kCGNullDirectDisplay to request the shape of the main display.
The coordinate space in which the positioning shape should be returned. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
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.
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.
MacWindows.hObtains an array of the drawers that are attached to a window.
OSStatus HIWindowCopyDrawers ( WindowRef inWindow, CFArrayRef *outDrawers );
The parent window to access.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.hRetrieves a shape that describes a region of a window.
OSStatus HIWindowCopyShape ( WindowRef inWindow, WindowRegionCode inRegion, HICoordinateSpace inSpace, HIShapeRef *outShape );
The window to access.
The window region whose shape you want to obtain. For a list of possible values, see “Window Region Constants.”
The coordinate space in which the shape should be returned. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.
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.
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.”
MacWindows.hCreates a standard or custom window.
OSStatus HIWindowCreate ( WindowClass inClass, const int *inAttributes, const WindowDefSpec *inDefSpec, HICoordinateSpace inSpace, const HIRect *inBounds, WindowRef *outWindow );
The class of window to be created. For a list of possible classes, see “Window Class Constants”.
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”.
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.
The coordinate space in which the content bounds is expressed. This parameter must be either kHICoordSpaceScreenPixels or kHICoordSpace72DPIGlobal.
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.
A pointer to a window variable. On output, the variable contains the new window.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hCreates a Quartz graphics context for drawing a collapsed window’s Dock tile.
OSStatus HIWindowCreateCollapsedDockTileContext ( WindowRef inWindow, CGContextRef *outContext, HISize *outContextSize );
The collapsed window.
A pointer to a CGContextRef variable. On output, the variable contains the graphics context for drawing the window’s Dock tile.
A pointer to a HISize structure. On output, the structure contains the width and height of the area in which to draw.
A result code. If the window is not collapsed, the result code is windowWrongStateErr. For other possible values, see “Window Manager Result Codes.”
When you are finished drawing in the graphics context, you should:
Call CGContextFlush to ensure that your drawing appears onscreen.
Call HIWindowReleaseCollapsedDockTileContext to release the context. Do not call CFRelease or CGContextRelease to release the context, or you may leak system resources.
MacWindows.hFinds 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 );
The location, in global coordinates, at which to search for a window.
The coordinate space in which the location is expressed. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
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.
Reserved. Pass zero.
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.
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.
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.
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.”
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.
MacWindows.h
Flushes any dirty areas a window might have.
OSStatus HIWindowFlush ( WindowRef inWindow );
The window to flush.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hReturns the window in the current process with a specified Quartz window ID.
WindowRef HIWindowFromCGWindowID ( CGWindowID inWindowID );
The window ID, as returned by HIWindowGetCGWindowID or CGWindowListCopyWindowInfo.
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.
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.
MacWindows.hObtains the availability of a window during Exposé or in Spaces.
OSStatus HIWindowGetAvailability ( WindowRef inWindow, HIWindowAvailability *outAvailability );
The window whose availability is to be obtained.
On exit, the current setting of the window’s availability bits. For details, see “Window Availability Constants.”
A result code. See “Window Manager Result Codes.”
MacWindows.hGets the available window positioning bounds on a display.
OSStatus HIWindowGetAvailablePositioningBounds ( CGDirectDisplayID inDisplay, HICoordinateSpace inSpace, HIRect *outAvailableRect );
The display for which to find the available bounds. May be kCGNullDirectDisplay to request the bounds of the main display.
The coordinate space in which the positioning bounds should be returned. This must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
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.
A result code. See “Window Manager Result Codes.”
This function gets the bounds of the display not including the menu bar and Dock, if located on that display.
MacWindows.hGets the bounds of a specified region of a window.
OSStatus HIWindowGetBounds ( WindowRef inWindow, WindowRegionCode inRegion, HICoordinateSpace inSpace, HIRect *outBounds );
The window to access.
The window region. For a list of possible values, see “Window Region Constants”.
The coordinate space in which the bounds should be returned. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.
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.
A result code. If the window does not support the specified window region, the result returned is errWindowRegionCodeInvalid.
MacWindows.h
Returns the Quartz window ID assigned to a window.
CGWindowID HIWindowGetCGWindowID ( WindowRef inWindow );
The window to access.
The window ID of the specified window, or zero if the window is invalid.
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.
MacWindows.hFinds the display with the greatest area of intersection with a window region.
OSStatus HIWindowGetGreatestAreaDisplay ( WindowRef inWindow, WindowRegionCode inRegion, HICoordinateSpace inSpace, CGDirectDisplayID *outGreatestDisplay, HIRect *outGreatestDisplayRect );
The window to compare against.
The window region to compare against. See “Window Region Constants” for a list of possible values.
The coordinate space in which the display bounds should be returned. This must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
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.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Gets the bounds of a window’s content region in its user state.
OSStatus HIWindowGetIdealUserState ( WindowRef inWindow, HICoordinateSpace inSpace, HIRect *outUserState );
The window to access.
The coordinate space in which the user state bounds should be returned. This parameter must be kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
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.
A result code. See “Window Manager Result Codes.”
This function returns information about the window’s user state most recently recorded by the function ZoomWindowIdeal.
MacWindows.hObtains the FSRef used to determine the proxy icon for a window.
OSStatus HIWindowGetProxyFSRef ( WindowRef window, FSRef *outRef );
The window whose proxy FSRef is to be obtained.
On exit, the FSRef for the window’s proxy icon.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hObtains the window’s scale mode and the application’s display scale factor.
OSStatus HIWindowGetScaleMode ( WindowRef inWindow, HIWindowScaleMode *outMode, CGFloat *outScaleFactor );
The window whose scale mode is to be obtained.
On exit, an HIWindowScaleMode indicating the window’s scale mode. For details, see “Window Scale Mode Constants.”
On exit, a float indicating the display scale factor for the application. Pass NULL if you are not interested in acquiring the scale factor.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hGets the theme background brush for a window.
OSStatus HIWindowGetThemeBackground ( WindowRef inWindow, ThemeBrush *outThemeBrush );
The window from which to get the brush.
A pointer to a theme brush. On output, the brush is the window’s theme background brush.
A result code. If no brush is found, themeNoAppropriateBrushErr is returned.
This function gets the theme background brush previously set by calling the function SetThemeWindowBackground.
MacWindows.hRecalculates a window’s shadow.
OSStatus HIWindowInvalidateShadow ( WindowRef inWindow );
The window whose shadow is to be recalculated.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hReturns a Boolean value indicating whether a window attribute is valid for a specified window class.
Boolean HIWindowIsAttributeAvailable ( WindowClass inClass, int inAttr );
The window class to test.
The window attribute to test. You must specify one of the window attributes described in “Window Attribute Identifiers”.
If true, the window class supports the specified attribute. Otherwise, false.
MacWindows.hDetermines if a window is currently the target window of another document modal window, such as a sheet.
Boolean HIWindowIsDocumentModalTarget ( WindowRef inWindow, WindowRef *outOwner );
The window to query.
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.
A Boolean whose value is true if the window specified by inWindow is currently the target of a document modal window; otherwise, false.
MacWindows.h
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 );
The window whose zoom state is to be determined.
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.
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.
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.
If true, the window is currently in its standard state. If false, the window is currently in its user state.
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.
MacWindows.hReleases a Quartz graphics context for drawing a collapsed window’s Dock tile.
OSStatus HIWindowReleaseCollapsedDockTileContext ( WindowRef inWindow, CGContextRef inContext );
The collapsed window.
The graphics context to release. On return, the context is invalid and should no longer be used.
A result code. If the window is not collapsed, the result code is windowWrongStateErr. For other possible values, see “Window Manager Result Codes.”
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.
MacWindows.hSets the bounds of a window based on either the structure or content region.
OSStatus HIWindowSetBounds ( WindowRef inWindow, WindowRegionCode inRegion, HICoordinateSpace inSpace, HIRect *inBounds );
The window to access.
The window region on which to base the window's new bounds. This parameter must be either kWindowStructureRgn or kWindowContentRgn.
The coordinate space in which the bounds are expressed. This parameter must be kHICoordSpaceWindow, kHICoordSpaceScreenPixel, or kHICoordSpace72DPIGlobal.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets the bounds of a window’s content region in its user state.
OSStatus HIWindowSetIdealUserState ( WindowRef inWindow, HICoordinateSpace inSpace, const HIRect *inUserState );
The window to access.
The coordinate space in which the user state bounds are expressed. This parameter must be either kHICoordSpaceScreenPixel or kHICoordSpace72DPIGlobal.
The new bounds (position and size) of the window’s content region in its user state.
A result code. See “Window Manager Result Codes.”
A window’s ideal user state is used by the function ZoomWindowIdeal when zooming in.
MacWindows.h
Sets the proxy icon for a window using an FSRef to a file system object.
OSStatus HIWindowSetProxyFSRef ( WindowRef window, const FSRef *inRef );
The window whose proxy icon is to be set.
The file system object the window represents.
A result code. See “Window Manager Result Codes.”
This function determines the window’s proxy icon by asking Icon Services for the icon for the object specified by inRef.
MacWindows.hSets a custom toolbar view for a window.
OSStatus HIWindowSetToolbarView ( WindowRef inWindow, HIViewRef inView );
The window whose toolbar view to set.
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.
A result code.
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.
MacWindows.hReturns a Boolean value indicating whether a window's content should show focus indicators such as focus rings.
Boolean HIWindowShowsFocus ( WindowRef inWindow );
The window to access.
If true, a window's content should show focus indicators; otherwise false.
This function returns true if the window is either the modeless focus or the effective focus.
MacWindows.hReturns a Boolean value indicating whether a window has a specified attribute.
Boolean HIWindowTestAttribute ( WindowRef inWindow, int inAttr );
The window to test.
The window attribute to test. You must specify one of the window attributes described in “Window Attribute Identifiers”.
If true, the window has the specified attribute. Otherwise, false.
MacWindows.hTracks the drag of a window proxy icon.
OSStatus HIWindowTrackProxyDrag ( WindowRef inWindow, EventRef inEvent, DragRef inDrag );
The window whose proxy icon to drag.
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.
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.
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.
MacWindows.h
Adds a rectangle to a window’s update region.
OSStatus InvalWindowRect ( WindowRef window, const Rect *bounds );
The window containing the rectangle you want to be updated.
Set this structure to specify, in local coordinates, a rectangle to be added to the window’s update region.
A result code. See “Window Manager Result Codes.”
The InvalWindowRect function informs the Window Manager that an area of a window should be redrawn.
See also the functions ValidWindowRect and InvalWindowRgn.
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.
MacWindows.h
Adds a region to a window’s update region.
OSStatus InvalWindowRgn ( WindowRef window, RgnHandle region );
The window containing the region that you want to update.
Set this region to specify, in local coordinates, the area to be added to the window’s update region.
A result code. See “Window Manager Result Codes.”
The InvalWindowRgn function informs the Window Manager that an area of a window should be redrawn.
See also the functions InvalWindowRect and ValidWindowRgn.
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.
MacWindows.h
Determines whether a given window class is valid.
Boolean IsValidWindowClass ( WindowClass inClass );
The window class to query.
A Boolean whose value is true if the window class is valid; otherwise, false.
MacWindows.h
Reports whether a pointer is a valid window pointer.
Boolean IsValidWindowPtr ( WindowRef possibleWindow );
The window to query.
A Boolean whose value is true if the specified pointer is a valid window pointer; otherwise, false.
This function is primarily intended for use with debugging your application.
The IsValidWindowPtr function is a processor-intensive call.
MacWindows.h
Indicates whether the specified window is active.
Boolean IsWindowActive ( WindowRef inWindow );
The window to query.
Returns true if the window is active, false otherwise.
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.
MacWindows.h
Determines whether a window can be collapsed.
Boolean IsWindowCollapsable ( WindowRef window );
The window to be examined.
If true, the window can be collapsed; otherwise, false.
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.
MacWindows.h
Determines whether a window is currently collapsed.
Boolean IsWindowCollapsed ( WindowRef window );
The window to be examined.
If true, the window is collapsed. If false, the window is expanded.
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.
MacWindows.h
Determines if a window is a member of a window group or any of its subgroups.
Boolean IsWindowContainedInGroup ( WindowRef inWindow, WindowGroupRef inGroup );
The window to query.
The window group to query.
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.
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.
MacWindows.h
Indicates whether the window frame is currently highlighted.
Boolean IsWindowHilited ( WindowRef window );
The window to query.
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.
MacWindows.hDetermines 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 );
The window whose zoom state is to be determined.
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.
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.
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.
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.
MacWindows.h
Indicates whether a window is visible onscreen or is latently visible but not currently onscreen.
Boolean IsWindowLatentVisible ( WindowRef inWindow, WindowLatentVisibility *outLatentVisible );
The window to query.
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.
A Boolean whose value is true if the window is currently onscreen; otherwise, false.
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.
MacWindows.hObtains the modification state of the specified window.
Boolean IsWindowModified ( WindowRef window );
The window whose modification state is to be obtained.
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.
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.
MacWindows.h
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 );
The window to query.
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.
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.
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.
MacWindows.h
Determines whether a window’s toolbar is visible.
Boolean IsWindowToolbarVisible ( WindowRef inWindow );
The window to query.
A Boolean whose value is true if the window’s toolbar is visible; otherwise, false.
MacWindows.h
Determines whether a window update is pending.
Boolean IsWindowUpdatePending ( WindowRef window );
The non-composited window to query.
A Boolean whose value is true if an update is pending; otherwise, false.
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.
MacWindows.h
Indicates whether the window frame is currently visible.
Boolean IsWindowVisible ( WindowRef window );
The window to query.
A Boolean value indicating whether or not the window is visible. If true, the window is visible. If false, the window is invisible.
MacWindows.h
Moves a window on the desktop.
void MoveWindow ( WindowRef window, short hGlobal, short vGlobal, Boolean front );
The window that is to be moved on the desktop.
On input, the new location, in global coordinates, of the left edge of the window’s port rectangle.
On input, the new location, in global coordinates, of the top edge of the window’s port rectangle.
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.
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.
MacWindows.h
Positions a window relative to its structure region.
OSStatus MoveWindowStructure ( WindowRef window, short hGlobal, short vGlobal );
The window that is to be moved.
A value specifying the horizontal position, in global coordinates, to which the left edge of the window’s structure region is to be moved.
A value specifying the vertical position, in global coordinates, to which the top edge of the window’s structure region is to be moved.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Opens a drawer.
OSStatus OpenDrawer ( WindowRef inDrawerWindow, OptionBits inEdge, Boolean inAsync );
The drawer window to open.
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.
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.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Returns the point within the specified rectangle that is closest to the specified point.
long PinRect ( const Rect *theRect, Point thePt );
On input, a pointer to a rectangle in which the point is to be contained.
On input, a pointer to the point to be contained.
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.
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
if the horizontal position is to the left of the rectangle, PinRect returns the left edge as the horizontal coordinate
if the horizontal position is to the right of the rectangle, PinRect returns the right edge minus 1 as the horizontal coordinate
if the vertical position is above the rectangle, PinRect returns the top edge as the vertical coordinate
if the vertical position is below the rectangle, PinRect returns the bottom edge minus 1 as the vertical coordinate
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.
MacWindows.h
Registers a binding between a resource ID and a window definition function.
OSStatus RegisterWindowDefinition ( SInt16 inResID, const WindowDefSpec *inDefSpec );
A WDEF proc ID, as used in a 'WIND' resource.
Specifies the WindowDefUPP that should be used for windows with the given WDEF proc ID. Pass NULL to unregister a given WDEF proc ID.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Decrements the reference count for a window group.
OSStatus ReleaseWindowGroup ( WindowGroupRef inGroup );
The window group whose reference count is to be queried.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Removes a piece of data that is associated with a window.
OSStatus RemoveWindowProperty ( WindowRef window, PropertyCreator propertyCreator, PropertyTag propertyTag );
The window whose data is to be removed.
The creator code (typically, the application’s signature) of the associated data to be removed.
The application-defined code identifying the associated data to be removed.
A result code. See “Window Manager Result Codes.”
The data removed by the RemoveWindowProperty function must have been previously associated with the window with the function SetWindowProperty.
MacWindows.h
Dissociates a file from a window.
OSStatus RemoveWindowProxy ( WindowRef window );
The window for which you want to remove the associated file.
A result code. See “Window Manager Result Codes.”
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.
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.
MacWindows.h
Positions a window relative to another window or a display screen.
OSStatus RepositionWindow ( WindowRef window, WindowRef parentWindow, WindowPositionMethod method );
The window whose position you want to set.
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.
A constant specifying the window positioning method to be used; see “Window Position Constants” for descriptions of possible values.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Notifies the Window Manager that a custom window’s shape has changed.
OSStatus ReshapeCustomWindow ( WindowRef window );
The window whose shape has changed.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Handles all user interaction while a window is being resized.
Boolean ResizeWindow ( WindowRef inWindow, Point inStartPoint, const Rect *inSizeConstraints, Rect *outNewContentRect );
The window that is to be resized.
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.
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.
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.
true if the window was successfully resized; otherwise, false.
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.
MacWindows.h
Increments the reference count for a window group.
OSStatus RetainWindowGroup ( WindowGroupRef inGroup );
The window group whose reference count is to be incremented. For information on this data type, see WindowGroupRef.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Scroll any area of a window.
OSStatus ScrollWindowRect ( WindowRef inWindow, const Rect *inScrollRect, SInt16 inHPixels, SInt16 inVPixels, ScrollWindowOptions inOptions, RgnHandle outExposedRgn );
The window to scroll in.
The rectangle to scroll, in local coordinates.
The number of pixels to scroll horizontally.
The number of pixels to scroll vertically.
Options for the scroll. See “Window Scrolling Options” for a list of possible options.
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.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Scrolls a window’s region.
OSStatus ScrollWindowRegion ( WindowRef inWindow, RgnHandle inScrollRgn, SInt16 inHPixels, SInt16 inVPixels, ScrollWindowOptions inOptions, RgnHandle outExposedRgn );
The window to scroll in.
The region to scroll, in local coordinates.
The number of pixels to scroll horizontally.
The number of pixels to scroll vertically.
Options for the scroll. See “Window Scrolling Options” for a list of possible options.
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.
A result code. See “Window Manager Result Codes.”
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
MacWindows.h
Makes a window active.
void SelectWindow ( WindowRef window );
The window that is to be made active.
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).
MacWindows.h
Moves one window behind another.
void SendBehind ( WindowRef window, WindowRef behindWindow );
The window to be moved.
On input, a pointer to the window that is to be in front of the moved window.
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.
MacWindows.hOrders one window group behind another.
OSStatus SendWindowGroupBehind ( WindowGroupRef inGroup, WindowGroupRef behindGroup );
The window group.
The “behind” window group.
A result code. See “Window Manager Result Codes.”
A window group can contain multiple window groups. You can use this function to order nested groups.
MacWindows.h
Sets the positioning offsets for the drawer with respect to its parent window.
OSStatus SetDrawerOffsets ( WindowRef inDrawerWindow, CGFloat inLeadingOffset, CGFloat inTrailingOffset );
The drawer window whose positioning offsets are to be set.
The new leading offset, in pixels. Pass kWindowOffsetUnchanged if you don’t want to change the leading offset.
The new trailing offset, in pixels. Pass kWindowOffsetUnchanged if you don’t want to change the trailing offset.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets the parent window for a drawer.
OSStatus SetDrawerParent ( WindowRef inDrawerWindow, WindowRef inParent );
The drawer window whose parent window is to be set.
The window that is to be set as the parent of the window specified by inDrawerWindow.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Set the preferred window edge from which the drawer should appear.
OSStatus SetDrawerPreferredEdge ( WindowRef inDrawerWindow, OptionBits inEdge );
The drawer window whose preferred window edge is to be set.
The preferred edge. See “Window Edge Constants” for a list of possible values.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets the current graphics port to the window’s port.
void SetPortWindowPort ( WindowRef window );
The window whose graphics port is to be set.
MacWindows.hSets a text color that contrasts with a theme brush.
OSStatus SetThemeTextColorForWindow ( WindowRef inWindow, Boolean inActive, SInt16 inDepth, Boolean inColorDev );
The window whose text color is to be set.
A Boolean whose value is true to indicate an active state or false to indicate an inactive state.
The bit depth of the window’s port. In Mac OS X, this parameter is ignored and should always be set to 32.
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.
A result code. See “Window Manager Result Codes” for a list of possible values.
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.
MacWindows.h
Sets a window’s background theme.
OSStatus SetThemeWindowBackground ( WindowRef inWindow, ThemeBrush inBrush, Boolean inUpdate );
The window whose background theme is to be set.
The theme brush that determines how the window background is painted. For information on theme brushes, see the Appearance Manager documentation.
A Boolean whose value is true if you want the window to be redrawn immediately using the new background brush; otherwise, false.
A result code. See “Window Manager Result Codes” for a list of possible values.
MacWindows.hDesignates a window to receive user focus.
OSStatus SetUserFocusWindow ( WindowRef inWindow );
A result code.
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.
MacWindows.h
Sets a window’s activation scope.
OSStatus SetWindowActivationScope ( WindowRef inWindow, WindowActivationScope inScope );
The window whose activation scope is to be set.
The new activation scope.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets the window’s alpha channel value.
OSStatus SetWindowAlpha ( WindowRef inWindow, CGFloat inAlpha );
The window whose alpha channel value is to be set.
The alpha value to set. This value can range from 0.0 (completely transparent) to 1.0 (opaque).
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets an alternate window title.
OSStatus SetWindowAlternateTitle ( WindowRef inWindow, CFStringRef inTitle );
The window for which to set the alternate title.
The alternate title for the window. Passing NULL for this parameter will remove any alternate title that might be present.
A result code. See “Window Manager Result Codes.” An operating system status code.
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).
MacWindows.h
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 );
The window whose bounds are to be set.
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.
Set the rectangle to specify the dimensions and position, in global coordinates, of the window region specified in the regionCode parameter.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hSpecifies a Cancel button for a window.
OSStatus SetWindowCancelButton ( WindowRef inWindow, ControlRef inControl );
The window whose Cancel button you want to set.
The control to designate as the Cancel button.
A result code.
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.
MacWindows.h
Sets the color to which a window’s content region is redrawn.
OSStatus SetWindowContentColor ( WindowRef window, const RGBColor *color );
The window whose content color is to be set.
Set this structure to specify the content color to be used.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Sets the pattern to which a window’s content region is redrawn.
OSStatus SetWindowContentPattern ( WindowRef window, PixPatHandle pixPat );
A pointer to the window whose content pattern is being set.
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.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.hSpecifies a default button for a window.
OSStatus SetWindowDefaultButton ( WindowRef inWindow, ControlRef inControl );
The window whose default button you want to set.
The control to designate as the default.
A result code.
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.
MacWindows.h
Associates a pop-up menu with a window.
OSStatus SetWindowDockTileMenu ( WindowRef inWindow, MenuRef inMenu );
The window with which a pop-up menu is to be associated.
The pop-up menu that is to be associated with the window specified by inWindow
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Assigns a window to a window group.
OSStatus SetWindowGroup ( WindowRef inWindow, WindowGroupRef inNewGroup );
The window that is to be assigned to a window group.
The window group. For information on this data type, see WindowGroupRef.
A result code. See “Window Manager Result Codes.”
MacWindows.h
Sets the level of group in the window class hierarchy.
OSStatus SetWindowGroupLevel ( WindowGroupRef inGroup, SInt32 inLevel );
The window group.
The new level for the windows in this group.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Sets the window level of a window group.
OSStatus SetWindowGroupLevelOfType ( WindowGroupRef inGroup, UInt32 inLevelType, CGWindowLevel inLevel );
The window group whose Core Graphics window level is to be set.
The level type to set. Specify kWindowGroupLevelActive or kWindowGroupLevelInactive. For details, see “Window Group Level Constants.”
The new level that is to be set for the windows in this group.
A result code. See “Window Manager Result Codes.”
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.
MacWindows.h
Assigns a name to a window group.
OSStatus SetWindowGroupName ( WindowGroupRef inGroup, CFStringRef inName );
The window group. For information on this data type, s