Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 4 - Window Manager / Window Manager Reference

Window Manager Routines / Creating Windows

GetNewWindow

Use the GetNewWindow function to create a new window from a window resource
when Color QuickDraw is not available. The GetNewWindow function takes the same parameters as GetNewCWindow and returns a value of type WindowPtr. The only difference is that it creates a monochrome graphics port, not a color graphics port.
The window record and graphics port record that describe monochrome and color graphics ports are the same size and can be used interchangeably in most Window Manager routines.

FUNCTION GetNewWindow (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 GetNewWindow 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, 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 NIL.

DESCRIPTION

Like GetNewCWindow, GetNewWindow creates a new window from a window resource, but it creates a monochrome window. The GetNewWindow function creates a new 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 GetNewWindow is unable to read the window or window definition function from the resource file, it returns NIL.

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 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, GetNewWindow retrieves the window characteristics from the window resource and then calls the function NewWindow, passing the characteristics
as parameters.

SPECIAL CONSIDERATIONS

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 GetNewWindow, 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

For more information about window characteristics and the window resource, see the description of NewWindow beginning on page 4-75 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.