Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 4 - Window Manager / Window Manager Reference

Window Manager Routines / Creating Windows

GetNewCWindow

Use the GetNewCWindow function to create a color window with the properties defined in the 'WIND' resource with a specified resource ID.

FUNCTION GetNewCWindow (windowID: Integer; wStorage: Ptr;
                        behind: WindowPtr): WindowPtr;

windowID

The resource ID of the 'WIND' resource that defines the properties of
the window.

wStorage

A pointer to memory space for the window record.

If you specify a value of NIL for wStorage, the GetNewCWindow function allocates the window record as a nonrelocatable object in the heap. You can reduce the chances of heap fragmentation by allocating the memory your application needs for window records 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

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 Pointer(-1). 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 NIL.

DESCRIPTION

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

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 frame and highlighting selected text.

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 record. It allocates space in the application heap for the structure and content regions of the window and asks the window definition function to calculate those regions.

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. Before calling GetNewCWindow, verify that Color QuickDraw is available. Your application typically sets up its own global variables reflecting the system setup during initialization by calling the Gestalt function.

SPECIAL CONSIDERATIONS

Note that the GetNewCWindow function returns a value of type WindowPtr, not CWindowPtr.

If you let the Window Manager create the window record in your application's heap, call DisposeWindow to dispose of the window's window record. If you allocated the memory for the window record yourself and passed a pointer to the storage to GetNewCWindow, use the procedure CloseWindow to close the window and the procedure DisposePtr, documented in Inside Macintosh: Memory, to dispose of the window record.

SEE ALSO

See Listing 4-3 on page 4-28 for an example that calls GetNewCWindow to create a new window from a window resource.

For more information about window characteristics and the window resource, see the description of NewCWindow beginning on page 4-72 and the description of the 'WIND' resource in the section "The Window Resource" beginning on page 4-116.

For the procedures for closing a window and removing the structures from memory, see the descriptions of the DisposeWindow procedure on page 4-97, the CloseWindow procedure on page 4-96, and the DisposePtr procedure in Inside Macintosh: Memory. See Listing 4-17 on page 4-61 for an example of closing a document window.