/*

    File:       QISAPanels.h

    Contains:   Interface to the various panels.

    Written by: DTS

    Copyright:  Copyright © 2002 by 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):

$Log$

*/

#pragma once

/////////////////////////////////////////////////////////////////

// System interfaces

#if defined(__MACH__)

    #include <Carbon/Carbon.h>

#else

    #include <MacWindows.h>

    #include <Controls.h>

#endif

/////////////////////////////////////////////////////////////////

#ifdef __cplusplus

extern "C" {

#endif

/////////////////////////////////////////////////////////////////

typedef struct QISAState QISAState;     // defined in "QISA.c", panels can't see the details

typedef struct QISAPanel QISAPanel;     // forward declaration

// QISAPanelSwitchDirection defines the directions that you can step in the user interface.

typedef enum {

    kQISAPanelSwitchDirectionForward,

    kQISAPanelSwitchDirectionBackward

} QISAPanelSwitchDirection;

// The following type definitions represent the entry points to the panels.

typedef OSStatus (*PanelInitialiseProc)(QISAPanel *panel);

    // Called by QISA when the panel is first entered.  This gives 

    // the panel a chance to initialise its internal data structures. 

    // Note that the panel's window and controls have already been 

    // created by QISA as part of the main NIB instantiation.

    // 

    // Typical activities include:

    // 

    // o Sets up any controls.  If the control represents 

    //   global state, you get the global state using 

    //   QISAGetGlobalValue (from "QISA.h").

    //

    // o Overrides any other panel callbacks by modifying 

    //   panel->Terminate, panel->SwitchTo, etc.

    //

    // o Set up panel->refCon.

    // 

    // On entry, panel will point to a valid panel data structure.

    // On error, no other panel routines are called.

typedef void     (*PanelTerminateProc)(QISAPanel *panel);

    // Called to shut down a panel when the window is closed.

    // Only called if the PanelInitialiseProc was called and 

    // returned noErr.  Typically this routine disposes of 

    // panel->refCon.

    //

    // IMPORTANT: With the current implementation, this 

    // routines won't be called if the application is quit.

    //

    // On entry, panel will point to a valid panel data structure.

typedef OSStatus (*PanelSwitchToProc)(QISAPanel *panel);

    // Called immediately before the panel is made active. 

    // Normally this routine does the following tasks:

    // 

    // o Sets up any controls if they weren't set up in 

    //   the PanelInitialiseProc routine.

    // o Determines if the current state allows the user to 

    //   move to the next panel, and activates the forward 

    //   button (using QISASetButtonEnable) accordingly.

    // 

    // On entry, panel will point to a valid panel data structure.

    // On error, an error dialog is displayed and the panel 

    // is not made active.  

typedef OSStatus (*PanelSwitchFromProc)(QISAPanel *panel, QISAPanelSwitchDirection direction, QISAPanel **nextPanel);

    // Called when the panel is being switch from because 

    // the user has clicked the back or forward buttons. 

    // direction indicates which button is pressed.  The 

    // panel must return, in *nextPanel, which panel is 

    // to be switched to next.

    // 

    // On entry, panel will point to a valid panel data structure.

    // On entry, direction will be either kQISAPanelSwitchDirectionForward 

    // or kQISAPanelSwitchDirectionBackward.

    // On entry, nextPanel will not be NULL and *nextPanel is undefined.

    // On success, *nextPanel must be set to the panel to 

    // be switched to, either the next or previous panel, depending on 

    // direction.

    // On error, an error dialog is displayed and the panel 

    // is switched from.

    // 

    // IMPORTANT: With the current implementation, this 

    // routines won't be called if the window is closed 

    // or the application is quit.

extern const OSType kQISAPanelMagic;        // defined in "QISA.c"

struct QISAPanel {

    OSType                  magic;          // must be kQISAPanelMagic

    QISAState *             state;          // always a valid, but opaque, reference to the per-window state

    int                     index;          // the index of this panel, starting at 0 for the first panel

    WindowRef               window;         // a reference to the window in which the panel is running

    ControlRef              panelControl;   // a reference to the control in which all of the panel's controls are embedded

    Boolean                 initialised;    // true if this panel has been initialised, the panel should neither read nor write this

    void *                  refCon;         // a place for the panel to store its private data

    PanelInitialiseProc     Initialise;     // the panel initialisation proc

    PanelTerminateProc      Terminate;      // the panel termination proc

    PanelSwitchToProc       SwitchTo;       // the panel switch to proc

    PanelSwitchFromProc     SwitchFrom;     // the panel switch from proc

};

// IMPORTANT:

// The panel callbacks (except Initialise) are all set up to a default 

// implementation.  If your panel needs to override the default, it 

// should save the old callback away in its private data so that it 

// can call through to the inherited implementation.

// The following are prototypes for the panel initialisation routines for 

// each of the panels I've implemented so far.  Right now panels are statically 

// linked, so "QISA.c" has this knowledge of exactly which panels are implemented.

extern OSStatus  PortCCLPanelInitialise(QISAPanel *panel);

extern OSStatus  UserPassPanelInitialise(QISAPanel *panel);

extern OSStatus  SetupPanelInitialise(QISAPanel *panel);

#ifdef __cplusplus

}

#endif