Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 4 - Window Manager / Window Manager Reference

Window Manager Routines / Creating Windows

NewCWindow
You can use the NewCWindow function to create a window with a specified list of characteristics.
FUNCTION NewCWindow (wStorage: Ptr; boundsRect: Rect;
                     title: Str255; visible: Boolean;
                     procID: Integer; behind: WindowPtr;
                     goAwayFlag: Boolean;
                     refCon: LongInt): WindowPtr;
wStorage
A pointer to the window record. If you specify NIL as the value of wStorage, NewCWindow allocates the window record 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
A rectangle, in global coordinates, specifying the window's initial size and location. This parameter 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.
Note
The NewCWindow function actually calls the QuickDraw procedure 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
A string that specifies the window's title.

If the title is too long to fit in the title bar, the title is truncated. If the window has a close box, characters are truncated at the end of the title; if there's no close box, the title is centered and truncated at both ends.

To suppress the title in a window with a title bar, pass an empty string, not NIL, in the title parameter.
visible
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 Pointer(-1)), 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 ShowWindow procedure, described on page 4-80.
procID
The window's definition ID, which specifies both the window definition function and the variation code within that definition function.

The Window Manager supports nine standard window types, which
are handled by two window definition functions. You can create windows of the standard types by specifying one of the window definition ID constants:
            CONST
               documentProc      = 0;  {standard document }
                                       { window, no zoom box}
               dBoxProc          = 1;  {alert box or modal }
                                       { dialog box}
               plainDBox         = 2;  {plain box}
               altDBoxProc       = 3;  {plain box with shadow}
               noGrowDocProc     = 4;  {movable window, }
                                       { no size box or zoom box}
               movableDBoxProc   = 5;  {movable modal dialog box}
               zoomDocProc       = 8;  {standard document window}
               zoomNoGrow        = 12; {zoomable, nonresizable }
                                       { window}
               rDocProc          = 16; {rounded-corner window}
For a description of the nine standard window types, see "Types of Windows" beginning on page 4-8.

You can control the diameter of curvature of rounded-corner windows by adding an integer to the rDocProc constant, as described in "The Window Resource" beginning on page 4-116.
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 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 NIL.
goAwayFlag
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
The window's reference constant, set and used only by your application. (See "Managing Multiple Windows" beginning on page 4-23 for some suggested ways to use the refCon parameter.)

DESCRIPTION
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 record. You can use the returned window pointer to refer to this window in most Window Manager routines. If NewCWindow is unable to read the window definition function from the resource file, it returns NIL.
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 frame and highlighting.
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 record. It allocates space for the structure and content regions of the window and asks the window definition function
to calculate those regions.
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. Before calling GetNewCWindow, verify that Color QuickDraw is available. Your application typically sets up its own set of global variables reflecting the system setup during initialization by calling the Gestalt function.
Note that the function NewCWindow returns a value of type WindowPtr, not CWindowPtr.

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

SEE ALSO
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.