/////////////////////////////////////////
// START of File: C4_CVIEW.HPP
/////////////////////////////////////////

#ifndef C4_CVIEW_HPP
#define C4_CVIEW_HPP

//===================================================================
//
//  COPYRIGHT NOTICE:  This code is protected by Copyright!
//  -------------------------------------------------------
//
// Copyright (c) 1994 through 1997 by DPC Technology Corporation.
// All rights reserved by DPC Technology Corporation.
//
// See files "cf_copyr.txt" and "cf_licen.txt" for details of
// copyright and license specifications, and contact information.
//
//===================================================================

// Master Header File Listing:
// Usage:   #include    <api/include/c4_cview.hpp>
            // A "Chart View" object in a Model/View/Controller Hierarchy.
            // Route, translates, and controls display output ops, and
            // system/display events such as window re-draw and re-size
            // events, print events, etc, from the encapsulating parent
            // chart-control-object.

//-----------------------------------------------------------------
// Spec the interface-points/object-usage from the Base-Framework:
//-----------------------------------------------------------------
class       zEvent;
class       zDrawEvt;
class       zSizeEvt;
class       zNotifyEvt;
class       zWindow;
class       zSizer;
class       zPane;
class       zPrinterDisplay;
class       zRect;              // used as a "printer banding" param...
#include    <cf_api/bf_defs.h>
            // NOTE that (according to zApp spec) these implicit zApp
            // includes MUST come FIRST in the include file order.

//--------------------------------------------------------------------
// Include Chart Framework class or ID defs/headers this file needs.
//--------------------------------------------------------------------
#include    <cf_api/cf_defs.h>
            // Defines chart-typing enums-params used in c-tor below...

class       bf_Color;
#include    <cf_api/b0_color.hpp>

class       bf_Display;
#include    <cf_api/b0_dspla.hpp>

class       cf_ChartModel;
#include    <cf_api/c1_cmodl.hpp>

class       cf_3DGridTickSeries;
#include    <cf_api/co1_gts.hpp>

class       cf_ChartEngine;
#include    <cf_api/c1_engin.hpp>

class       zChartControl;
#include    <cf_api/b5_ccont.hpp>


//-------------------------------
// Declare a "Chart View" Object:
//-------------------------------
class CF_EXPORT   cf_ChartView
        //friend class zChartControl
{

public:

    cf_ChartView(   cf_ChartType    enumChartType,
                    cf_DispMode     enumDispMode,
                    cf_IndexMode    enumIndexMode );
                                    // Makes its own Chart Model...

    virtual         ~cf_ChartView();
                    // D-tor needs to discriminate whether we allocated a new
                    // chart model, or were just looking at someone else's...


    BOOL            activatedIs();
    void            activate( bf_Display *p_bf_dspToRenderInto );
                    // Called by this chart-view's parent chart-control to
                    // sychrnonize the chart-view's encapsulated kernel,
                    // model, and engine for an initial display rendering.


    //=========================================================================
    // Facilitate the parent Chart-Control's component-access/behavior methods:
    //=========================================================================
    cf_3DGridTickSeries*
                    activeAxis( cf_ChartAxis  enumChartAxisSelector );
                    // Allows acccess to the chart-engine's collection
                    // of axis-marking Grid/Tick-Series objects.

    cf_ChartEngine* activeEngine();
                    // Allows user drill-down acccess to the chart-engine.

    BOOL            activeEngine(   cf_ChartType    enumChartType,
                                    cf_DispMode     enumDispMode,
                                    BOOL            bDeleteOldEngine );

    BOOL            activeEngine(   cf_ChartEngine  *p_cf_engCustomized,
                                    BOOL            bDeleteOldEngine  );
                    // You can configure chart-engines by enumerated-type-specs,
                    // or by passing pointers to your own custom engine types.
                    // Give careful consideration to deleting the old engine!

    cf_ChartModel*  activeModel();
                    // Allows user drill-down access to the chart-model.


    //==============================================================
    // Facilitate the parent Chart-Control's add-data(...) methods:
    //==============================================================
    cf_XYZ&         addData(    int         iDataGroupNum,
                                double      dYVal );
                    // Will auto-generate the domain X-index values in
                    // the chart-model by defaulting to CF_INDEX_NAT_N
                    // (i.e. n=1,2,3,..N) behavior -- unless the index
                    // mode is set to CF_INDEX_INT_I ( i.e. i=0,1,2,..I).
                    // Z-index value is automatically set equal to the
                    // data-group number.  Returns a reference to the newly
                    // added x/y/z-data-triplet that has just been created
                    // which is often useful in the scope of user ops.
                    //*******************************************************
                    // Note that THIS IS THE RECOMMENDED DATA STORAGE METHOD
                    // for about 90 to 95 percent of all Chart Types!
                    //*******************************************************

    cf_XYZ&         addData(    int         iDataGroupNum,
                                double      dXVal,
                                double      dYVal );
                    //********************************************************
                    // Note that this data storage method is recommended ONLY
                    // for X/Y "Scatter Plots" or EXPLICIT "Time-Series Plots"!
                    //********************************************************
                    // Lets the user explicitly set the domain X-index values
                    // in the chart-model along with range Y-values. Z-index
                    // values are automatically set equal to the data-group
                    // number.  Returns a reference to the newly-created
                    // x/y/z-data-triplet.

    cf_XYZ&         addData(    int         iDataGroupNum,
                                double      dXVal,
                                double      dYVal,
                                double      dZVal );
                    //********************************************************
                    // Note that this data storage method is recommended ONLY
                    // for explicit X/Y/Z "Scatter Plot" applications!
                    //********************************************************
                    // Lets the user explicitly set domain X-index values,
                    // range Y-values, and range Z-values in the chart-model.
                    // Returns a reference to the new x/y/z-data-triplet.


    //===============================================================
    // Facilitate the parent Chart-Control's add-label(...) methods:
    //===============================================================
    cf_DataGroup&   setLabelAxisName(   const char      *p_strAxisLabel,
                                        cf_ChartAxis    enumChartAxisSelector,
                                        double      dPercentFromXCenterCoord,
                                        double      dPercentFromYCenterCoord,
                                        double      dPercentFromZCenterCoord );
                    // Lets the user add chart-model data which will auto-
                    // generate a axis-labels at the percentage position
                    // coordinates.  Each axis-label will be centered
                    // and will have the default color of CF_BLACK.

    cf_DataGroup&   setLabelAxisName(   const char      *p_strAxisLabel,
                                        cf_ChartAxis    enumChartAxisSelector );
                    // Default method places labels at the following coords:

    cf_XYZ&         addLabelAxisItem(   const char      *p_strAxisItemLabel,
                                        cf_AxisData     enumAxisDataSource,
                                        double          dAxisIndexLocation );

    cf_XYZ&         addLabelAxisItem(   double          dValueForLabel,
                                        cf_AxisData     enumAxisDataSource,
                                        double          dAxisIndexLocation );
                    // Adds a axis-data item-label to the Data-Model's
                    // "domain-axis-item" or "range-axis-value" or
                    // "groups-list-axis" data-groups.

                    //********************************************************
                    // NOTE! to avoid conflicts with automatic axis-item
                    // generation performed by the addData(...) methods, you
                    // should add axis-labels BEFORE any addData(...) calls!
                    //********************************************************


    cf_DataGroup&   addLabelLegend( const char  *p_strLegendLabel,
                                    double      dPercentFromXCenterCoord,
                                    double      dPercentFromYCenterCoord,
                                    double      dPercentFromZCenterCoord );
                    // Lets the user add chart-model data which will auto-
                    // generate a 3D-text-marker at the percentage position
                    // coordinates.  Each legend-markers will be right-shifted
                    // and will have the default palette color of its numerical
                    // order in the sequence of legend additions.

    cf_DataGroup&   setLabelTitle(  const char      *p_strTitleLabel,
                                    cf_ChartTitle   enumChartTitleSelector,
                                    double          dPercentFromXCenterCoord,
                                    double          dPercentFromYCenterCoord,
                                    double          dPercentFromZCenterCoord );
                    // Lets the user add chart-model data which will auto-
                    // generate a main/sub-titles at the percentage position
                    // coordinates.  Each title-markers will be centered
                    // and will have the default color of CF_BLACK.

    cf_DataGroup&   setLabelTitle(  const char      *p_strTitleLabel,
                                    cf_ChartTitle   enumChartTitleSelector );
                    // Default method places titles at the following coords:


    //========================================================================
    // Facilitate the parent Chart-Control's display/text-attrib(...) methods:
    //========================================================================
    cf_DispAttribs* attribAxisItemDisp( cf_ChartAxis  enumChartAxisSelector );
    cf_TextAttribs* attribAxisItemText( cf_ChartAxis  enumChartAxisSelector );

    cf_DispAttribs* attribAxisNameDisp( cf_ChartAxis  enumChartAxisSelector );
    cf_TextAttribs* attribAxisNameText( cf_ChartAxis  enumChartAxisSelector );

    cf_DispAttribs* attribChartFaceDisp( cf_ChartFace enumChartFaceSelector );

    cf_DispAttribs* attribDataGroupDisp( int iDataGroupNumber );
    cf_TextAttribs* attribDataGroupText( int iDataGroupNumber );
                    // Note: Data-groups not yet created will be new-ed!

    cf_DispAttribs* attribLegendDisp( int iUserLegendNumber );
    cf_TextAttribs* attribLegendText( int iUserLegendNumber );
                    // Note: Legends not yet created will be default/new-ed!

    cf_DispAttribs* attribTitleDisp( cf_ChartTitle   enumChartTitleSelector );
    cf_TextAttribs* attribTitleText( cf_ChartTitle   enumChartTitleSelector );



    //==================================================================
    // Facilitate the parent Chart-Control's behavior(...) methods:
    //==================================================================
    cf_3DGridTickSeries*
                    axisBehavior(   cf_ChartAxis    enumChartAxisSelector,
                                    double          dFreqTicksToData,
                                    int             iRatioLabelsToTicks,
                                    int             iRatioGridsToTicks,
                                    int             iRatioMajorToMinor,
                                    double          dPercentTickSizeToChart,
                                    long            lFlags );

    cf_3DGridTickSeries*
                    axisDataSource( cf_ChartAxis    enumChartAxisSelector,
                                    cf_AxisData     enumAxisDataSource,
                                    BOOL            bNewState );

    cf_3DGridTickSeries*
                    axisTicks(  cf_ChartAxis    enumChartAxisSelector,
                                double          dFreqTicksToData,
                                int             iRatioMajorToMinor,
                                double          dPercentTickSizeToChart,
                                long            lFlags );
    cf_3DGridTickSeries*
                    axisGrids(  cf_ChartAxis    enumChartAxisSelector,
                                int             iRatioGridsToTicks,
                                long            lFlags );

    cf_3DGridTickSeries*
                    axisLabels( cf_ChartAxis    enumChartAxisSelector,
                                int             iRatioLabelsToTicks,
                                long            lFlags );


    double          axisRangeMin();
    double          axisRangeMax();
    BOOL            axisRangePref(  double  dMinCandidate,
                                    double  dMaxCandidate );


    BOOL            axisRangeIncludesOrigin( BOOL bForceOriginInclusion );
    BOOL            axisRangeIncludesOriginIs();

    BOOL            axisRangeIncludesOrigin( double dWithinNumDataDeltas );
    double          axisRangeIncludesOrigin();



    //===================================================================
    // Facilitate the parent Chart-Control's chart-typing(...) methods:
    //===================================================================
    BOOL            chartType( cf_ChartType enumNewChartType );
    cf_ChartType    chartType();

    BOOL            chartDispMode( cf_DispMode enumNewDispMode );
    cf_DispMode     chartDispMode();

    BOOL            chartIndexMode( cf_IndexMode enumNewIndexMode );
    cf_IndexMode    chartIndexMode();


    //=================================================================
    // Facilitate the parent Chart-Control's geom/view(...) methods:
    //=================================================================
    BOOL            geomViewAngle(  cf_DispMode enumNewDispMode );
    BOOL            geomViewAngle(  double  dXAngleZeroToPositive90,
                                    double  dYAngleZeroToNegative90 );


    //=================================================================
    // Facilitate the parent Chart-Control's chart-reset(...) methods:
    //=================================================================
    void            resetAll( BOOL  bForceImmediateReDraw );
    void            resetData( BOOL  bForceImmediateReDraw );
    void            resetLabels( BOOL  bForceImmediateReDraw );
    void            resetLegends( BOOL  bForceImmediateReDraw );
    void            resetTitles( BOOL  bForceImmediateReDraw );



    //========================================================================
    // Facilitate the parent Chart-Control's chart-display-mode(...) methods:
    //========================================================================
    void            disp3DBmp( BOOL bNewState );

    BOOL            disp3DBmpIs();
                    // Get/Set the ON/OFF status of the Chart's 3D-Bitmap(s).

    void            dispColorBackground( bf_Color   bf_clrNewVal );
                    // Goal -- synchronize chart-engine background color(s)
                    // with this color sent by the parent chart-control.

    BOOL            draw( bf_Display  *p_bf_dspFromParentControl );
                    //*************************************************
                    // Goal -- pass the display context from the parent
                    // chart-control to the encapsulated chart-engine
                    // draw() member methods.  A crucial method!
                    //*************************************************

    void            updateDisplayMetrics( bf_Display *p_bf_dspHasChanged );
                    //*******************************************************
                    // Called by this chart-view's parent chart-control to
                    // respond to display re-sizes, re-sets, context-changes.
                    // Goals -- pass the display-context to the chart-engine's
                    // geom-kernel for geom-recalculation, and then apply
                    // the geom-changes to the chart-engine and its objects.
                    //********************************************************

protected:

    cf_ChartModel   *p_ViewsModel_;
                    //--------------------------------------------------------
                    // Holding the user-data for the chart-engine to render.
                    //--------------------------------------------------------

    BOOL            bWasViewsModelNewed_;
                    // We MAY new the pointer above -- BUT -- we may also be
                    // borrowing some ELSE's pointer!  So avoid double deletes.
                    // Note that this value is typically TRUE.

    cf_ChartEngine  *p_ViewsEngine_;
                    //--------------------------------------------------------
                    // Generates sets of 2D/3D chart-objects from user-data
                    //--------------------------------------------------------

    BOOL            bWasViewsEngineNewed_;
                    // Same rationale as above -- avoid double-deletes!
                    // Note that this value is typically true.

    BOOL            bIsActivatedForControlsDisplay_;
                    // Tracks if (at least one) engine-to-control/display
                    // synchronization has yet occured. C-tor inits FALSE,
                    // and the first call from the parent chart-control
                    // to this chart-view's activate(...) method sets true.

private:

    void            ctorInit(   cf_ChartType    enumChartType,
                                cf_DispMode     enumDispMode,
                                cf_IndexMode    enumIndexMode );
                    // Multiple c-tors may share commmon init-functionality.

    void            rz_doNothing();
                    // template for a Rogue-Wave zApp-specific helper-method.

};  // End of cf_ChartView Declaration.

#endif

/////////////////////////////////////////
// END of File: C4_CVIEW.HPP
/////////////////////////////////////////

