Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 4 - Window Manager / Window Manager Reference

Window Manager Routines / Creating Windows

NewWindow

Use the NewWindow function to create a new window with the characteristics specified by a list of parameters when Color QuickDraw is not available. The NewWindow function takes the same parameters as NewCWindow and, like NewCWindow, returns a WindowPtr 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 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 NewWindow (wStorage: Ptr; boundsRect: Rect;
                     title: Str255; visible: Boolean;
                     theProc: Integer; behind: WindowPtr;
                     goAwayFlag: Boolean;
                     refCon: LongInt): WindowPtr;

wStorage

A pointer to the window record. If you specify NIL as the value of wStorage, NewWindow allocates the window record 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

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

Note

The NewWindow function actually calls the QuickDraw procedure 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

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 at the end of the title are truncated; 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.

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 (described below) 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.

theProc

The window's definition ID, which specifies both the window definition function and the variation code for 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 type 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}

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, 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 NIL.

goAwayFlag

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.

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 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 record. You can use the returned window pointer to refer to this window in most Window Manager routines. If NewWindow is unable to read the window definition function from the resource file, it returns NIL.

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

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.