/*

    File:       WindowPositioner.h

    Contains:   Window-handling code for the ColorReset application

    Written by: Forrest Tanaka  

    Copyright:  Copyright © 1988-1999 by Apple Computer, Inc., All Rights Reserved.

                You may incorporate this Apple sample source code into your program(s) without

                restriction. This Apple sample source code has been provided "AS IS" and the

                responsibility for its operation is yours. You are not permitted to redistribute

                this Apple sample source code as "Apple sample source code" after having made

                changes. If you're going to re-distribute the source, we require that you make

                it clear in the source that the code was descended from Apple sample source

                code, but that you've made changes.

    Change History (most recent first):

                7/13/1999   Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1

*/

#ifndef __WINDOWPOSITIONER__

#define __WINDOWPOSITIONER__

/******************************************************************************\

* Header Files

\******************************************************************************/

#ifndef THINK_C

#ifndef __WINDOWS__

#include <Windows.h>

#endif

#endif

/******************************************************************************\

* Constants

\******************************************************************************/

#define kMainScreenPos   0 /* Position window against the main screen */

#define kParentPos       1 /* Position window against parent window */

#define kParentScreenPos 2 /* Position window against parent windowÕs screen */

#define kCenterPos  0 /* Position window centered on base rectangle */

#define kAlertPos   1 /* Position window in alert position */

#define kStaggerPos 2 /* Position window staggered from other windows */

/******************************************************************************\

* PositionScreenRect - Position a rectangle based on the screen set-up

*

* Whenever a window is to be positioned on a screen in an aesthetic or at least

* unannoying way, PositionScreenRect is called to calculate a position for the

* window that tries not to get on peopleÕs nerves.  The position is returned as

* a point in global coordinates at which the top-left corner of the portRect of

* of the window being positioned should be placed.  The screenOption parameter

* specifies which screen the window should appear on.  It has the following

* values and meanings:

*

* kMainScreenPos   - Always position the window somewhere on the main screen.

*

* kParentPos       - Position the window within the portRect of the window

*                    specified by parentWindow.  If parentWindow is nil, then

*                    this parameter defaults to kMainScreenPos.

*

* kParentScreenPos - Position the window on the screen that contains most of the

*                    area of the window specified by parentWindow.  If

*                    parentWindow is nil or if Color QuickDraw isnÕt available,

*                    then this parameter defaults to kMainScreenPos.

*

* The positionOption parameter specifies how the window is to be positioned

* within the screen (or parentWindow if screenOption == kParentPos).  It has the

* following values and meanings:

*

* kCenterPos  - Center the window

*

* kAlertPos   - Position the window in alert position, that is, 1/3 of the

*               screen is above the alert and 2/3 below it.

*

* kStaggerPos - Stagger the window from existing windows.  An attempt is made to

*               position the window so that its portRect is in the upper-left

*               corner of the screen (or parentWindow if screenOption ==

*               kParentPos).  If the top-left corner of one or more windows is

*               already in that general area, then another attempt is made down

*               and to the right a bit.  These attempts are made either until

*               an area that doesnÕt collide with an existing window is found or

*               no areas devoid of windows can be found.  If no free area was

*               found, then attempts are made from the top-left corner again,

*               but this time collisions are tolerated.  A position that has the

*               fewest number of collisions is returned.

*

* The portRect of the window being positioned is normally passed in the

* windowRect parameter.  Its actual coordinates donÕt matter; PositionScreenRect

* is only interested in its width and height.  If positionOption == kStaggerPos,

* then PositionScreenRect wonÕt allow the portRect of a window to be staggered

* right off of the screen or window itÕs being positioned in.  If itÕs OK for a

* window to be staggered partly off of a screen or if the final size of the

* window depends on the position that PositionScreenRect returns, then

* windowRect should specify the smallest rectangle that would be allowed to be

* visible when the window is placed at the location that PositionScreenRect

* returns.  In other words, if you want PositionScreenRect to guarantee that at

* least the top-left 100 x 100 pixels of the window being positioned are visible

* when itÕs placed at the location that PositionScreenRect returns, then

* windowRect should be 100 x 100 pixels.

*

* parentWindow specifies the window that the positioned window is based on.  See

* the description of the screenOption parameter for details.  If screenOption ==

* kMainScreen, then parentWindow is ignored.

*

* hBias and vBias are only used if positionOption == kStaggerPos.  They specify

* the horizontal and vertical amounts to offset the returned position.  The

* number of pixels between the top of the portRect of the window being

* positioned and the top of the windowÕs frame should be passed in vBias.

* Likewise, the number of pixels between the left edge of the windowÕs portRect

* and the left edge of the windowÕs frame should be passed in hBias.  This is

* normally used to take into account the amount of space taken up by the title

* bar of the window being positioned.  You can use CalcWindowBias to have the

* bias calculated for you.

\******************************************************************************/

void PositionScreenRect(

    Rect      *modWindowRect,

    short     screenOption,

    short     positionOption,

    WindowPtr parentWindow,

    short     hBias,

    short     vBias);

/******************************************************************************\

* CalcWindowBias - Calculate the bias for a specific kind of window

*

* This routine calculates and returns the bias for the kind of window whose

* window proc ID is given in the procID parameter.  The biasÕs horizontal

* coordinate can then be passed in the hBias parameter of PositionScreenRect and

* the vertical coordinate can be passed in the vBias parameter.  This is so that

* windows can be staggered while taking into account the size of the title bar

* of a window and other parts of the window frame.  The "bias" is just my

* (actually CraigÕs) word for the vertical and horizontal distance between the

* top-left coordinate of the rgnBBox of the content region of a window and the

* top-left coordinate of the rgnBBox of the structure region of that same

* window.

*

* If the window being positioned has a go-away box, then true is passed in the

* goAwayFlag parameter, otherwise false is passed.

\******************************************************************************/

Point CalcWindowBias(

    short   procID,

    Boolean goAwayFlag);

#endif