c1_cmodl.hpp

windRiver提供的的Zinc5.3完整源码,文档非常齐全

//////////////////////////////////
// START of File: C1_CMODL.HPP
//////////////////////////////////

#ifndef C1_CMODL_HPP
#define C1_CMODL_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    <cf_api/c1_cmodl.hpp>
            // This "Chart-Model" object hold user-data and group-attributes,
            // (in "Data-Groups") for one or more "Chart-Engine" object(s)
            // -- which generate and render the chart's geometrical objects).
            // Note that a Chart-Model exists as part of a "Chart-View" which
            // is usually owned by some sort of "Chart-Control" object
            // in a Model/View/Controller configuration/relationship.


//--------------------------------------------------------------------
// Specify the Chart Framework classes or defs/headers this file needs.
//--------------------------------------------------------------------
#include    <cf_api/cf_defs.h>
            // contains Chart Framework typedef(s)

#include    <cf_api/cf_const.h>
            // defines chart engine default values

class       cf_DyArr;   // We'll use dynamic arrays of (void) ptrs...
#include    <cf_api/c0_dyarr.hpp>   // ...to cf-data-group objects
                                    // ...and cf-chart-engine objects
class       cf_String;
#include    <cf_api/c0_dystr.hpp>

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

class       bf_Display;
#include    <cf_api/b0_dspla.hpp>
            // also has enums bf_PenStyle and bf_BrushHatch...

class       bf_2DBitmap;
#include    <cf_api/b0_dsbmp.hpp>

class       cf_DataGroup;
#include    <cf_api/c1_dgrou.hpp>

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

class       cf_ChartView;
#include    <cf_api/c4_cview.hpp>

// Define values used throughout this module:
#define     C1_CMODL_NUM_PALETTE_COLORS         16
#define     C1_CMODL_NUM_PEN_STYLES              3
#define     C1_CMODL_NUM_BRUSH_HATCHES           3

//------------------------------------------------------------
// Declare a ChartFolio "User-Chart Data-Model" (base) Class:
//------------------------------------------------------------
class CF_EXPORT   cf_ChartModel

{

public:

    cf_ChartModel(  cf_ChartView    *p_bf_cviewOwner,
                    cf_IndexMode    enumIndexMode  = CF_INDEX_NAT_N );

    ~cf_ChartModel();

    cf_DataGroup*   accessGroupsList();
    cf_DataGroup*   accessDomainItems();
    cf_DataGroup*   accessRangeValues();
                    // Allow users to access the implicit "domain",
                    // "range", and "group-list" data-groups this
                    // model constructs from user data.


    cf_DataGroup*   activateGroupAxis( cf_ChartAxis  enumChartAxisSelector );
    cf_DataGroup*   activateGroupAxisLabel( cf_ChartAxis enumChartAxisSelector );
    cf_DataGroup*   activateGroupLegend(  int   iUserLegendNumber );
    cf_DataGroup*   activateGroupTitle( cf_ChartTitle  enumChartTitleSelector );
    cf_DataGroup*   activateGroupUserData( int  iUserGroupIndex );
                    // Engines interact with (e.g. pull data) from pointers
                    // to "active" group in either: (1) a "dynamic array"
                    // of data groups, or (2) a collection of data-groups
                    // that this Chart-Model keeps for their reference...


    cf_ChartEngine* activeEngine();
    BOOL            activeEngine(   cf_ChartEngine  *p_cf_engToUseOurData );

    cf_ChartView*   activeView();
                    // Returns the current pointer to the "parent" chart-view.


    cf_XYZ*     addDataYVal( double      dUserYVal,
                             const char* a_cDomainItemLabel = NULL,
                             const char* a_cRangeValueLabel = NULL );
                //===================================================
                // Add a (y) data item to the current "activated"
                // (z) group.  Domain (x) index values automatically
                // generated according to the chart-model's current
                // domain-indexing method ID. Group (z) index
                // generated from current "activateGroupUserData()" call.
                // Optional labels from const char* strings show up
                // on respective domain and range axes. Note that
                // THIS IS THE RECOMMENDED DATA STORAGE METHOD for
                // about 90 to 95 percent of all Chart Types!
                //===================================================

    cf_XYZ*     addDataXYVal( double      dUserXVal,
                              double      dUserYVal,
                              const char* a_cDomainItemLabel = NULL,
                              const char* a_cRangeValueLabel = NULL );
                //===================================================
                // Add a (x,y) data item to the current "activated"
                // (z) group. Domain (x) index value is SPECIFIED by
                // the user.  Domain index method AUTOMATICALLY reset
                // to CF_ID_YVALS_AT_USR_XS; e.g. x = 2.3, 10.2 .. X.
                // Z-index generated from current "activateGroupUserData()"
                // call.  Optional labels from const char* strings
                // show up on respective domain and range axes.
                // Note that this data storage method is ONLY
                // RECOMMENDED for X/Y "Scatter Plots" or EXPLICIT
                // "Time-Series Plots"!
                //===================================================


    cf_XYZ*     addDataXYZVal( double      dUserXVal,
                               double      dUserYVal,
                               double      dUserZVal,
                               const char* a_cDomainItemLabel = NULL,
                               const char* a_cRangeValueLabel = NULL );
                //===================================================
                // Add a (x,y,z) data item to the current "activated"
                // group. Domain (x) index value is SPECIFIED by the
                // user.  Domain Index method AUTOMATICALLY reset
                // to CF_ID_YVALS_AT_USR_XS; e.g. x = 2.3, 10.2 .. X.
                // Note that y AND z values are specified by the user,
                // so there is NOT implicit z-group indexing. The
                // optional labels from const char* string show up
                // on respective domain and range axes.  Note that
                // this data storage method is ONLY RECOMMENDED
                // for X/Y/Z "Scatter Plots"!
                //===================================================



    cf_XYZ* addLabelDomainItem( double      dDomainItemIndex,
                                const char  *p_strDomainItemLabel );
    cf_XYZ* addLabelDomainItem( double      dDomainItemIndex,
                                double      dValueForLabel );
            // Add an index (char string OR user-specified
            // value) label to the "domain axis item" group:

    cf_XYZ* addLabelGroupsList( double      dGroupListIndex,
                                const char  *p_strGroupListLabel );
    cf_XYZ* addLabelGroupsList( double      dGroupListIndex,
                                double      dValueForLabel );
            // Add an index (char string OR user-specified
            // value) label to the "data-groups list" group:

    cf_XYZ* addLabelRangeValue( double      dRangeValueIndex,
                                const char  *p_strRangeValueLabel );
    cf_XYZ* addLabelRangeValue( double      dRangeValueIndex,
                                double      dValueForLabel );
            // Add an user-specified (char string OR user-specified)
            // value) label to the "range values" group:

    int     dataGroupActive();
            // Returns the current active index value

    int     dataGroupCount();
            // Returns the number of allocated data-groups

    int     dataGroupsStartAt();
    int     dataGroupsEndAt();
            // Yields the min and max index values for
            // the current set of activated data-groups

    cf_DataGroup*   dataGroupsReset();
                    // Performs a "delete" op on each activated
                    // data-group, then re-inits a default active
                    // data-group number one, and returns a pointer
                    // to this default data-group.


    cf_IndexMode    dataIndexMethod();
    BOOL            dataIndexMethod(    cf_IndexMode    enumNewIndexMode,
                                        BOOL            bForceEngineUpdate );
                    //=======================================================
                    // Get/set Index Method IDs as follows:
                    //  CF_INDEX_NAT_NS; e.g: n = 1, 2, 3, .. N.
                    //  CF_INDEX_INT_IS; e.g: i = 0, 1, 2, .. I.
                    //  CF_INDEX_USR_XS; e.g. x = 2.3, 10.2 .. X.
                    //=======================================================


    double      dataRangeInclMaxBuffer();
    void        dataRangeInclMaxBuffer( double dAddOntoCurrentRange );
                // Get/set extra "margin" onto the user-data-range.
                // Subject to range's "use-max-ceiling" state (below).
                // C-tor inits this buffer value to zero.

    double      dataRangeInclMaxCandidate();
    void        dataRangeInclMaxCandidate( double dPossibleMaxVal );
                // Get/set a "candidate" max value for user-data-range.
                // Subject to range's "max-buffer" state (above).
                // Subject to range's "use-max-ceiling" state (below).

    BOOL        dataRangeInclMaxCandidateInUse();
    void        dataRangeInclMaxCandidateInUse( BOOL bNewState );
                // Turn consideration of any candidate max value for
                // the user data-range ON/OFF.  C-tor inits to FALSE.
                // Calls to dataRangeInclMaxCandidate( double );
                // (immediately above) reset this state to TRUE!

    BOOL        dataRangeInclMaxCeiling();
    void        dataRangeInclMaxCeiling( BOOL bNewState );
                // If set TRUE, uses math.h ceil() to round user data
                // ranges UP to an integer value.  C-tor inits to FALSE.

    double      dataRangeInclMinBuffer();
    void        dataRangeInclMinBuffer( double dAddOntoCurrentRange );
                // Get/set extra "margin" onto the user-data-range.
                // Subject to range's "use-min-floor" state (below).
                // C-tor inits this buffer value to zero.

    double      dataRangeInclMinCandidate();
    void        dataRangeInclMinCandidate( double dPossibleMinVal );
                // Get/set a "candidate" min value for user-data-range.
                // Subject to range's "min-buffer" state (above).
                // Subject to range's "use-min-floor" state (below).

    BOOL        dataRangeInclMinCandidateInUse();
    void        dataRangeInclMinCandidateInUse( BOOL bNewState );
                // Turn consideration of any candidate min value for
                // the user data-range ON/OFF.  C-tor inits to FALSE.
                // Calls to dataRangeInclMinCandidate( double );
                // (immediately above) reset this state to TRUE!

    BOOL        dataRangeInclMinFloor();
    void        dataRangeInclMinFloor( BOOL bNewState );
                // If set TRUE, uses math.h floor() to round user data
                // ranges DOWN to an integer value.  C-tor inits to FALSE.


    BOOL        dataRangeInclOrigAlways();
    void        dataRangeInclOrigAlways( BOOL bNewState );
                // Get/set data-range-origin-in(/ex)clusion treatment.
                // C-tor inits this FORCED origin inclusion to FALSE;

    double      dataRangeInclOrigFromDelta();
    void        dataRangeInclOrigFromDelta( double dNumDataDeltasAway );
                // Get/set data-range-origin-in(/ex)clusion treatment.
                // C-tor inits this data-dependent limit to 3 data deltas.

    double      dataXItemsMax();
    double      dataXItemsMin();
    double      dataXItemsExtent();
                // Query methods for special use.  See note below...

    double      dataYValuesMax();
    double      dataYValuesMin();
    double      dataYValuesExtent();
                // Query methods for special use.  See note below...

    double      dataYValSumsMax();
    double      dataYValSumsMin();
    double      dataYValSumsExtent();
                // Query methods for special use.  See note below...

    double      dataZGroupsMax();
    double      dataZGroupsMin();
    double      dataZGroupsExtent();
                // Query the active data groups for min/max/range
                // values.  For use in engine axis/tick ops, etc...
                // ...or for "advanced" or customized-engine usage.


    cf_DataGroup*   labelAxis(  const char      *p_strNewLabel,
                                cf_ChartAxis    enumChartAxisSelector,
                                double          dPercentFromXCenterCoord,
                                double          dPercentFromYCenterCoord,
                                double          dPercentFromZCenterCoord );

    cf_DataGroup*   labelAxisData( cf_ChartAxis   enumChartAxisSelector );
    //BOOL            labelAxisIs( cf_ChartAxis   enumChartAxisSelector );
                    // Run the BOOL validator *BEFORE* the pointer-accessor!

    void            labelAxesReset();


    cf_DataGroup*   labelLegendData( int iAtIndex );