THE ZEN OF WINDOW ZOOMING

DEAN YU

Window zooming is a feature of the Macintosh user interface that's rarely implemented correctly. Because a lot of calculation and pixel-tweaking is required toachieve the "perfect" window zoom, few applications go through the effort to properlyzoom their document windows. This article discusses proper zooming etiquette andprovides a routine that deals with all the details of zooming windows.

About once a year, I go on a tirade about how few programs zoom their windows properly. Most programs zoom to the full size of the main screen; other applications make the window only as big as they need to but still move it to the main screen, even if the window is on another screen. The System 7 Finder comes close to making me happy, but every once in a while it zips a window to the main screen for reasons known only to the Finder engineers.

As I was writing some application code recently, I took the opportunity to make it zoom windows the way I wish all other programs would zoom windows. The resulting code (which is on this issue's CD) is the basis for this article. The zooming behavior that this code implements reflects all the documentation Apple has ever published about window zooming, from the old Human Interface notes to the Window Manager chapter inInside Macintosh: Macintosh Toolbox Essentials .

THE ETIQUETTE OF ZOOMING

First let's look at the subtle effects of a user's actions on how a window should be zoomed. After some basic definitions, we'll go over a few rules that govern zooming behavior. If you couldn't care less about these preliminaries, you can skip to the section "The Zooming Code" (however, if you do this, you'll hurt the author's feelings, since he spent a perfect Saturday afternoon indoors to write this article).

THE STATES OF A WINDOW
A window is zoomed between two states, theuser state  and the standard state . The user state is any size and position in which the user can place the window on the desktop. The Window Manager updates the user state when it calls a WDEF to recalculate a window's regions.

The standard state of a window is defined to be the size that can best display the data contained in the window. For example, in word processing applications the standard state of a document window would most likely be the size of a printed page. For some types of windows the standard state depends on the window's contents and so is determined dynamically by the application when the user zooms the window. In the Finder, for instance, the standard state of a window in an icon view would be the smallest size that can display all the icons in that window. The position of a window in its standard state varies depending on the position of the user state when the window was zoomed and on other factors, as explained later.

Figure 1 shows the user state and standard state of a Finder window displayed in the "small icon" view.

Figure 1 The User and Standard States of a Window

RULES OF THE ROAD
In addition, there are a few rules that govern how a window should be zoomed in different situations. These rules can be divided into two categories: rules on size and rules on position.

Rules on size. Although the standard state of a window is defined to be the best size for displaying the window's contents, this state is actually constrained by the size of the screen to which the window is being zoomed. If the ideal size for the standard state is larger than the destination screen, the window should be pinned to the size of the screen, minus some slop pixels. For example, Figure 2 shows the height of the standard state being pinned on the main screen. (Note that space was also left for the menu bar.)

If a window is being zoomed to the main screen and the ideal size for the standard state would take up the entire width of the screen, a strip of space should be left on the right side of the screen to let the first column of Finder icons show through.

Figure 2 Pinning to the Screen Size

Rules on position. The basic guideline for positioning a window during a zoom is that the window should move as little as possible, to avoid distracting the user.

A window in its standard state should be positioned so that it's entirely on one screen. If a window straddles more than one screen in the user state and is subsequently zoomed to the standard state, it should be zoomed to the screen that contains the largest portion of the window's content region. (See Figure 3.)When a window is zoomed from the user state to the standard state, it should be anchored at its current top left corner if possible. If the standard state size will fit on the screen without moving the window, the window can simply be resized. If the standard state of the window cannot fit with the top left corner anchored, the window should be "nudged" so that the parts that were off the screen fall just on screen. (See Figure 4.)

THE ZOOMING CODE

This section goes through the window zooming code chunk by chunk, discussing the logic behind each step.

ZoomTheWindow is the entry point to the window zooming code. It determines the best screen to zoom the window to, and nudges the window into position in case part of it falls off the edge of the screen. Applications should call this routine instead of calling the Toolbox routine ZoomWindow directly.

Figure 3Zooming to the Best Screen

Figure 4 Nudge Zooming

ZoomTheWindow has the following prototype:

void ZoomTheWindow(WindowPeek theWindow, short zoomState,
            CalcIdealDocumentSizeProcPtr calcRoutine);

The first two parameters, theWindow and zoomState, are identical to the first two parameters of ZoomWindow. The last parameter, calcRoutine, is an application-supplied callback routine that calculates the ideal size for the window without taking the user's screen configuration into consideration. The prototype of the CalcIdealDocumentSizeProcPtr function type is as follows:

typedef void (*CalcIdealDocumentSizeProcPtr)
            (WindowPtr theWindow, Rect *idealContentSize);

Given the window to be zoomed, the callback routine returns (in local coordinates) the ideal rectangle for the window in the idealContentSize parameter. The window will be the current graphics port when the callback routine is invoked.

ZoomTheWindow calls two utility routines, CalculateWindowAreaOnScreen and CalculateOffsetAmount. CalculateWindowAreaOnScreen calculates the area of a window on a screen. The screen that contains the largest portion of the window is the screen that the window will be zoomed to. If ZoomTheWindow determines that anchoring the window at its current top left corner will result in part of the window lying off the screen, it calls CalculateOffsetAmount to find out how many pixels the window needs to be nudged so that it's entirely on the screen. These utility routines are described in detail following the discussion of ZoomTheWindow below.

THE ZOOMDATA STRUCTURE
The ZoomData structure is used by ZoomTheWindow to hold information about the screen the window should be zoomed to. ZoomTheWindow uses DeviceLoop to find the screen containing the largest portion of the window. The DeviceLoop drawing procedure updates the ZoomData structure as DeviceLoop calls it for each active screen device.

struct ZoomData {
    GDHandle    screenWithLargestPartOfWindow;
    unsigned    long largestArea;
    Rect        windowBounds;
};
typedef struct ZoomData ZoomData, *ZoomDataPtr;

The screenWithLargestPartOfWindow field is a handle to the screen device that the window should be zoomed to. The largestArea field holds the area of the largest portion of the window encounteredso far, as DeviceLoop iterates through the screens. The windowBounds field is the portion of the window that's currently visible on the desktop.

THE ZOOMTHEWINDOW ROUTINE
About 90% of the code in ZoomTheWindow executes only when the window is to be zoomed to the standard state. The routine starts by setting up the current graphics port and getting some frequently used fields out of the window record.

void ZoomTheWindow(WindowPeek theWindow, short zoomState,
                    CalcIdealDocumentSizeProcPtr calcRoutine)
{
    ZoomData    zoomData;
    Rect        newStandardRect, scratchRect, screenRect, portRect;
    Rect        contentRegionBoundingBox, structureRegionBoundingBox;
    Rect        deviceLoopRect;
    GrafPtr     currentPort;
    RgnHandle   scratchRegion, contentRegion, structureRegion;
    GDHandle    mainDevice;
    short       horizontalAmountOffScreen, verticalAmountOffScreen;
    short       windowFrameTopSize, windowFrameLeftSize;
    short       windowFrameRightSize, windowFrameBottomSize;

    GetPort(&currentPort);
    SetPort((WindowPtr) theWindow);
    contentRegion = GetWindowContentRegion(theWindow);
    structureRegion = GetWindowStructureRegion(theWindow);
    GetWindowPortRect(theWindow, &portRect);
    contentRegionBoundingBox = (**contentRegion).rgnBBox;
    structureRegionBoundingBox = (**structureRegion).rgnBBox;
    windowFrameTopSize = contentRegionBoundingBox.top - 
                            structureRegionBoundingBox.top;
    windowFrameLeftSize = contentRegionBoundingBox.left - 
                            structureRegionBoundingBox.left;
    windowFrameRightSize = structureRegionBoundingBox.right - 
                            contentRegionBoundingBox.right;
    windowFrameBottomSize = structureRegionBoundingBox.bottom - 
                            contentRegionBoundingBox.bottom;

Determining the proper screen. The code then determines which screen contains the largest portion of the window, as follows:

// If the window is being zoomed to the standard state, calculate the
// best size to display the window's information.
mainDevice = GetMainDevice();
if (zoomState == inZoomOut) {
    zoomData.screenWithLargestPartOfWindow = mainDevice;
    zoomData.largestArea = 0;
    
    // Get the portion of the window that's on the desktop. 
    scratchRegion = NewRgn();
    SectRgn(GetGrayRgn(), contentRegion, scratchRegion);
    if (EmptyRgn(scratchRegion))
        zoomData.windowBounds = structureRegionBoundingBox;
    else
        zoomData.windowBounds = contentRegionBoundingBox;
    
    // Use DeviceLoop to walk through all the active screens to find
    // the one with the largest portion of the zoomed window.
    deviceLoopRect = zoomData.windowBounds;
    GlobalToLocal((Point *)&deviceLoopRect);
    GlobalToLocal((Point *)&deviceLoopRect.bottom);
    RectRgn(scratchRegion, &deviceLoopRect);
    DeviceLoop(scratchRegion, &CalcWindowAreaOnScreen,
         (long) &zoomData, (DeviceLoopFlags) singleDevices);
    DisposeRgn(scratchRegion);
    screenRect = (**(zoomData.screenWithLargestPartOfWindow)).gdRect;
    
    // If the window will be zoomed to the main screen, change the
    // top of the usable screen area so that the window's title bar
    // won't be placed under the menu bar.
    if (zoomData.screenWithLargestPartOfWindow == mainDevice)
        screenRect.top += GetMBarHeight();

ZoomTheWindow sets up default values in the ZoomData structure so that the window will zoom to the main screen by default. Normally, the content area of the window is used to determine the area of the window that's on each screen. However, if the user has the window positioned such that only the title bar (or a portion of the title bar) is visible on the desktop, the structure region of the window is used to determine the screen that contains the largest portion of the title bar.

One of the little-known facts about the universe is that inspiration actually comes from subatomic particles flying around in deep space. These particles occasionally hit a sentient brain, resulting in a flash of inspiration. One of these events resulted in the use of DeviceLoop to iterate through the list of active screen devices. (Of course, this means that the zooming code requires System 7; for a System 6 alternative to DeviceLoop, see "Graphical Truffles: Multiple Screens Revealed" indevelop Issue 10.) The CalcWindowAreaOnScreen routine is the DeviceLoop drawing procedure. The ZoomData structure is passed to DeviceLoop as the userData value, and the DeviceLoop flags are set so that DeviceLoop will call its drawing procedure for each screen device.

Determining the ideal size for the window. After determining the proper screen to zoom to, the application's callback routine is called to get back the ideal content size for the window. This rectangle is then anchored at the window's current top left corner and expanded to include the window frame.

 
    // Figure out the perfect size for the window as if we had an
    // infinitely large screen.
    (*calcRoutine)((WindowPtr) theWindow, &newStandardRect);
    
    // Anchor the new rectangle at the current top left corner of the
    // window.
    OffsetRect(&newStandardRect, -newStandardRect.left,
                -newStandardRect.top);
    OffsetRect(&newStandardRect, contentRegionBoundingBox.left,
                contentRegionBoundingBox.top);
    
    // Add the window frame to the ideal content rect.
    newStandardRect.top -= windowFrameTopSize;
    newStandardRect.left -= windowFrameLeftSize;
    newStandardRect.right += windowFrameRightSize;
    newStandardRect.bottom += windowFrameBottomSize;

Fitting the ideal size onto the screen. This is the tedious part of the code. At this point, newStandardRect holds the ideal size for the window being zoomed. Since a window in its standard state must be entirely on one screen, we ensure that the window fits on the screen, maintaining its ideal size if possible.

 
    // If the new rectangle falls off the edge of the screen, nudge it
    // so that it's just on the screen. CalculateOffsetAmount
    // determines how much of the window is off the screen.
    SectRect(&newStandardRect, &screenRect, &scratchRect); 
    if (!EqualRect(&newStandardRect, &scratchRect)) {
        horizontalAmountOffScreen = CalculateOffsetAmount(
                            newStandardRect.left,
                            newStandardRect.right,
                            scratchRect.left, scratchRect.right,
                            screenRect.left, screenRect.right);
        verticalAmountOffScreen = CalculateOffsetAmount(
                            newStandardRect.top,
                            newStandardRect.bottom,
                            scratchRect.top, scratchRect.bottom,
                            screenRect.top, screenRect.bottom);
        OffsetRect(&newStandardRect, horizontalAmountOffScreen,
                            verticalAmountOffScreen);
    }
        
    // If we're still falling off the edge of the screen, the perfect
    // size is larger than the screen, so shrink the standard size.
    SectRect(&newStandardRect, &screenRect, &scratchRect);
    if (!EqualRect(&newStandardRect, &scratchRect)) {
    // First shrink the width. If the window is wider than the screen
    // it's being zoomed to, just pin the standard rectangle to the
    // edges of the screen, leaving some slop; otherwise, we know we 
    // just nudged the window into position, so do nothing.
        if ((newStandardRect.right - newStandardRect.left) >
                (screenRect.right - screenRect.left)) {
            newStandardRect.left = screenRect.left + kNudgeSlop;
            newStandardRect.right = screenRect.right - kNudgeSlop;
        
            if ((zoomData.screenWithLargestPartOfWindow == 
                    mainDevice) &&
                (newStandardRect.right >
                   (screenRect.right - kIconSpace)))
                newStandardRect.right =
                    screenRect.right - kIconSpace;
        }
    
    // Move in the top of the window. As with the width of the 
    // window, do nothing unless the window is taller than the 
    // height of the screen.
    if ((newStandardRect.bottom - newStandardRect.top) >
            (screenRect.bottom - screenRect.top)) {
        newStandardRect.top = screenRect.top + kNudgeSlop;
        newStandardRect.bottom = screenRect.bottom - kNudgeSlop;
        }
    }

    // We've got the best possible window position. Remove the
    // frame, slam it into the WStateData record and let ZoomWindow
    // take care of the rest.
    newStandardRect.top += windowFrameTopSize;
    newStandardRect.left += windowFrameLeftSize;
    newStandardRect.right -= windowFrameRightSize;
    newStandardRect.bottom -= windowFrameBottomSize;
    SetWindowStandardState(theWindow, &newStandardRect);
} // if (zoomState == inZoomOut)
else
    GetWindowUserState(theWindow, &newStandardRect);

We call CalculateOffsetAmount to determine how much to nudge the window if it falls off the edge of the screen in its ideal size. After nudging the window, we double check to see if the window is entirely on the screen. If it still isn't, that means that the ideal size of the window is larger than the screen that it's zooming to, so the window has to be shrunk to fit on the screen. The code shrinks the window so that there's a small area of slop space between the edge of the window and the screen boundary. Additionally, if the screen that the window is zooming to is the main screen, space is left for the menu bar and a column of Finder icons. After all that, newStandardRect contains the best size for the window for that screen. After we remove the window frame, the stdState field of the WStateData record can be filled with this rectangle.

There's also the simple case of zooming to the user state. Since the Window Manager takes care of keeping the userState field of the WStateData record up to date, that rectangle is easy to get.

Zooming the window. Finally, all that's left to do is to actually zoom the window. One final optimization that can be performed is that if the top left corner of the window hasn't moved, SizeWindow can be called instead of ZoomWindow, reducing the amount of redrawing that needs to be done. The window's clipping region is reset to be the size of the window to ensure that the window's contents are entirely erased before ZoomWindow is called.

    // If the window is still anchored at the current top left corner,
    // just resize it.
    if ((newStandardRect.left == contentRegionBoundingBox.left) &&
            (newStandardRect.top == contentRegionBoundingBox.top)) {
        OffsetRect(&newStandardRect, -newStandardRect.left,
                    -newStandardRect.top);
        SizeWindow((WindowPtr) theWindow, newStandardRect.right,
                    newStandardRect.bottom, true);
    }
    else {
        scratchRegion = NewRgn();
        GetClip(scratchRegion);
        ClipRect(&portRect);
        EraseRect(&portRect);
        ZoomWindow((WindowPtr) theWindow, zoomState, false);
        SetClip(scratchRegion);
        DisposeRgn(scratchRegion);
    }
    SetPort(currentPort);
}

THE CALCWINDOWAREAONSCREEN ROUTINE
CalcWindowAreaOnScreen, the DeviceLoop drawing procedure for the zooming code, doesn't actually do any drawing, but instead simply calculates the area of the window that's on a screen. If there's more content area on one screen than any of the other screens that have been encountered so far, CalcWindowAreaOnScreen saves the GDHandle of this screen in the ZoomData structure as the potential screen to zoom the window to.

pascal void CalcWindowAreaOnScreen(short depth, short deviceFlags,
GDHandle targetDevice, long userData)
{
#pragma unused (depth, deviceFlags)
    ZoomDataPtr     zoomData = (ZoomDataPtr) userData;
    unsigned long   windowAreaOnScreen;
    Rect            windowPortionOnScreen;
    
    // Find the rectangle that encloses the intersection of the
    // screen and the document window.
    SectRect(&(zoomData->windowBounds), &((**targetDevice).gdRect),
    &windowPortionOnScreen);
    
    // Offset this rectangle so that its right and bottom are also
    // its width and height.
    OffsetRect(&windowPortionOnScreen, -windowPortionOnScreen.left,
                -windowPortionOnScreen.top); 

    // Calculate the area of the part of the window that is on this 
    // screen.
    windowAreaOnScreen = windowPortionOnScreen.right *
    windowPortionOnScreen.bottom;
    
    // If this is the largest area that has been encountered so far,
    // remember this screen as the potential screen to zoom to.
    if (windowAreaOnScreen > zoomData->largestArea) {
        zoomData->largestArea = windowAreaOnScreen;
        zoomData->screenWithLargestPartOfWindow = targetDevice;
    }
}

THE CALCULATEOFFSETAMOUNT ROUTINE
The zooming code calls the CalculateOffsetAmount routine to calculate the number of pixels the window needs to be nudged to be entirely on the screen. This routine works in one dimension at a time, so ZoomTheWindow calls it twice, once for the width of a window and once for the window's height. If CalculateOffsetAmount determines that the window is larger than the screen, it returns 0 for the offset, since the window will be resized later.

short CalculateOffsetAmount(short idealStartPoint,
        short idealEndPoint, short idealOnScreenStartPoint,
        short idealOnScreenEndPoint, short screenEdge1,
        short screenEdge2)
{
    short offsetAmount;
    
    // Check to see if the window fits on the screen in this
    // dimension.
    if ((idealStartPoint < screenEdge1) &&
            (idealEndPoint > screenEdge2))
        offsetAmount = 0;
    else {
        // Find out how much of the window lies off this screen by 
        // subtracting the amount of the window that's on the screen
        // from the size of the entire window in this dimension. If
        // the window is completely off-screen, offset the window so
        // that it's placed just on the screen.
        if ((idealOnScreenStartPoint - idealOnScreenEndPoint) == 0) {
            // See if the window is lying to the left or above the
            // screen.
            if (idealEndPoint < screenEdge1)
                offsetAmount =
                    screenEdge1 - idealStartPoint + kNudgeSlop;
            else
                // Otherwise, it's below or to the right of the
                // screen.
                offsetAmount =
                    screenEdge2 - idealEndPoint - kNudgeSlop;
        }
        else {
            offsetAmount = (idealEndPoint - idealStartPoint) -
                            (idealOnScreenEndPoint -
                                idealOnScreenStartPoint);
                            
            // If we're nudging, add slop pixels.
            if (offsetAmount != 0)
                offsetAmount += kNudgeSlop;

            // Check to see which side of the screen the window was
            //  fallingoff of, so that it can be nudged in the
            // opposite direction.
            if (idealEndPoint > screenEdge2)
                offsetAmount = -offsetAmount;
        }
    }
    return offsetAmount;
}

CalculateOffsetAmount determines the nudge amount by calculating the amount of overlap of two line segments. The first line segment, described by the idealStartPoint and idealEndPoint parameters, is the width or height of the window being zoomed. The second line segment, described by the idealOnScreenStartPoint and idealOnScreenEndPoint parameters, is the part of the window's width or height that is on the screen the window will be zoomed to. The number of pixels the window will be nudged is the difference between the lengths of these two line segments, plus some slop. If the length of the second line segment is 0, the window is entirely off the screen that it will be zoomed to. In this case, CalculateOffsetAmount will return the number of pixels the window will have to be nudged to be just on the screen. A third line segment, describing the screen width or height, is used to check whether the window is larger than the screen and to determine the direction to nudge the window.

ZOOMING AWAY

The code presented in this article takes care of most of the work of zooming windows. All your application needs to do is supply the code that determines the ideal size for your windows. Hopefully, many more applications will implement proper zooming behavior in the near future. This will make the people in the offices around me especially happy, since it's one less thing I'll have to complain about.

RECOMMENDED READING

• "DeviceLoop Meets the Interface Designer" by John Powers, develop  Issue 13. How to use DeviceLoop the correct way.
• Making It Macintosh: The Macintosh Human Interface Guidelines Companion  (Apple Computer, 1993). Anyone who wants to write programs on the Macintosh should be required to go through this CD first. APDA #R0450LL/A.
• Sourcery  by Terry Pratchett (Signet, 1989). Find out about inspiration particles, magicons, and other subatomic particles and how they interact with ducks.

A lot of people think the Window Manager has some magic value stashed away in a dark corner that tells it whether a window is in its user state or its standard state. In reality, it's not that sophisticated. It's actually the WDEF that does all the work, since it's the thing that really needs to know which state a window is in. To make this decision, the standard document WDEF takes a window's portRect, converts it to global coordinates, and then compares it with the user and standard state rectangles to determine which state the window is in. *

If the structure region is always used to calculate the screen containing most of the window, there's actually a scenario in which the code will zoom to the wrong screen. If the user has a multiscreen setup and places a window so that it sits across two screens, with only the title bar showing on one screen but a sliver of the content region showing on the other, and there's more title bar than content showing, the window will zoom to the first screen. However, since there is content area on the second screen, the window should zoom to that screen. *

DEAN YU recently went on a cross-country road trip in his new car. In retrospect, he decided that the time off wasn't worth the emotional trauma of being pelted by marble-sized hail in Cheyenne, Wyoming, being salt-blasted in the Utah salt flats, being nearly blown off the road as an 18-wheeler passed him at 95 miles an hour in the dead of night, and having his windshield chipped by gravel falling off a dump truck. Dean didn't even get the satisfaction of finding out exactly how fast he can drive without getting pulled over for speeding in Nebraska. Sympathy notes and donations for getting his car repaired can be sent to Dean in care of develop .*

THANKS TO OUR TECHNICAL REVIEWERS C. K. Haun, Elizabeth Moller, Dave Owens, Craig Prouse *