Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 4 - Window Manager / Window Manager Reference

Data Structures

The Color Window Record

The Window Manager maintains a window record or color window record for each window on the desktop.

The Window Manager supplies routines that let you access the window record as necessary. Your application seldom changes fields in the window record directly.

The CWindowRecord data type defines the window record for a color window. The CWindowPeek data type is a pointer to a color window record. The first field in
the window record is in fact the record that describes the window's graphics port. The CWindowPtr data type is defined as a pointer to the window's graphics port.

When Color QuickDraw is not available, you can create monochrome windows using the parallel data types WindowRecord, WindowPeek, and WindowPtr, described in the next section, "The Window Record."

For compatibility, the WindowPtr and WindowPeek data types can point to either a color window record or a monochrome window record. You use the WindowPtr data type to specify a window in most Window Manager routines, and you can use it to specify a graphics port in QuickDraw routines that take the GrafPtr data type. Note that you can access only the fields of the window's graphics port, not the rest of the window record, through the WindowPtr and CWindowPtr data types. You use the WindowPeek and CWindowPeek data types in low-level Window Manager routines
and in your own routines that access window record fields beyond the graphics port.

The routines that manipulate color windows get color information from the window color tables and the auxiliary window record described in the sections "The Window Color Table Record" on page 4-63 and "The Auxiliary Window Record" on page 4-66.

TYPE  CWindowPtr  = ^CGrafPtr; 
      CWindowPeek = ^CWindowRecord;
TYPE  CWindowRecord =
   RECORD
      port:          CGrafPort;     {window's graphics port}
      windowKind:    Integer;       {class of the window}
      visible:       Boolean;       {visibility}
      hilited:       Boolean;       {highlighting}
      goAwayFlag:    Boolean;       {presence of close box}
      spareFlag:     Boolean;       {presence of zoom box}
      strucRgn:      RgnHandle;     {handle to structure region}
      contRgn:       RgnHandle;     {handle to content region}
      updateRgn:     RgnHandle;     {handle to update region}
      windowDefProc: Handle;        {handle to window definition }
                                    { function}
      dataHandle:    Handle;        {handle to window state }
                                    { data record}
      titleHandle:   StringHandle;  {handle to window title}
      titleWidth:    Integer;       {title width in pixels}
      controlList:   ControlHandle; {handle to control list}
      nextWindow:    CWindowPeek;   {pointer to next window }
                                    { record in window list}
      windowPic:     PicHandle;     {handle to optional picture}
      refCon:        LongInt;       {storage available to your }
                                    { application}
   END;

Field Description

port

The graphics port record that describes the graphics port in which the window is drawn.

The graphics port record, which is documented in Inside Macintosh: Imaging, defines the rectangle in which drawing can occur, the window's visible region, the window's clipping region, and a collection of current drawing characteristics such as fill pattern, pen location, and pen size.

windowKind

The class of window--that is, how the window was created.

The Window Manager fills in this field when it creates the window record. It places a negative value in windowKind when the window


was created by a desk accessory. (The value is the reference ID of the desk accessory.) This field can also contain one of two constants:

               CONST
                  dialogKind  = 2;     {dialog or alert window}
                  userKind    = 8;     {window created by an }
                                       { application}

The value dialogKind identifies all dialog or alert box windows, whether created by the system software or, indirectly through the Dialog Manager, by your application. The Dialog Manager uses this field to help it track dialog and alert box windows.

The value userKind represents a window created directly by your application.

visible

A Boolean value indicating whether or not the window is visible. If the window is visible, the Window Manager sets this field to TRUE; if not, FALSE. Visibility means only whether or not the window is to be displayed, not necessarily whether you can see it on the screen. (For example, a window that is completely covered by other windows can still be visible, even if the user cannot see it on the screen.)

hilited

A Boolean value indicating whether the window is highlighted--that is, drawn with stripes in the title bar. Only the active window is ordinarily highlighted. When the window is highlighted, the hilited field contains TRUE; when not, FALSE.

goAwayFlag

A Boolean value indicating whether the window has a close box.

The Window Manager fills in this field when it creates the window according to the information in the 'WIND' resource or the parameters passed to the function that creates the window.

If the value of goAwayFlag is TRUE, and if the window type supports a close box, the Window Manager draws a close box when the window is highlighted.

spareFlag

A Boolean value indicating whether the window type supports zooming. The Window Manager sets this field to TRUE if the window's type is one that includes a zoom box (zoomDocProc, zoomNoGrow, or even modalDBoxProc + zoomDocProc).

strucRgn

A handle to the structure region, which is defined in global coordinates. The structure region is the entire screen area covered by the window--that is, both the window contents and the window frame.

contRgn

A handle to the content region, which is defined in global coordinates. The content region is the part of the window that contains the document, dialog, or other data; the window controls; and the size box.

updateRgn

A handle to the update region, which is defined in global coordinates. The update region is the portion of the window that must be redrawn. It is maintained jointly by the Window Manager and your application. The update region excludes parts of the window that are covered by other windows.

windowDefProc

A handle to the definition function that controls the window.

There's no need for your application to access this field directly.

In Macintosh models that use only 24-bit addressing, this field contains both a handle to the window's definition function and the window's variation code. If you need to know the variation code, regardless of the addressing mode, call the GetWVariant function.

dataHandle

Usually a handle to a data area used by the window definition function.

For zoomable windows, dataHandle contains a handle to the WStateData record, which contains the user state and standard state rectangles. The WStateData record is described in "The Window State Data Record" beginning on page 4-62.

A window definition function that needs only 4 bytes of data can use the dataHandle field directly, instead of storing a handle to the data. The window definition function that handles rounded-corner windows, for example, stores the diameters of curvature in the dataHandle field.

titleHandle

A handle to the string that defines the title of the window.

titleWidth

The width, in pixels, of the window's title.

controlList

A handle to the window's control list, which is used by the Control Manager. (See the chapter "Control Manager" in this book for a description of control lists.)

nextWindow

A pointer to the next window in the window list, that is, the window behind this window on the desktop. In the window record for the last window on the desktop, the nextWindow field is set
to NIL.

windowPic

A handle to a QuickDraw picture of the window's contents. The Window Manager initially sets the windowPic field to NIL. If you're using the window to display a stable image, you can use the SetWindowPic procedure to place a handle to the picture in this field. When the window's contents need updating, the Window Manager then redraws the contents itself instead of generating an update event.

refCon

The window's reference value field, which is simply storage
space available to your application for any purpose. The sample code in this chapter uses the refCon field to associate a window with the data it displays by storing a window type constant in
the refCon field of alert and dialog window records and a handle to a document record in the refCon field of a document
window record.

Note

The close box, drag region, zoom box, and size box are not included in the window record because they don't necessarily have the formal data structure for regions as defined in QuickDraw. The window definition function determines where these regions are.