ADC Home > Reference Library > Reference > Carbon > User Experience > Window Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Window Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

CalcVis

Calculates the visible region of a window. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void CalcVis (
   WindowRef window
);

Parameters
window

On input, a pointer to the window’s complete window structure.

Discussion

The Window Manager calls the CalcVis function; your application does not normally need to. CalcVis calculates the visible region of the specified window by starting with its content region and subtracting the structure region of each window in front of it.

Special Considerations

In Mac OS X, the visible region of a window is managed by the window server. Applications never need to call this function.

Availability
Declared In
MacWindows.h

CalcVisBehind

Calculates the visible regions of a series of windows. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void CalcVisBehind (
   WindowRef startWindow,
   RgnHandle clobberedRgn
);

Parameters
startWindow

On input, a pointer to a window structure.

clobberedRgn

On input, a handle to the desktop region that has become invalid.

Discussion

The Window Manager calls the CalcVisBehind function; your application does not normally need to. CalcVisBehind calculates the visible regions of the window specified by the startWindow parameter and all windows behind startWindow that intersect clobberedRgn. It is called after PaintBehind.

Special Considerations

In Mac OS X, the visible region of a window is managed by the window server. Applications never need to call this function.

Availability
Declared In
MacWindows.h

CheckUpdate

Scans the window list for windows that need updating. (Deprecated in Mac OS X v10.5. Use FindSpecificEventInQueue or AcquireFirstMatchingEventInQueue instead.)

Boolean CheckUpdate (
   EventRecord *theEvent
);

Parameters
theEvent

On input, a pointer to an event structure to be filled in if a window needs updating.

Return Value

A Boolean value. If CheckUpdate finds a window structure whose update region is not empty and whose window structure does not contain a picture handle, it stores an update event in the event structure referenced through the parameter theEvent and returns true. If it finds no such window, it returns false.

Discussion

The Event Manager calls the CheckUpdate function; your application does not normally need to. CheckUpdate scans the window list from front to back, checking for a visible window that needs updating (that is, a visible window whose update region is not empty). If it finds one whose window structure contains a picture handle, it redraws the window itself and continues through the list.

Special Considerations

If you are using a compositing window, the Window Manager never generates update events for the window and you will never find update events in the event queue.

Availability
Declared In
MacWindows.h

ClipAbove

Determines the clip region of the Window Manager port. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void ClipAbove (
   WindowRef window
);

Parameters
window

On input, a pointer to the window.

Discussion

The Window Manager calls the ClipAbove function; your application does not normally need to. ClipAbove sets the clip region of the Window Manager port to be the area of the desktop that intersects the current clip region, minus the structure regions of all the windows in front of the specified window.

ClipAbove retrieves the desktop region from the global variable GrayRgn.

Special Considerations

Mac OS X applications never need to call this function.

Availability
Declared In
MacWindows.h

CloneWindow

Increments the number of references to a window. (Deprecated in Mac OS X v10.5. Use CFRetain instead.)

OSStatus CloneWindow (
   WindowRef window
);

Parameters
window

The window whose reference count is to be incremented.

Return Value

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

Discussion

You should call CloneWindow if you are using a window and want to ensure that it is not disposed while you are using it. With the Window Manager in Mac OS 8.5 and later, all windows are created with a reference count (owner count) of one. The function CloneWindow increments the number of references to a window, and the earlier function DisposeWindow decrements the number of references. When the reference count reaches zero, DisposeWindow disposes of the window.

In Mac OS X v10.2 and later, you can also call CFRetain to increment the reference count of a window.

Special Considerations

To maintain an accurate reference count, you must follow every call to the CloneWindow function with a matching call to the DisposeWindow function when your application is ready to release its reference to the window.

Availability
Declared In
MacWindows.h

CreateQDContextForCollapsedWindowDockTile

Obtains a CGrafPtr for a collapsed window’s tile in the dock. (Deprecated in Mac OS X v10.5. Use HIWindowCreateCollapsedDockTileContext instead.)

OSStatus CreateQDContextForCollapsedWindowDockTile (
   WindowRef inWindow,
   CGrafPtr *outContext
);

Parameters
inWindow

The window whose CGrafPtr is to be obtained.

outContext

On output, a pointer to the window’s CGrafPtr.

Return Value

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

Availability
Related Sample Code
Declared In
MacWindows.h

CreateWindowFromCollection

Creates a window from collection data. (Deprecated in Mac OS X v10.5. Use HIArchiveCopyDecodedCFType to decode a window from an archive instead.)

OSStatus CreateWindowFromCollection (
   Collection collection,
   WindowRef *outWindow
);

Parameters
collection

A reference to the collection to be used in creating the window. You pass a reference to a previously created collection, such as that returned by the Collection Manager function NewCollection. The collection used to create the window must contain the required items for a resource of type ‘wind’ or window creation fails.

outWindow

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

Return Value

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

Discussion

This function creates a window invisibly and places it at the front of the window’s window group. After calling CreateWindowFromCollection, 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. The number of references to the collection (that is, its owner count) is incremented by a minimum of one for the duration of this call.

Availability
Declared In
MacWindows.h

CreateWindowFromResource

Creates a window from 'wind' resource data. (Deprecated in Mac OS X v10.5. Use nib files and CreateWindowFromNib instead.)

OSStatus CreateWindowFromResource (
   SInt16 resID,
   WindowRef *outWindow
);

Parameters
resID

The resource ID of a resource of type ‘wind’. Pass in the ID of the 'wind' resource to be used to create the window.

outWindow

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

Return Value

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

Discussion

The CreateWindowFromResource function loads a window from a 'wind' resource. The Window Manager creates the window invisibly and places it at the front of the window’s window group. After calling CreateWindowFromResource, you should set any desired associated data—using Window Manager or Control Manager accessor functions—then call the function TransitionWindow or ShowWindow to display the window.

Availability
Declared In
MacWindows.h

DisposeWindowDefUPP

Disposes of the UPP for your window definition. (Deprecated in Mac OS X v10.5. The WDEF interface is deprecated; use a custom HIView to draw your custom window frame instead.)

void DisposeWindowDefUPP (
   WindowDefUPP userUPP
);

Parameters
userUPP

The UPP that is to be disposed of.

Availability
Declared In
MacWindows.h

DisposeWindowPaintUPP

Disposes of the UPP to your region painting callback function. (Deprecated in Mac OS X v10.5. The window content painting interface is deprecated; use a kEventControlDraw Carbon event handler on a compositing window’s content view instead.)

void DisposeWindowPaintUPP (
   WindowPaintUPP userUPP
);

Parameters
userUPP

The UPP that is to be disposed of.

Availability
Declared In
MacWindows.h

DragGrayRgn

Moves a gray outline of a region on the screen, following the movements of the cursor, until the mouse button is released. (Deprecated in Mac OS X v10.5. Use an overlay window or other custom drawing instead.)

long DragGrayRgn (
   RgnHandle theRgn,
   Point startPt,
   const Rect *limitRect,
   const Rect *slopRect,
   short axis,
   DragGrayRgnUPP actionProc
);

Parameters
theRgn

On input, a handle to the region to be dragged.

startPt

On input, the location, in the local coordinates of the current graphics port, of the cursor when the mouse button was pressed.

limitRect

On input, a pointer to a rectangle, given in the local coordinates of the current graphics port, that limits where the region can be dragged. This parameter works with the slopRect parameter.

slopRect

On input, a pointer to a rectangle, given in the local coordinates of the current graphics port, that gives the user some leeway in moving the mouse without violating the limits of the limitRect parameter. The slopRect rectangle should be larger than the limitRect rectangle.

axis

On input, a constant that constrains the region’s motion. The axis parameter can have one of three values: noConstraint (0), hAxisOnly (1), or vAxisOnly (2).

If an axis constraint is in effect, the outline follows the cursor’s movements along only the specified axis, ignoring motion along the other axis. With or without an axis constraint, the outline appears only when the mouse is inside the slopRect rectangle.

actionProc

On input, a pointer to a function that defines an action to be performed repeatedly as long as the user holds down the mouse button. The function can have no parameters. If the value of actionProc is null, DragGrayRgn simply retains control until the mouse button is released.

Return Value

A long integer that specifies the difference between the point where the mouse button was pressed and the offset point.

Discussion

The DragGrayRgn function is called by DragWindow to move an outline of a window around the screen as the user drags a window. It returns the difference between the point where the mouse button was pressed and the offset point (the point in the region whose horizontal and vertical offsets from the upper-left corner of the region’s enclosing rectangle are the same as the offsets of the starting point when the user pressed the mouse button. DragGrayRgn stores the vertical difference between the starting point and the offset point in the high-order word of the return value and the horizontal difference in the low-order word.

It limits the movement of the region according to constraints set by the limitRect and slopRect parameters:

The region stops moving when the offset point reaches the edge of the limitRect rectangle. The cursor continues to move, but the region does not.

If the mouse button is released while the cursor is anywhere inside the slopRect rectangle, the Window Manager redraws the window in its new location, which is calculated from the value returned by DragGrayRgn.

Carbon Porting Notes

Can’t be used for live dragging. If you are implementing your own window dragging, use DragWindow instead. If you need to override window positioning during a drag, register a Carbon event handler for kEventWindowBoundsChanging. Okay to use if you’re dragging objects within a window.

Availability
Declared In
MacWindows.h

DragTheRgn

Tracks the mouse as the user drags the outline of a region. (Deprecated in Mac OS X v10.5. Use an overlay window or other custom drawing instead.)

long DragTheRgn (
   RgnHandle theRgn,
   Point startPt,
   const Rect *limitRect,
   const Rect *slopRect,
   short axis,
   DragGrayRgnUPP actionProc
);

Carbon Porting Notes

Can’t be used for live dragging. If you are implementing your own window dragging, use DragWindow instead. If you need to override window positioning during a drag, register a Carbon event handler for kEventWindowBoundsChanging. Okay to use if you’re dragging objects within a window.

Availability
Declared In
MacWindows.h

DrawGrowIcon

Draws a grow icon in the window frame. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DrawGrowIcon (
   WindowRef window
);

Special Considerations

This function is not needed in Mac OS X. Theme-savvy windows include the grow box in the window frame.

Availability
Declared In
MacWindows.h

FrontWindow

Identifies the frontmost visible window. (Deprecated in Mac OS X v10.5. Use ActiveNonFloatingWindow, FrontNonFloatingWindow, or GetFrontWindowOfClass instead.)

WindowRef FrontWindow (
   void
);

Return Value

The first visible window in the window list. If there are no visible windows, FrontWindow returns NULL.

Discussion

Most applications should call ActiveNonFloatingWindow or FrontNonFloatingWindow instead of FrontWindow because ActiveNonFloatingWindow and FrontNonFloatingWindow return the active and frontmost document window, respectively, skipping over other types of windows that may be in front of the active document, such as the menubar window, floating windows, help tags and toolbars.

Availability
Related Sample Code
Declared In
MacWindows.h

GetGrayRgn

Returns a region that covers the desktop area of all active displays. (Deprecated in Mac OS X v10.5. To determine the area in which a window may be positioned, use HIWindowGetAvailablePositioningBounds or HIWindowCopyAvailablePositioningShape.)

RgnHandle GetGrayRgn (
   void
);

Return Value

A handle to the current desktop region from the global variable GrayRgn.

Discussion

When your application calls DragWindow to let the user drag a window, it can use GetGrayRgn to set the limiting rectangle to the entire desktop area. The desktop region represents all available screen space, that is, the desktop area displayed by all monitors attached to the computer.

Special Considerations

Your application should not modify the desktop region.

Availability
Related Sample Code
Declared In
MacWindows.h

GetNewCWindow

Creates a color window from a window resource. (Deprecated in Mac OS X v10.5. Use nib files and CreateWindowFromNib instead.)

WindowRef GetNewCWindow (
   short windowID,
   void *wStorage,
   WindowRef behind
);

Parameters
windowID

On input, the resource ID of the 'WIND' resource that defines the properties of the window.

wStorage

On input, a pointer to memory space for the window structure. If you specify a value of null for wStorage, the GetNewCWindow function allocates the window structure as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the memory your application needs for window structures early in your initialization code. Whenever you need to create a window, you can allocate memory from your own block and pass a pointer to it in the wStorage parameter.

behind

On input, a pointer to the window that appears immediately in front of the new window on the desktop. To place a new window in front of all other windows on the desktop, specify a value of (WindowRef)-1L. When you place a window in front of all others, GetNewCWindow removes the highlighting from the previously active window, highlights the newly created window, and generates the appropriate activate events. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).

To place a new window behind all other windows, specify a value of null.

Return Value

A pointer to the newly created window structure.

Discussion

The GetNewCWindow function creates a new color window from the specified window resource and returns a pointer to the newly created window structure. You can use the returned window pointer to refer to this window in most Window Manager functions. If GetNewCWindow is unable to read the window or window definition function from the resource file, it returns null.

The GetNewCWindow function looks for a 'wctb' resource with the same resource ID as that of the ' WIND ' resource. If it finds one, it uses the window color information in the ' wctb ' resource for coloring the window content area.

If the window’s definition function (specified in the window resource) is not already in memory, GetNewCWindow reads it into memory and stores a handle to it in the window structure.

To create the window, GetNewCWindow retrieves the window characteristics from the window resource and then calls the NewCWindow function, passing the characteristics as parameters.

The GetNewCWindow function creates a window in a color graphics port. Your application typically sets up its own global variables reflecting the system setup during initialization by calling the Gestalt function.

Special Considerations

If you must get your window definition from a resource, use CreateWindowFromResource. Otherwise, use CreateWindowFromNib or CreateNewWindow.

Availability
Declared In
MacWindows.h

GetNewWindow

Creates a window from a window resource. (Deprecated in Mac OS X v10.5. Use nib files and CreateWindowFromNib instead.)

WindowRef GetNewWindow (
   short windowID,
   void *wStorage,
   WindowRef behind
);

Parameters
windowID

On input, the resource ID of the 'WIND' resource that defines the properties of the window.

wStorage

On input, a pointer to memory space for the window structure. If you specify a value of null for wStorage, the GetNewWindow function allocates the window structure as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the memory your application needs for window structures early in your initialization code. Whenever you need to create a window, you can allocate memory from your own block and pass a pointer to it in the wStorage parameter.

behind

On input, a pointer to the window that appears immediately in front of the new window on the desktop. To place a new window in front of all other windows on the desktop, specify a value of (WindowRef)-1l. When you place a window in front of all others, GetNewWindow removes the highlighting from the previously active window, highlights the newly created window, and generates the appropriate activate events. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active). To place a new window behind all other windows, specify a value of null.

Return Value

A pointer to the newly created color window structure.

Discussion

The GetNewWindow function takes the same parameters as GetNewCWindow and returns a value of type WindowRef. The only difference is that it creates a monochrome graphics port, not a color graphics port, regardless of the presence of a corresponding ' wctb ' resource (it loads the resource but doesn’t use it). The window structure and graphics port structure that describe monochrome and color graphics ports are the same size and can be used interchangeably in most Window Manager functions.

The GetNewWindow function creates a new window from the specified window resource and returns a pointer to the newly created window structure. You can use the returned window pointer to refer to this window in most Window Manager functions. If GetNewWindow is unable to read the window or window definition function from the resource file, it returns null.

If the window’s definition function (specified in the window resource) is not already in memory, GetNewWindow reads it into memory and stores a handle to it in the window structure. It allocates space in the application heap for the structure and content regions of the window.

To create the window, GetNewWindow retrieves the window characteristics from the window resource and then calls the function NewWindow, passing the characteristics as parameters.

Special Considerations

If you must get your window definition from a resource, use CreateWindowFromResource. Otherwise, use CreateWindowFromNib or CreateNewWindow.

Version Notes

The GetNewWindow function was originally implemented prior to Color QuickDraw. In Mac OS 8, you should call the Color QuickDraw function GetNewCWindow instead of GetNewWindow to programmatically create a window, because Color QuickDraw is always available in Mac OS 8. Use of this function is not recommended with Mac OS 8 and later. GetNewWindow is described here only for completeness.

Availability
Declared In
MacWindows.h

GetWindowOwnerCount

Obtains the number of existing references to a window. (Deprecated in Mac OS X v10.5. Use CFGetRetainCount instead.)

OSStatus GetWindowOwnerCount (
   WindowRef window,
   ItemCount *outCount
);

Parameters
window

The window whose reference (owner) count is to be determined.

outCount

A pointer to a value that, on return, contains the current number of references to the window.

Return Value

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

Discussion

All windows are created with a reference count (owner count) of one. The function CloneWindow increments the number of references to a window, and the earlier function DisposeWindow decrements the number of references. When the reference count reaches zero, DisposeWindow disposes of the window.

In Mac OS X v10.2 and later, you can also call CFGetRetainCount to get the number of existing references to a window.

Availability
Declared In
MacWindows.h

GetWindowPic

Returns a handle to a window’s picture. (Deprecated in Mac OS X v10.5. Use an HIImageView object to draw a window's content and ask the view for its image instead.)

PicHandle GetWindowPic (
   WindowRef window
);

Parameters
window

The window whose picture handle is to be returned.

Return Value

A handle to the picture to be drawn in a specified window’s content region. The handle must have been stored previously with the function SetWindowPic.

Availability
Declared In
MacWindows.h

GetWindowProxyFSSpec

Obtains a file system specification structure for the file that is associated with a window. (Deprecated in Mac OS X v10.5. Use HIWindowGetProxyFSRef instead.)

OSStatus GetWindowProxyFSSpec (
   WindowRef window,
   FSSpec *outFile
);

Parameters
window

A pointer to the window for which you wish to determine the associated file.

outFile

On input, a pointer to an FSSpec structure. On return, this structure contains a copy of the file system specification data for the file associated with the specified window.

Return Value

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

Discussion

You can use the GetWindowProxyFSSpec function to obtain identifying information about a proxy file: its volume reference number, directory ID, and file name.

See also the function SetWindowProxyFSSpec.

Special Considerations

The use of file specification structures is no longer recommended.

Availability
Related Sample Code
Declared In
MacWindows.h

GetWindowRegion

Obtains a handle to a specific window region. (Deprecated in Mac OS X v10.5.)

OSStatus GetWindowRegion (
   WindowRef window,
   WindowRegionCode inRegionCode,
   RgnHandle ioWinRgn
);

Parameters
window

The window for which a window region handle is to be obtained.

inRegionCode

A constant representing the window region whose handle you want to obtain; see “Window Region Constants” for a list of possible values.

ioWinRgn

On input, a handle to a region created by your application. On return, the handle is set to the specified window region.

Return Value

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

Discussion

The GetWindowRegion function produces a handle to a window definition function’s window region in response to a kWindowMsgGetRegion message. The visibility of the window is unimportant for GetWindowRegion to work correctly.

Availability
See Also
Declared In
MacWindows.h

GetWindowRetainCount

Returns the retain count of a window. (Deprecated in Mac OS X v10.5. Use CFGetRetainCount instead.)

ItemCount GetWindowRetainCount (
   WindowRef inWindow
);

Parameters
inWindow

The window whose retain count to retrieve.

Discussion

This API is equivalent to GetWindowOwnerCount. For consistency with Core Foundation and Carbon Events, it is preferred over GetWindowOwnerCount. Both APIs will continue to be supported.

Availability
Declared In
MacWindows.h

GetWTitle

Retrieves the title of a window as a Pascal string. (Deprecated in Mac OS X v10.5. Use CopyWindowTitleAsCFString instead.)

void GetWTitle (
   WindowRef window,
   Str255 title
);

Parameters
window

On input, a pointer to the window structure.

title

A Pascal string. On output, the string contains the window title.

Discussion

The GetWTitle function returns the title of the window in the title parameter.

When you need to retrieve a window’s title, you should always use GetWTitle instead of reading the title from a window structure.

Availability
Declared In
MacWindows.h

GetWVariant

Returns a window’s variation code. (Deprecated in Mac OS X v10.5. Use GetWindowAttributes to determine aspects of a window's appearance or behavior.)

short GetWVariant (
   WindowRef window
);

Parameters
window

On input, a pointer to the window structure.

Return Value

A short integer that specifies the variation code of the specified window. Depending on the window definition function, the result of GetWVariant can represent one of the standard variation codes or a variation code defined by your own window definition function.

Availability
Declared In
MacWindows.h

GrowWindow

Allows the user to change the size of a window. (Deprecated in Mac OS X v10.5. Use ResizeWindow instead.)

long GrowWindow (
   WindowRef window,
   Point startPt,
   const Rect *bBox
);

Parameters
window

On input, a pointer to the window structure of the window to drag.

startPt

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

bBox

On input, a pointer to a rectangle structure that specifies the limits on the vertical and horizontal measurements of the port rectangle, in pixels.

Although the bBox parameter gives the address of a structure which is in the form of the Rect data type, the four numbers in the structure represent lengths, not screen coordinates. The top, left, bottom, and right fields of the bBox parameter specify the minimum vertical measurement (top), the minimum horizontal measurement (left), the maximum vertical measurement (bottom), and the maximum horizontal measurement (right).

The minimum measurements must be large enough to allow a manageable rectangle 64 pixels on a side is typical. Because the user cannot ordinarily move the cursor off the screen, you can safely set the upper bounds to the largest possible length (65,535 pixels) when you’re using GrowWindow to follow cursor movements.

Return Value

A long integer that specifies the new dimensions, in pixels, of the resulting window: the height in the high-order word of the returned long-integer value and the width in the low-order word. A return value of 0 means that the new size is the same as the size of the current port rectangle.

Discussion

The GrowWindow function displays an outline (grow image) of the window as the user moves the cursor to make the window larger or smaller; it handles all user interaction until the user releases the mouse button. After calling GrowWindow, you call the function SizeWindow to change the size of the window.

The GrowWindow function moves a dotted-line image of the window’s right and lower edges around the screen, following the movements of the cursor until the mouse button is released. You can use the functions HiWord and LoWord, described in the Mathematical and Logical Utilities Reference , to retrieve only the high-order and low-order words, respectively.

Special Considerations

In non-Carbon implementations of GrowWindow on Mac OS 8 and 9, the maximum size that the specified window is allowed to grow to is actually one less than the values specified in the bBox parameter. For example, if you pass the values 500 in the bBox.bottom field and 600 in the bBox.right field, the maximum height and width of the window would actually be 499 and 599, respectively.

However, in Carbon, the maximum height and width allowed for the specified window is equal to the values passed in the bBox.bottom and bBox.right fields, respectively.

Availability
Declared In
MacWindows.h

InstallWindowContentPaintProc

Installs a window content painting callback. (Deprecated in Mac OS X v10.5. Use a kEventControlDraw Carbon event handler on a window's content view instead.)

OSStatus InstallWindowContentPaintProc (
   WindowRef window,
   WindowPaintUPP paintProc,
   WindowPaintProcOptions options,
   void *refCon
);

Parameters
window

The window whose default content painting function you want to override.

paintProc

A UPP to your window painting callback function. See WindowPaintProcPtr for more information about the format of this function.

options

The options that are to be set. See “Window Paint Callback Options” for a list of possible values.

refCon

Application-defined data. This data is passed to your callback when it is called.

Return Value

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

Discussion

To remove a previously-installed paint proc (returning to the standard window manager erase-to-white content painting), pass NULL in the paintProc and refCon parameters.

Special Considerations

Instead of using this function, you should install a Carbon event handler for the kEventControlDraw event on a window's content view.

Availability
Declared In
MacWindows.h

InvokeWindowDefUPP

Invokes the UPP for a window definition. (Deprecated in Mac OS X v10.5. The WDEF interface is deprecated; use a custom HIView to draw your custom window frame instead.)

long InvokeWindowDefUPP (
   short varCode,
   WindowRef window,
   short message,
   long param,
   WindowDefUPP userUPP
);

Parameters
varCode

The window’s variation code.

window

The window whose UPP is to be invoked.

message

The message.

param

The parameter.

userUPP

The UPP to invoke.

Availability
Declared In
MacWindows.h

InvokeWindowPaintUPP

Invokes the UPP for the specified painting region. (Deprecated in Mac OS X v10.5. The window content painting interface is deprecated; use a kEventControlDraw Carbon event handler on a compositing window’s content view instead.)

OSStatus InvokeWindowPaintUPP (
   GDHandle device,
   GrafPtr qdContext,
   WindowRef window,
   RgnHandle inClientPaintRgn,
   RgnHandle outSystemPaintRgn,
   void *refCon,
   WindowPaintUPP userUPP
);

Parameters
device

The graphics device on which the window background should be painted.

qdContext

The QuickDraw port in which the window background should be painted.

window

The window whose UPP is to be invoked.

inClientPaintRgn

The region of the window background that needs to be painted, in local coordinates.

outSystemPaintRgn

On return, the region of the window background that the paint proc requests the Window Manager to paint.

refCon

Application-defined data.

userUPP

The UPP to invoke. For more information on this data type, see WindowPaintUPP.

Return Value

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

Availability
Declared In
MacWindows.h

IsWindowPathSelectClick

Reports whether a mouse click should activate the window path pop-up menu. (Deprecated in Mac OS X v10.5. Use IsWindowPathSelectEvent instead.)

Boolean IsWindowPathSelectClick (
   WindowRef window,
   const EventRecord *event
);

Parameters
window

The window in which the mouse-down event occurred.

event

A pointer to the EventRecord structure containing the mouse-down event that IsWindowPathSelectClick is to examine.

Return Value

A Boolean whose value is true f the mouse click should activate the window path pop-up menu; otherwise false.

Discussion

The Window Manager provides system support for your application to display window path pop-up menus, such as those used in Finder windows. When the user presses the Command key and clicks on the window’s title, the window displays a pop-up menu containing a standard file system path, informing the user of the location of the document displayed in the window and allowing the user to open windows for folders along the path.

Because the window title includes both the proxy icon region and part of the drag region of the window, your application must be prepared to respond to a click in either region by displaying a window path pop-up menu. Therefore, when the FindWindow function returns either the inDrag or the inProxyIcon result code—you should pass the event to the IsWindowPathSelectClick function to determine whether the mouse-down event should activate the window path pop-up menu. If IsWindowPathSelectClick returns a value of true, your application should then call the function WindowPathSelect to display the menu.

Availability
Declared In
MacWindows.h

NewCWindow

Creates a window with a specified list of characteristics. (Deprecated in Mac OS X v10.5. Use CreateNewWindow instead.)

WindowRef NewCWindow (
   void *wStorage,
   const Rect *boundsRect,
   ConstStr255Param title,
   Boolean visible,
   short procID,
   WindowRef behind,
   Boolean goAwayFlag,
   SRefCon refCon
);

Parameters
wStorage

On input, a pointer to the window structure. If you specify null as the value of wStorage, NewCWindow allocates the window structure as a nonrelocatable object in the application heap. You can reduce the chances of heap fragmentation by allocating memory from a block of memory reserved for this purpose by your application and passing a pointer to it in the wStorage parameter.

boundsRect

On input, a pointer to a rectangle, given in global coordinates, that specifies the window’s initial size and location. This rectangle becomes the port rectangle of the window’s graphics port. For the standard window types, the boundsRect field defines the content region of the window. The NewCWindow function places the origin of the local coordinate system at the upper-left corner of the port rectangle. NewCWindow calls the QuickDraw function OpenCPort to create the graphics port. The bitmap, pen pattern, and other characteristics of the window’s graphics port are the same as the default values set by OpenCPort, except for the character font, which is set to the application font instead of the system font.

title

On input, a pascal string that specifies the window’s title. If the title is too long to fit in the title bar, the title is truncated. To suppress the title in a window with a title bar, pass an empty string, not null, in the title parameter. null is an invalid value and may cause runtime errors.

visible

On input, a Boolean value indicating visibility status: true means that the Window Manager displays the window; false means it does not. If the value of the visible parameter is true, the Window Manager draws a new window as soon as the window exists. The Window Manager first calls the window definition function to draw the window frame. If the value of the goAwayFlag parameter is also true and the window is frontmost (that is, if the value of the behind parameter is (WindowRef)–1L), the Window Manager instructs the window definition function to draw a close box in the window frame. After drawing the frame, the Window Manager generates an update event to trigger your application’s drawing of the content region.

When you create a window, you typically specify false as the value of the visible parameter. When you’re ready to display the window, call ShowWindow.

procID

On input, the window’s definition ID, a value that specifies both the window definition function and the variation code within that definition function. For a list of possible values, see “Pre-Appearance Window Definition IDs”.

behind

On input, a pointer to the window that appears immediately in front of the new window on the desktop. To place a new window in front of all other windows on the desktop, specify a value of (WindowRef)–1L. When you place a new window in front of all others, NewCWindow removes highlighting from the previously active window, highlights the newly created window, and generates activate events that trigger your application’s updating of both windows. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).

To place a new window behind all other windows, specify a value of null.

goAwayFlag

On input, a Boolean value that determines whether the window has a close box. If the value of goAwayFlag is true and the window type supports a close box, the Window Manager draws a close box in the title bar and recognizes mouse clicks in the close region; if the value of goAwayFlag is false or the window type does not support a close box, it does not.

refCon

On input, a window’s reference constant, set and used only by your application.

Return Value

A pointer to the newly created window structure.

Discussion

The NewCWindow function creates a window as specified by its parameters, adds it to the window list, and returns a pointer to the newly created window structure. You can use the returned window pointer to refer to this window in most Window Manager functions. If NewCWindow is unable to read the window definition function from the resource file, it returns null.

The NewCWindow function looks for a ' wctb ' resource with the same resource ID as the ' WIND ' resource. If it finds one, it uses the window color information in the ' wctb ' resource for coloring the window content region.

If the window’s definition function is not already in memory, NewCWindow reads it into memory and stores a handle to it in the window structure. It allocates space for the structure and content regions of the window.

Storing the characteristics of your windows as resources, especially window titles and window items, makes your application easier to localize.

The NewCWindow function creates a window in a color graphics port. Creating color windows whenever possible ensures that your windows appear on color monitors with whatever color options the user has selected. Your application typically sets up its own set of global variables reflecting the system setup during initialization by calling the Gestalt function.

Special Considerations

If you let the Window Manager create the window structure in your application’s heap, call DisposeWindow to close the window and dispose of its window structure. If you allocated the memory for the window structure yourself and passed a pointer to NewCWindow, use the function CloseWindow to close the window and the appropriate disposal function (determined by how you have allocated memory) to dispose of the window structure.

Carbon Porting Notes

In Carbon, you cannot pass your own storage in to the wStorage parameter.

Carbon does not support custom window definitions stored in 'WDEF' resources. If you want to specify a custom window definition for NewCWindow, you must compile your definition function directly in your application and then register the function by calling RegisterWindowDefinition. When NewCWindow gets a procID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resource ID embedded in the procID parameter. It then calls that function to implement your window.

Availability
Declared In
MacWindows.h

NewWindow

Creates a window from a parameter list. (Deprecated in Mac OS X v10.5. Use CreateNewWindow instead.)

WindowRef NewWindow (
   void *wStorage,
   const Rect *boundsRect,
   ConstStr255Param title,
   Boolean visible,
   short theProc,
   WindowRef behind,
   Boolean goAwayFlag,
   SRefCon refCon
);

Parameters
wStorage

On input, a pointer to the window structure. If you specify null as the value of wStorage, NewWindow allocates the window structure as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the storage from a block of memory reserved for this purpose by your application and passing a pointer to it in the wStorage parameter.

boundsRect

On input, a pointer to a rectangle, given in global coordinates, which specifies the window’s initial size and location. This rectangle becomes the port rectangle of the window’s graphics port. For the standard window types, boundsRect defines the content region of the window. The NewWindow function places the origin of the local coordinate system at the upper-left corner of the port rectangle. NewWindow calls the QuickDraw function OpenPort to create the graphics port. The bitmap, pen pattern, and other characteristics of the window’s graphics port are the same as the default values set by OpenPort, except for the character font, which is set to the application font instead of the system font. The coordinates of the graphics port’s port boundaries and visible region are changed along with its port rectangle.

title

On input, a pascal string that specifies the window’s title. If the title is too long to fit in the title bar, the title is truncated. To suppress the title in a window with a title bar, pass an empty string, not null. null is an invalid value and may cause runtime errors.

visible

On input, a Boolean value indicating visibility status: true means that the Window Manager displays the window; false means it does not.

If the value of the visible parameter is true, the Window Manager draws a new window as soon as the window exists. The Window Manager first calls the window definition function to draw the window frame. If the value of the goAwayFlag parameter (described below) is also true and the window is frontmost (that is, if the value of the behind parameter is (WindowRef(–1L), the Window Manager instructs the window definition function to draw a close box in the window frame. After drawing the frame, the Window Manager generates an update event to trigger your application’s drawing of the content region.

When you create a window, you typically specify false as the value of the visible parameter. When you’re ready to display the window, you call the function ShowWindow.

theProc

On input, the window’s definition ID, which specifies both the window definition function and the variation code for that definition function. For a list of possible values, see “Pre-Appearance Window Definition IDs”.

behind

On input, a pointer to the window that appears immediately in front of the new window on the desktop. To place a new window in front of all other windows on the desktop, specify a value of (WindowRef)–1L. When you place a new window in front of all others, NewWindow removes highlighting from the previously active window, highlights the newly created window, and generates activate events that trigger your application’s updating of both windows. Note that if you create an invisible window in front of all others on the desktop, the user sees no active window until you make the new window visible (or make another window active).

To place a new window behind all other windows, specify a value of null.

goAwayFlag

On input, a Boolean value that determines whether or not the window has a close box. If the value of goAwayFlag is true and the window type supports a close box, the Window Manager draws a close box in the title bar and recognizes mouse clicks in the close region; if the value of goAwayFlag is false or the window type does not support a close box, it does not. The goAwayFlag parameter is ignored for movable modal or modal dialog boxes which do not support a close box.

refCon

On input, the window’s reference constant, set and used only by your application.

Discussion

The NewWindow function takes the same parameters as NewCWindow and returns a WindowRef as its function result. The only difference is that NewWindow creates a window in a monochrome graphics port, not a color graphics port. The window structure and graphics port structure that describe monochrome and color graphics ports are the same size and can be used interchangeably in most Window Manager functions.

The NewWindow function creates a window as specified by its parameters, adds it to the window list, and returns a pointer to the newly created window structure. You can use the returned window pointer to refer to this window in most Window Manager functions. If NewWindow is unable to read the window definition function from the resource file, it returns null.

If the window’s definition function is not already in memory, NewWindow reads it into memory and stores a handle to it in the window structure. It allocates space for the structure and content regions of the window.

Storing the characteristics of your windows as resources, especially window titles and window items, makes your application easier to localize.

Special Considerations

If you let the Window Manager create the window structure in your application’s heap, call DisposeWindow to close the window and dispose of its window structure. If you allocated the memory for the window structure yourself and passed a pointer to NewWindow, use the function CloseWindow to close the window and the appropriate disposal function (determined by how you have allocated memory) to dispose of the window structure.

Version Notes

The NewWindow function was originally implemented prior to Color QuickDraw. In Mac OS 8, you should call the Color QuickDraw function NewCWindow instead of NewWindow to programmatically create a window, because Color QuickDraw is always available in Mac OS 8. Use of this function is not recommended with Mac OS 8 and later. NewWindow is described here only for completeness.

Carbon Porting Notes

In Carbon, you cannot pass your own storage in to the wStorage parameter.

In Carbon, NewWindow is functionally equivalent to the NewCWindow, in that NewWindow returns a color window instead of a monochrome window.

Carbon does not support custom window definitions stored in 'WDEF' resources. If you want to specify a custom window definition for NewWindow, you must compile your definition function directly in your application and then register the function by calling RegisterWindowDefinition. When NewWindow gets a procID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resource ID embedded in the procID parameter. It then calls that function to implement your window.

Availability
Declared In
MacWindows.h

NewWindowDefUPP

Creates a new UPP for a window definition. (Deprecated in Mac OS X v10.5. The WDEF interface is deprecated; use a custom HIView to draw your custom window frame instead.)

WindowDefUPP NewWindowDefUPP (
   WindowDefProcPtr userRoutine
);

Parameters
userRoutine

For information, see WindowDefProcPtr.

Return Value

For a description of the WindowDefUPP data type, see WindowDefUPP.

Availability
Declared In
MacWindows.h

NewWindowPaintUPP

Creates a new UPP for a painting region. (Deprecated in Mac OS X v10.5. The window content painting interface is deprecated; use a kEventControlDraw Carbon event handler on a compositing window’s content view instead.)

WindowPaintUPP NewWindowPaintUPP (
   WindowPaintProcPtr userRoutine
);

Parameters
userRoutine

For information, see WindowPaintProcPtr.

Return Value

A UPP to the window paint function.

Availability
Declared In
MacWindows.h

PaintBehind

Redraws a series of windows in the window list. (Deprecated in Mac OS X v10.5. Use InvalWindowRect, InvalWindowRgn, or HIViewSetNeedsDisplay to invalidate a portion of a window.)

void PaintBehind (
   WindowRef startWindow,
   RgnHandle clobberedRgn
);

Parameters
startWindow

On input, a pointer to the window’s complete window structure.

clobberedRgn

On input, a handle to the region that has become invalid.

Discussion

The Window Manager calls the PaintBehind function; your application does not normally need to. PaintBehind calls PaintOne for startWindow and all the windows behind startWindow, clipped to clobberedRgn.

Special Considerations

Mac OS X applications never need to call this function.

Availability
Declared In
MacWindows.h

PaintOne

Redraws the invalid, exposed portions of one window on the desktop. (Deprecated in Mac OS X v10.5. Use InvalWindowRect, InvalWindowRgn, or HIViewSetNeedsDisplay to invalidate a portion of a window.)

void PaintOne (
   WindowRef window,
   RgnHandle clobberedRgn
);

Parameters
window

On input, a pointer to the window structure.

clobberedRgn

On input, a handle to the region that has become invalid.

Discussion

The Window Manager calls the PaintOne function; your application does not normally need to. PaintOne “paints” the invalid portion of the specified window and all windows above it. PaintOne draws as much of the window frame as is in clobberedRgn and, if some content region is exposed, erases the exposed area (paints it with the content pattern rather than the background pattern using SetWinColor or SetThemeWindowBackground) and adds it to the window’s update region.

If the value of the window parameter is null, the window is the desktop, and PaintOne paints it with the desktop pattern.

Special Considerations

Mac OS X applications never need to call this function.

Availability
Declared In
MacWindows.h

ReleaseQDContextForCollapsedWindowDockTile

Releases a port and other state created by CreateQDContextForCollapsedWindowDockTile. (Deprecated in Mac OS X v10.5. Use HIWindowReleaseCollapsedDockTileContext instead.)

OSStatus ReleaseQDContextForCollapsedWindowDockTile (
   WindowRef inWindow,
   CGrafPtr inContext
);

Parameters
inWindow

The window whose port is to be released.

inContext

The port that is to be released.

Return Value

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

Discussion

You must call this function instead of calling DisposePort directly, or you may leak system resources.

Availability
Related Sample Code
Declared In
MacWindows.h

ReleaseWindow

Decrements the retain count of a window, and destroys the window if the retain count falls to zero. (Deprecated in Mac OS X v10.5. Use CFRelease instead.)

OSStatus ReleaseWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window whose retain count is to be decremented.

Return Value

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

Discussion

This API is equivalent to DisposeWindow. For consistency with Core Foundation and Carbon Events, it is preferred over DisposeWindow. Both APIs will continue to be supported.

In Mac OS X v10.2 and later, you can also call CFRelease to decrement the retain count of a window.

Availability
Declared In
MacWindows.h

RetainWindow

Increments the retain count of a window. (Deprecated in Mac OS X v10.5. Use CFRetain instead.)

OSStatus RetainWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window whose retain count is to be incremented.

Return Value

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

Discussion

This API is equivalent to CloneWindow. For consistency with Core Foundation and Carbon Events, it is preferred over CloneWindow. Both APIs will continue to be supported.

In Mac OS X v10.2 and later, you can also call CFRetain to increment the retain count of a window.

Availability
Declared In
MacWindows.h

SetWindowClass

Sets the class of a window. (Deprecated in Mac OS X v10.5. Use HIWindowChangeClass, SetWindowGroup, or HIWindowChangeAttributes instead.)

OSStatus SetWindowClass (
   WindowRef inWindow,
   WindowClass inWindowClass
);

Parameters
window

The window whose class you want to set.

inClass

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

Return Value

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

Discussion

This function changes the class of a window. It also changes the window's z-order so that it is grouped with other windows of the same class. It does not change the visual appearance of the window.

Availability
Declared In
MacWindows.h

SetWindowPic

Sets a picture for the Window Manager to draw in a window’s content region. (Deprecated in Mac OS X v10.5. Use an HIImageView object to draw a window's content instead.)

void SetWindowPic (
   WindowRef window,
   PicHandle pic
);

Parameters
window

The window whose picture is to be set.

pic

On input, a handle to the picture to be drawn in the window.

Discussion

The SetWindowPic function stores in a window structure a handle to a picture to be drawn in the window. When the window’s content region must be updated, the Window Manager then draws the picture or part of the picture, as necessary, instead of generating an update event.

The DisposeWindow function assumes that any picture pointed to by the window structure field windowPic is stored as data, not as a resource. If your application uses a picture stored as a resource, you must release the memory it occupies by calling the Resource Manager’s ReleaseResource function and set the WindowPic field to NULL before you close the window.

Availability
Declared In
MacWindows.h

SetWindowProxyFSSpec

Associates a file with a window. (Deprecated in Mac OS X v10.5. Use HIWindowSetProxyFSRef instead.)

OSStatus SetWindowProxyFSSpec (
   WindowRef window,
   const FSSpec *inFile
);

Parameters
window

A pointer to the window with which the specified file is to be associated.

inFile

Set the file system specification structure to contain the data for the file to associate with the specified window. You can obtain an FSSpec structure by calling the function GetWindowProxyFSSpec.

Return Value

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

Discussion

Your application should call the SetWindowProxyFSSpec function to establish a proxy icon for a given window. The creator code and file type of the file associated with a window determine the proxy icon that is displayed for the window.

Because the SetWindowProxyFSSpec function won’t work without a saved file, you must establish the initial proxy icon for a new, untitled window with the function SetWindowProxyCreatorAndType , which requires that you know the file type and creator code for the file, but does not require that the file have been saved.

You must save and restore the current graphics port—by calling the QuickDraw functions GetPort and SetPort—around each call to the SetWindowProxyFSSpec function.

See also the function SetWindowProxyAlias.

Special Considerations

The use of file specifications is no longer recommended.

Availability
Related Sample Code
Declared In
MacWindows.h

SetWTitle

Specifies a window’s title. (Deprecated in Mac OS X v10.5. Use SetWindowTitleWithCFString instead.)

void SetWTitle (
   WindowRef window,
   ConstStr255Param title
);

Parameters
window

On input, a pointer to the window structure.

title

On input, a Pascal string containing the window title. To suppress the title in a window with a title bar, pass an empty string, not null.

Discussion

The SetWTitle function changes a window’s title to the specified string, both in the window structure and on the screen, and redraws the window’s frame as necessary. Always use SetWTitle instead of changing the title in a window structure.

When the user opens a previously saved document, you typically create a new (invisible) window with the title “untitled” and then call SetWTitle to give the window the document’s name before displaying it. You also call SetWTitle when the user saves a document under a new name.

Availability
Declared In
MacWindows.h

StoreWindowIntoCollection

Stores data describing a window into a collection. (Deprecated in Mac OS X v10.5. Use HIArchiveEncodeCFType to encode a window to an archive instead.)

OSStatus StoreWindowIntoCollection (
   WindowRef window,
   Collection collection
);

Parameters
window

The window to be stored.

collection

A reference to the collection into which the window is to be stored. You pass a reference to a previously created collection, such as that returned by the Collection Manager function NewCollection.

Return Value

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

Discussion

The StoreWindowIntoCollection function stores any window—including those not created by the Window Manager calls—into the specified collection. The Window Manager does not empty the collection beforehand, so any existing items in the collection remain.

Availability
Declared In
MacWindows.h

< Previous PageNext Page > Hide TOC

© 1995, 2003, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.