c1_engin.hpp

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

//////////////////////////////////////
// START of File: C1_ENGIN.HPP
//////////////////////////////////////

#ifndef C1_ENGIN_HPP
#define C1_ENGIN_HPP

//-------------------------------------------------------------------
// COPYRIGHT NOTICE:  This code is protected by Copyright!
//
// Copyright (c) 1994 through 1997 by DPC Technology Corporation.
// All rights reserved.
//
// 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/c1_engin.hpp>
            // Chart Framework "Virtual Chart Engine" BASE class object.

//--------------------------------------------------------------------
// Include Chart Framework class or ID defs/headers this file needs.
// Paths are relative to the IDE's (global) include path: ~/cfrz
//--------------------------------------------------------------------
#include    <cf_api/cf_defs.h>
            // contains Chart Framework typedef(s)

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

class       cf_String;
#include    <cf_api/c0_dystr.hpp>

class       bf_Display;
class       bf_2DBitmap;
#include    <cf_api/b0_dspla.hpp>
            // which pulls in the classes above...

class       cf_DyArr;   // We'll use dynamic arrays of (void) ptrs
#include    <cf_api/c0_dyarr.hpp>  // to "virtual-3D-objects"

class       cf_Kernel;
#include    <cf_api/c1_kernl.hpp>

class       cf_3DPoint;
class       cf_3DPolygon;
#include    <cf_api/co1_pgon.hpp>
            // which pulls in the classes above...

class       cf_TitleMarkerMgr;
class       cf_3DTextMarkerSeries;
#include    <cf_api/co1_tms.hpp>

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

class       cf_3DBitmap;
#include    <cf_api/co1_cbmp.hpp>

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


//--------------------------------------------------------------
// Declare a Chart Framework "Virtual Chart Engine" Base Class:
//--------------------------------------------------------------
class CF_EXPORT   cf_ChartEngine
{

public:

    cf_ChartEngine( cf_ChartType    enumChartType,
                    cf_DispMode     enumDispMode );
                    // Chart-Types are specified in file: "cf_defs.h"
                    // Creates (and deletes) an encapsulated geometry-kernel.

    virtual         ~cf_ChartEngine();

    cf_Kernel*      activeKernel();
    BOOL            activeKernel(   cf_Kernel   *p_cf_kNewKernel,
                                    BOOL        bDeleteOldKernelNow,
                                    BOOL        bDeleteNewKernelAtDtor );
                    // Any chart-engine can create it's own kernel, or
                    // borrow/hot-swap its kernel in/out at run-time!
                    // A powerful member method -- for CF-Experts only!

    cf_3DGridTickSeries*    axis_X_BackFace();
    cf_3DGridTickSeries*    axis_X_BottomFace();
    cf_3DGridTickSeries*    axis_Y_LeftFace();
    cf_3DGridTickSeries*    axis_Y_BackFace();
    cf_3DGridTickSeries*    axis_Z_LeftFace();
    cf_3DGridTickSeries*    axis_Z_BottomFace();
    cf_3DGridTickSeries*    axis_Polar_Floor();
                            // accessor methods for implicit grid/tick
                            // series objects associated with a standard
                            // chart-engine.  If the objects do not yet
                            // exist they will be new()-ed by the engine.

    virtual void    applyDataUpdate( cf_ChartModel *p_cf_cmodlDataSource );
                    // When a chart-model has a data-update, it will
                    // call this "umbrella" chart-engine method to
                    // tell the chart-engine to begin (re)generating
                    // its components and collection of virtual-
                    // geometry objects according to the current
                    // data-state of the chart-model.  Derived chart-
                    // engines (including customized derivations)
                    // should use their own specific over-rides
                    // of this virtual method.  This method might
                    // also call one or more protected (and possibly
                    // re-derived update() methods, (such as
                    // updateYValsAtIntIs(), updateAxisGridTickSeries(),
                    // etc.) according to a given specific
                    // implementation of a derived chart-engine.


    virtual void    applyDispMetrics();
    virtual void    applyGeomXform();
    virtual void    applyProjXform();
                    // Causes cascading geometry/projection update(s)
                    // throughout this chart-engine's collection of
                    // components and/or virtual-geometry-objects...

    cf_DispAttribs* attribChartFaceDisp( cf_ChartFace enumChartFaceSelector );
                    // Get method allows set display-attrib ops on chart-faces.

    virtual void    autoConfigure();
                    // Causes a chart-component reconfiguration to
                    // conform to latest user-programmer preferences
                    // (such as perspective, proportioning, etc.).

    BOOL            bitmapChartWallFile();
    void            bitmapChartWallFileName( const char *a_cFileNameString );
    const char*     bitmapChartWallFileName();
                    // Methods for a "background-bitmap" source file.
                    // Also see dispBitmapChartWall(); below...

    BOOL            bitmapWallPaperFile();
    void            bitmapWallPaperFileName( const char *a_cFileNameString );
    const char*     bitmapWallPaperFileName();
                    // Methods for a "wall-projected-bitmap" source file.
                    // Also see dispBitmapWallPaper(); below...

    cf_ChartType    chartType();
    BOOL            chartTypeBarColStackIs();
    BOOL            chartTypeCartesianIs();
    BOOL            chartTypePolarIs();
                    // Once we get beyond this "base" class, charts
                    // will be either "Cartesian" or "Polar".  This
                    // may cause different requirements for things
                    // like engine index-modes dialogs/displays/etc.
                    // Bar/Col/Stack-type charts have *slightly* different
                    // indexing requirements from "point"-type charts such
                    // as point series, line, and (integral) area charts,
                    // so it helps to keep track of this type/category.

    cf_DispMode     disp2D3DMode();
    virtual BOOL    disp2D3DMode( cf_DispMode enumNewDispMode );

    BOOL            dispBitmapChartWall();
    void            dispBitmapChartWall( BOOL bNewState );
                    // Displays a "wall-projected-bitmap" source file.
                    // Also see bitmapChartWallFileName(); above...

    BOOL            dispBitmapWallPaper();
    void            dispBitmapWallPaper( BOOL bNewState );
                    // Displays a "background-bitmap" source file.
                    // Also see bitmapWallPaperFileName(); above...

    bf_Color        dispColorBackground();
    void            dispColorBackground( const bf_Color &cr_bf_clrNew );

    bf_Color        dispColorFaceBack();
    void            dispColorFaceBack( const bf_Color &cr_bf_clrNew );

    bf_Color        dispColorFaceBottom();
    void            dispColorFaceBottom( const bf_Color &cr_bf_clrNew );

    bf_Color        dispColorFaceLeft();
    void            dispColorFaceLeft( const bf_Color &cr_bf_clrNew );

    bf_Color        dispColorFaceLines();
    void            dispColorFaceLines( const bf_Color &cr_bf_clrNew );
                    // display-attribute methods for chart-face-colors

    BOOL            dispFaceBack();
    void            dispFaceBack( BOOL bNewState );

    BOOL            dispFaceBottom();
    void            dispFaceBottom( BOOL bNewState );

    BOOL            dispFaceLeft();
    void            dispFaceLeft( BOOL bNewState );
                    // Manipulate the ON/OFF display attributes of
                    // the Back and/or Left and/or Bottom chart-faces

    BOOL            dispForceBackBorder();
    void            dispForceBackBorder( BOOL bNewState );
                    // Force background rect poly-line to render
                    // into the display.  Useful for "stubborn"
                    // print-display contexts.  C-tor inits OFF.

    BOOL            dispForceBackColor();
    void            dispForceBackColor( BOOL bNewState );
                    // Force FILLED background rectangle to render
                    // into the display.  Useful for "stubborn"
                    // print-display contexts.  C-tor inits OFF.

    void            dispVirtCentroid( BOOL bNewState );
    void            dispVirtObjMaxPoint( BOOL bNewState );
    void            dispVirtObjMinPoint( BOOL bNewState );
                    // Get/set "draw-virtual-points" modes ON/OFF.

    BOOL            dispWireFrameMode();
    void            dispWireFrameMode( BOOL bNewState );
                    // Wire-Frameing skips Hidden-Surface-Elimination
                    // and/or Depth-Sorting ops and so is MUCH more
                    // efficient when directly manipulating chart
                    // configurations (such as in dialogs, etc...)

    BOOL            dispZoomMode();
    void            dispZoomMode( BOOL bNewState );
                    // When Zoom-Mode is TRUE, the chart-engine IGNORES
                    // any user-specified margins when it calcs the
                    // display-context rendering projection-rectangle.

    virtual void    draw( bf_Display *p_bf_dspOutputDisplay );
                    // Self-explanatory.  Chart-Engines render into
                    // a display-context provided by their parent
                    // chart-model, which itself has a display-
                    // context provided by a parent chart-view.

    cf_TitleMarkerMgr*
                    markerMgrTitlesAxes();
                    // Access the chart-engine "Text-Marker-Manager"
                    // object that can be used to control and access
                    // the EXISTING set of title, sub-title, and
                    // axis-label 3D-Text-Markers.


    cf_3DTextMarkerSeries*
                    markerMgrUserLegends();
                    // Access the chart-engine "3D-Text-Marker-Series"
                    // that can be used to create and control EXTRA
                    // user-specified 3D-text-markers for use as
                    // chart-legends, etc.


    double          measuredDataXRangeMin();
    double          measuredDataXRangeMax();
    double          measuredDataYRangeMin();
    double          measuredDataYRangeMax();
    double          measuredDataZRangeMin();
    double          measuredDataZRangeMax();

    double          measuredVirtXOrigin();
    double          measuredVirtYOrigin();
    double          measuredVirtZOrigin();

    double          measuredVirtXRangeMin();
    double          measuredVirtXRangeMax();
    double          measuredVirtYRangeMin();
    double          measuredVirtYRangeMax();
    double          measuredVirtZRangeMin();
    double          measuredVirtZRangeMax();
                    // Data-query methods used by chart-objects
                    // encapsulated by this chart-engine (which likely
                    // do NOT have direct access to this chart-engine's
                    // parent-chart-model) -- such as automatic-axis
                    // grid/tick-series objects.


    BOOL    positPointAt(   cf_3DPoint  *p_cf_3dpTargetPoint,
                            double      dPctWidthFromCtr,
                            double      dPctHeightFromCtr,
                            double      dPctDepthFromCtr = 0.0,
                            BOOL        bCorrectOriginOffset = FALSE );
            // Allows user classes (e.g. axis grid/tick/series) to
            // over-ride any default positioning of a 3D Point (e.g.
            // Axis Label Text Marker Points) and specify a new posit
            // as an X/Y/Z % val away from the CENTER of the 3D Box
            // of the chart.  Positive OR negative % vals are allowed.
            // Note that optional correction for default origin xlation
            // (e.g. when grid/tick-series are added to engines via
            // the "add-Component-Object(...)" method) is available,
            // but is NOT the default mode of operation.

    //------------------------------------------------------------
    // The chart-engine "preference" methods below typically
    // pass their parameters directly to a corresponding member
    // method of the geometry-kernel object associated with this
    // chart-engine, and are provided in this chart-engine object
    // basically for convenience...
    //------------------------------------------------------------
    void    preferMarginTop(    int iMarginInTwips );
    void    preferMarginBottom( int iMarginInTwips );
    void    preferMarginLeft(   int iMarginInTwips );
    void    preferMarginRight(  int iMarginInTwips );

    void    preferMargins(  int iTopMarginInTwips,
                            int iBottomMarginInTwips,
                            int iLeftMarginInTwips,