March 94 - THE ZEN OF WINDOW ZOOMING
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(¤tPort);
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);