/*

    File: HandyWindow.h

    Description:

        This file contains the routine prototypes for calls defined in HandyWindow.c

    These routines are used to take care of event handling and dispatching

    events to the various event handlers.

    HandyWindow.c implements the routines used for drawing the windows

    displayed by this application.

    Copyright:

        © Copyright 2000 Apple Computer, Inc. All rights reserved.

    Disclaimer:

        IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.

        ("Apple") in consideration of your agreement to the following terms, and your

        use, installation, modification or redistribution of this Apple software

        constitutes acceptance of these terms.  If you do not agree with these terms,

        please do not use, install, modify or redistribute this Apple software.

        In consideration of your agreement to abide by the following terms, and subject

        to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs

        copyrights in this original Apple software (the "Apple Software"), to use,

        reproduce, modify and redistribute the Apple Software, with or without

        modifications, in source and/or binary forms; provided that if you redistribute

        the Apple Software in its entirety and without modifications, you must retain

        this notice and the following text and disclaimers in all such redistributions of

        the Apple Software.  Neither the name, trademarks, service marks or logos of

        Apple Computer, Inc. may be used to endorse or promote products derived from the

        Apple Software without specific prior written permission from Apple.  Except as

        expressly stated in this notice, no other rights or licenses, express or implied,

        are granted by Apple herein, including but not limited to any patent rights that

        may be infringed by your derivative works or by other works in which the Apple

        Software may be incorporated.

        The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO

        WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED

        WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR

        PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

        COMBINATION WITH YOUR PRODUCTS.

        IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR

        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

        GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

        ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

        OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT

        (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN

        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Change History (most recent first):

        Tue, Feb 8, 2000 -- created

*/

#ifndef __HANDYWINDOW__

#define __HANDYWINDOW__

#define TARGET_API_MAC_CARBON 1

#ifdef __APPLE_CC__

#include <Carbon/Carbon.h>

#else

#include <Carbon.h>

#endif

/* OpenHandyWindow opens a handy window using the WIND resource

    with the windowID ID. If successful, OpenHandyWindow returns a

    pointer to the newly created window. if drawSlow is true, then the

    window is set to draw the image slowly adding 1 tick per square

    in the pattern. */

WindowPtr OpenHandyWindow(short windowID, Boolean drawSlow);

/* CloseAllHandyWindows closes every handy window

    opened by calling OpenHandyWindow. */

void CloseAllHandyWindows(void);

/* HandyWindowUpdate should be called for update events

    directed at a handy window.  It calls

    BeginUpdate and EndUpdate and does all of the

    drawing required to refresh the handy window. */

OSErr HandyWindowUpdate(WindowPtr HandyWindow);

/* HandyWindowActivate should be called for activate events

    directed at the handy window. */

OSErr HandyWindowActivate(WindowPtr theWindow, Boolean activate);

/* HandyWindowCloseWindow closes the about box window. 

    this routine deallocates any structures allocated

    by the OpenHandyWindow. */

OSErr HandyWindowCloseWindow(WindowPtr theWindow);

/* FindHandyWindow iterates through the list of open handy windows

    looking for a HandyWindowRecord containing a window pointer

    matching the theWindow.  If one is found, a pointer to the

    HandyWindowRecord is returned.  If there is no HandyWindowRecord

    record for the window in the list of open handy windows, then

    NULL is returned. */

Boolean IsHandyWindow(WindowPtr HandyWindow);

/* HandyWindowMouse is called when the mouse is clicked in the content

    area of a window created by OpenHandyWindow.  where is a point in

    the window's coordinates, and modifiers is the state of the modifier

    keys copied from the event record. */

OSErr HandyWindowMouse(WindowPtr theWindow, Point where, short modifiers);

/* HandyWindowKey is called when a keydown event is received and

    a handy window is frontmost.  Some users prefer to navigate using

    the arrow keys, so this is often a useful facility to include in your

    software. */

OSErr HandyWindowKey(WindowPtr theWindow, char key, short modifiers);

/* HandyWindowCursor is called when a handy window is the frontmost window and

    the HandySample application is the frontmost application.  where is a point in

    the window's coordinates, and modifiers is the state of the modifier

    keys copied from the event record.  mouseRgn is a handle to a region.  If

    HandyWindowCursor sets the cursor, then it will also set this region to

    the region where it is appropriate for the cursor to remain as it has been

    set (in global coordinates).  this region is appropriate for passing to WaitNextEvent

    in the mouse region parameter. */

Boolean HandyWindowCursor(WindowPtr HandyWindow, Point where, short modifiers, RgnHandle mouseRgn);

/* GetHandyWindowGrowLimits sets the sizerect rectangle parameter

    to values appropriate for passing to the GrowWindow routine. */

OSErr GetHandyWindowGrowLimits(WindowPtr theWindow, Rect *sizerect);

/* HandyWindowSizeChanged should be called whenever the size of a window

    created by OpenHandyWindow has been changed by either a call to

    ZoomWindow or SizeWindow. */

OSErr HandyWindowSizeChanged(WindowPtr handyWindow);

/* HandyWindowScrollTo scrolls the to the location provided in

    the position parameter.  The actual distance scrolled will be

    restricted to the allowable scroll bar limits */

OSErr HandyWindowScrollTo(WindowPtr theWindow, Point position);

/* HandyWindowGetSlow returns the state of the handy window's drawing

    speed.  For illustration, it is possible to set the drawing speed to either

    slow or fast. */

OSErr HandyWindowGetSlow(WindowPtr theWindow, Boolean *drawnSlowly);

/* HandyWindowSetSlow sets the state of the handy window's drawing

    speed and posts an update event so the contents will be re-drawn

    showing the new speed.  For illustration, it is possible to set the

    drawing speed to either slow or fast. */

OSErr HandyWindowSetSlow(WindowPtr theWindow, Boolean drawSlowly);

#endif