Legacy Documentclose button

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

Previous Book Contents Book Index Next

Inside Macintosh: Macintosh Toolbox Essentials /
Chapter 4 - Window Manager / Window Manager Reference
Application-Defined Routine / The Window Definition Function

MyWindow

The window definition function is responsible for drawing the window frame, reporting the region where mouse-down events occur, calculating the window's structure region and content region, drawing the size box, resizing the window frame when the user drags the size box, and performing any customized initialization or disposal tasks.

You can give your window definition function any name you wish. It takes four parameters and returns a result code:

FUNCTION MyWindow (varCode: Integer; theWindow: WindowPtr; 
                     message: Integer; param: LongInt): LongInt;
varCode
The window's variation code.
theWindow
A pointer to the window's window record.
message
A code for the task to be performed. The message parameter has one of these values: 
            CONST
               wDraw       = 0;  {draw window frame}
               wHit        = 1;  {report where mouse-down event }
                                 { occurred}
               wCalcRgns   = 2;  {calculate strucRgn and contRgn}
               wNew        = 3;  {perform additional }
                                 { initialization}
               wDispose    = 4;  {perform additional disposal }
                                 { tasks}
               wGrow       = 5;  {draw grow image during resizing}
               wDrawGIcon  = 6;  {draw size box and scroll bar }
                                 { outline}
The subsections that follow explain each of these tasks in detail.
param
Data associated with the task specified by the message parameter. If the task requires no data, this parameter is ignored.
Your window definition function performs whatever task is specified by the message parameter and returns a function result if appropriate. If the task performed requires no result code, return 0.

The function's entry point must be at the beginning of the function.

You can set up the various tasks as subroutines inside the window definition function, but you're not required to do so.

Drawing the Window Frame

When you receive a wDraw message, draw the window frame in the current graphics port, which is the Window Manager port.

You must make certain checks to determine exactly how to draw the frame. If the value of the visible field in the window record is FALSE, you should do nothing; otherwise, you should examine the param parameter and the status flags in the window record:

Note
When the Window Manager calls a window definition function
with a message of wDraw, it stores a value of type Integer in the param parameter without clearing the high-order word. When processing the wDraw message, use only the low-order word of the param parameter.
The window frame typically but not necessarily includes the window's title, which should be displayed in the system font and system font size. The Window Manager
port is already set to use the system font and system font size.

When designing a title bar that includes the window title, allow at least 16 pixels vertically to support localization for script systems in which the system font can be no smaller than 12 points.

Note
Nothing drawn outside the window's structure region is visible.

Returning the Region of a Mouse-Down Event

When you receive a wHit message, you must determine where the cursor was when the mouse button was pressed. The wHit message is accompanied by the mouse location, in global coordinates, in the param parameter. The vertical coordinate is in the high-order word of the parameter, and the horizontal coordinate is in the low-order word. You return one of these constants:

CONST
   wNoHit      = 0;  {none of the following}
   wInContent  = 1;  {in content region (except grow, if active)}
   wInDrag     = 2;  {in drag region}
   wInGrow     = 3;  {in grow region (active window only)}
   wInGoAway   = 4;  {in go-away region (active window only)}
   wInZoomIn   = 5;  {in zoom box for zooming in (active window }
                     { only)}
   wInZoomOut  = 6;  {in zoom box for zooming out (active window }
                     { only)}
The return value wNoHit might mean (but not necessarily) that the point isn't in the window. The standard window definition functions, for example, return wNoHit if the point is in the window frame but not in the title bar.

Return the constants wInGrow, wInGoAway, wInZoomIn, and wInZoomOut only if the window is active--by convention, the size box, close box, and zoom box aren't drawn if the window is inactive. In an inactive document window, for example, a mouse-down event in the part of the title bar that would contain the close box if the window were active is reported as wInDrag.

Calculating Regions

When you receive the wCalcRgns message, you calculate the window's structure and content regions based on the current graphics port's port rectangle. These regions, whose handles are in the strucRgn and contRgn fields of the window record, are in global coordinates. The Window Manager requests this operation only if the window is visible.

WARNING
When you calculate regions for your own type of window, do not alter the clip region or the visible region of the window's graphics port. The Window Manager and QuickDraw take care of this for you. Altering the clip region or visible region may damage other windows.

Initializing a New Window

When you receive the wNew message, you can perform any type-specific initialization that may be required. If the content region has an unusual shape, for example, you might allocate memory for the region and store the region handle in the dataHandle field of the window record. The initialization routine for a standard document window creates the wStateData record for storing zooming data.

Disposing of a Window

When you receive the wDispose message, you can perform any additional tasks necessary for disposing of a window. You might, for example, release memory that was allocated by the initialization routine. The dispose routine for a standard document window disposes of the wStateData record.

Resizing a Window

When you receive the wGrow message, draw a grow image of the window. With the wGrow message you receive a pointer to a rectangle, in global coordinates, whose upper-left corner is aligned with the port rectangle of the window's graphics port. Your grow image should fit inside the rectangle. As the user drags the mouse, the Window Manager sends repeated wGrow messages, so that you can change your grow image to match the changing mouse location.

Draw the grow image in the current graphics port, which is the Window Manager port, in the current pen pattern and pen mode. These are set up (as gray and notPatXor) to conform to the Macintosh user interface guidelines.

The grow routine for a standard document window draws a dotted (gray) outline of the window and also the lines delimiting the title bar, size box, and scroll bar areas.

Drawing the Size Box

When you receive the wDrawGIcon message, you draw the size box in the content region if the window is active--if the window is inactive, draw whatever is appropriate to show that the window cannot currently be sized.

Note
If the size box is located in the window frame instead of the content region, do nothing in response to the wDrawGIcon message, instead drawing the size box in response to the wDraw message.
The routine that draws a size box for an active document window draws the size box in the lower-right corner of the port rectangle of the window's graphics port. It also draws lines delimiting the size box and scroll bar areas. For an inactive document window, it erases the size box and draws the delimiting lines.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
11 JUL 1996