//////////////////////////////////////
// START of File: C0_TATB.HPP
//////////////////////////////////////

#ifndef C0_TATB_HPP            // Avoid multiple includes...
#define C0_TATB_HPP    TRUE    // ...holds to a terminal #endif below...

//===================================================================
//
// COPYRIGHT NOTICE:  This code is protected by Copyright!
//
// Copyright (c) 1994, 1995, 1996, 1997 by DPC Technology.
// 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:
//
// #include    <cf_api/c0_tatb.hpp>
//
// Chart Framework abstraction of a "auto-scale-ing font spec" 
// for display/display context/output operations that produce 
// text output that dynamically re-scales to fit the minimum
// vertical or horizontal dimension of the current client 
// display area.
//

//--------------------------------------------------------------------
// 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>
            // defines typedefs for this charting framerowk...

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

class       cf_2DRect;
#include    <cf_api/c0_dimen.hpp>

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

class       bf_FontSpec;
class       bf_Font;
#include    <cf_api/b0_fonts.hpp>
            //
            // Note that this class is NOT dependent upon the 
            // base framework classes -- it uses only specifiers 
            // and types from the "bf_*.hpp" files.
            //


// Define scope-wide "color constants" to be used as bf_Color() params:
const bf_Color c_bf_clrBlack = CF_BLACK;
const bf_Color c_bf_clrWhite = CF_WHITE;

// Avoid Magic Numbers dispersed in the code body of ps_asfon.cpp!
// (note that we do NOT use "const doubles", because that will
// sometimes generate compiler warnings about "declared/unused vars")
#define C0_TATB_PCT_FONT_TO_RECT       5.0
        // Empirically determined for good results on typical VGA

#define C0_TATB_PCT_WIDTH_TO_HEIGHT    45.0
        // Default c-tor initialization ratio of font width 
        // to font height -- fonts look "good" at this ratio.

#define C0_TATB_DISP_VH_RATIO          1.33333333
        // I.e. this is the ratio of vertical to horizontal 
        // pixels in typical VGA monitors (i.e. 640/480 or 
        // 1024/768 ).  ( Note that this is also happens to 
        // be "mathematically" the "golden ratio" used in 
        // architecture, etc. Makes you go...  "hmmmmm..." )

#define C0_TATB_DEFAULT_SCALE_FAC      400.0
        // Used as a division factor against projected rectangle
        // dimensions to yield auto-scaled font dinensions.

//--------------------------------------------------------------
// Declare a Chart Framework "Auto-Scale Font Spec" class.
//
// Class cf_AutoScaleFontSpec WANTS to be derived from, but
// really HAS to encapsulate the zFontSpec class to add the
// capability of "AutoScale"ing to fit (by a percentage) a
// minimum vertic. or horiz. dimension of a given "display".
//--------------------------------------------------------------
class CF_EXPORT   cf_AutoScaleFontSpec 

{

public:

    cf_AutoScaleFontSpec(   bf_FontSpec    *p_bf_fspInitialFontSpec,
                            bf_Color       bf_clrInitialTextColor
                                            = c_bf_clrBlack,
                            bf_Color       bf_clrInitialBackColor
                                            = c_bf_clrWhite    );
            // A cf_AutoScaleFontSpec encapsulates a regular "base
            // class" bf_FontSpec, but has additional members and
            // controls to scale and control the rendering of the
            // base font spec to "auto-scale" to match a percentage
            // of the MINIMUM of the height or width of a given display.
            // In other words, as the client window area is resized by
            // user interaction, this ASFS ("Auto-Scaling" Font Spec)
            // "resizes" itself to stay in proportion to the client
            // area.  This is a highly desirable feature for the display
            // of titles, tick marks, etc.
            // Use this ctor to set up a cf_AutoScaleFontSpec from a
            // base-class-mapping bf_FontSpec and some initial color
            // display attributes.  The default initial state will be
            // to Auto-Scale -- after all, that's why we've made this
            // class in the first place!

    cf_AutoScaleFontSpec();
            // This default ctor is neccessary because some ctors
            // (either within the class hierarchy, or general user
            // classes), will need a default version of this ctor for
            // use in THEIR ctors.  This default ctor to set up a ASFS
            // with this BASE font spec: "SystemVariable 10pt high
            // by 5pt wide -- black text on white background".  Auto-
            // Scaling will be set ON (TRUE) -- after all, that's why
            //  we've made this class in the first place!

    ~cf_AutoScaleFontSpec();    // Std d-tor.


    bf_FontSpec
            calcFontSpec( bf_Display *p_bf_dspOutputDisplay );
            //  Returns either the Auto-Scaled bf_FontSpec OR the
            //  BASE bf_FontSpec for this cf_AutoScaleFontSpec --
            //  depending on which way the user has called autoScale().
            //  (Note that the ctor sets Auto-Scaling ON by default! )
/*
    void    displayAtAngle( bf_Display *p_bf_dspOutputDisplay,
                            int         iAngleInClockwiseDegrees );
            // Allow users to specify a "rotation" -- applied to both
            // Escapement AND orientation angles -- for this ASFS.
  */

    void    preferFontToProjRectPct( double dNewVal );
            // A Good Default is C0_TATB_PCT_FONT_TO_RECT = approx 4% to 5%.

    double  preferFontToProjRectPct();
            // Set/get the auto-scaling size of the font to a
            // percentage of the MINIMAL dimension (vertical OR
            // horizontal) of the active display.

    void    preferWidthToHeightPct( double  dNewVal );
            // A Good Default is C0_TATB_PCT_WIDTH_TO_HEIGHT = approx 45% to 50%.

    double  preferWidthToHeightPct();
            // Set/get the horizontal-to-vertical dimensions of the
            // font spec as a percentage of font width-to-height.

    void    setupScaleFactor( double dNewVal );
    double  setupScaleFactor();
            // Get/set division factor against projected rectangle
            // dimensions to yield auto-scaled font dinensions.
            // For expert use only! "Normal" users should rely on
            // c-tor init value of C0_TATB_DEFAULT_SCALE_FAC.

    void    setupVHRatio( double dNewVal );
    double  setupVHRatio();
            // Get/set the ratio of vertical to horizontal pixels
            // (e.g. for typical VGA monitors == 640/480 or 1024/768 ).
            // For expert use only! "Normal" users should rely on
            // c-tor init value of C0_TATB_DISP_VH_RATIO.

    void    useBoundingRect( cf_2DRect cf_2drUseThisRect );
    void    useDisplayRect( BOOL bNewState );
            //  Set the mode of the AutoFontSpec calc to use a source
            //  rectangular dimension to auto-scale the font scale
            //  against as one of the following:
            //  (1) useBoundingRect() -- a bounding 2D-rectable
            //  specified by a cf_2DRect; (2) useDisplayRect()
            //  -- use the current client area, i.e. the current
            //  bf_Display*->dsp_getVisible( cf_2DRect& ).
            //
            //  ALMOST ALL user classes will want to auto-scale the
            //  font spec output dimensions against the current client
            //  display area, while SOME "exotic" classes, MIGHT want
            //  to scale font spec output dimensions against the
            //  projected rectangular area of a 3D chart face.

    BOOL    useDisplayRectIs();
            //  Allow users to query (if they have forgotten)
            //  whether or not they are auto-scaling from the
            //  current client display area or not. (If they are NOT
            //  then they must be auto-scaling from a rectangular
            //  region passed in an earlier useBoundingRect( zRect )
            //  call.) Remember, this state var has meaning ONLY IF
            //  cf_AutoScaleFontSpec::autoScale( TRUE ) has been
            //  called -- fortunately, this IS the default c-tor
            //  initialization.

protected:

    // We'd LIKE to derive from bf_FontSpec as a base class,
    // but the lack of operators and members in some of the
    // base framework classes precludes this -- so we'll
    // encapsulate the zFontSpec class instead:
    bf_FontSpec    bf_fspBaseFontSpec;

    // We'll also be able to set this zFontSpec for a rotated angle:
    int         iOrientationAngle;
    int         iEscapementAngle;   //
                                    // In 10ths of a degree
                                    //
    // The choice of whether to use the base "fixed" zFontSpec,
    // or the AutoScaleFontSpec scaled to the current zDisplay
    // size MUST be available to the user:
    BOOL        bDoWeAutoScaleFontSpec;

    //
    // A "Bounding Rectangle" Dimension is the dimensioning param that
    // the zFontSpec will be scaled to.
    //
    // The "Normal" mode of operation will be to use a Bounding
    // Rectangle determined by a call to a zDisplay*
    // ->getVisible( zRect ) member.  This is the most useful mode
    // for classes like "3D Grid/Tick-Series", etc to use, and is
    // the DEFAULT mode.
    //
    // A Second mode is used by derived classes such as "3D-Text-Lines",
    // which need a bounding rectangle that is NOT the size of the
    // zDisplay*->getVisible( zRect ). (e.g. "3D-Text-Lines" that are
    // used as back wall titles need a bounding rectangle equivalent
    // to the projected size of the back face.)
    //
    // The modes are switched by calls to the members
    // cf_AutoScaleFontSpec::useBoundingRect( zRect ) or
    // cf_AutoScaleFontSpec::useBoundingRect( zDimension ) or
    // cf_AutoScaleFontSpec::useDisplayRect().
    // 
    cf_2DRect          cf_2drBoundingRect;
    BOOL                bGetDimensionsFromDisplay;

    //
    // The AutoScaleFactor(s) control how much (a Percentage) of
    // the Bounding Rectangle's dimension(s) the FontSpec will 
    // Auto-Scale to.
    //
    // The Default Values were determined empirically,
    // on VGA at Std and High Resolution.
    //
    double  dPctFontDimToProjDim;
            // C-tor inits = C0_TATB_PCT_FONT_TO_RECT
            
    double  dPctFontWidthToHeight;
            // C-tor inits = C0_TATB_PCT_WIDTH_TO_HEIGHT

    double  dSetupVHRatio;
            // C-tor inits = C0_TATB_DISP_VH_RATIO
            
    double  dSetupScaleFactor;
            // C-tor inits = C0_TATB_DEFAULT_SCALE_FAC

};  //
    // End of cf_AutoScaleFontSpec declaration.
    //



class CF_EXPORT   cf_TextAttribs
        : public cf_AutoScaleFontSpec
{

public:

    cf_TextAttribs();

    cf_TextAttribs( bf_Color    bf_clrTextForeground,
                    bf_Color    bf_clrTextBackground );

    ~cf_TextAttribs();


    //------------------------------------------------
    // Methods to manipulate Base Font-Spec Rotation:
    //------------------------------------------------
    void        angleRotationPrefer( int iAngleInClockwiseDegrees );
                // Set the "orientation" and "escapement" angles
                // for the embedded font-spec, in clockwise degrees.

    int         angleRotationDegrees();
    double      angleRotationRadians();
                // Get the orientation and/or escapement angle (in
                // clockwise degrees or converted to radians).



    BOOL    autoScale();
    void    autoScale( BOOL bNewState );
            // Get/set Auto-Scaling status/state ON or OFF,
            // corresponding to BOOL TRUE or FALSE values.

    bf_FontSpec*   baseFontSpec();
    void    baseFontSpec( bf_FontSpec  *p_bf_fspNewFontSpec );
            // Get/set the Base Font Spec for this ASFS. Enables
            // "Font Selection Dialogs" etc., which operate from
            // "pointers to Font Specs"...  Note that in the
            // baseFontSpec( bf_FontSpec* ) member method, a
            // VALUE copy of the bf_FontSpec* parameter is
            // performed, because this cf_AutoScaleFontSpec object
            // cannot know the scope of the bf_FontSpec* parameter.

    //------------------------------------------
    // Methods to control Auto-Scaling Behavior:
    //------------------------------------------
    void        autoScalePercent( double dUsingMinimumChartDimensionXY );
    double      autoScalePercent();
                // Set/get the auto-scaling size of the font to a percentage
                // of the MINIMAL dimension (vertical OR horizontal) of the
                // parent chart's 2D/3D-Box.  Typical settings range from
                // 0.04 to 0.06 (i.e 4 to 6 percent).


    //----------------------------------------------
    // Methods to manipulate Text-Attrib Color(s):
    //----------------------------------------------
    bf_Color    colorTextFore();
    BOOL        colorTextFore( bf_Color bf_clrNew );

    bf_Color    colorTextBack();
    BOOL        colorTextBack( bf_Color bf_clrNew );
                // Get/set text/text-background colors for these text-attribs.


    //------------------------------------------------
    // Methods to manipulate String Output Format(s):
    //------------------------------------------------
    cf_String   formatNumPrefer();
    void        formatNumPrefer( const char *a_cSprintfFormatString );
                // C-tor will init a numerical format string to "%g".
                // Use this method to get/set this format string to your
                // preferred sprintf(...) format spec, e.g. %2.2g", etc.



    //------------------------------------------------------
    // Methods to manipulate Text-Attrib Position-Shift(s):
    //------------------------------------------------------
    void        shiftVertUp();
    BOOL        shiftVertUpIs();

    void        shiftVertDown();
    BOOL        shiftVertDownIs();

    void        shiftVertCtr();
    BOOL        shiftVertCtrIs();

    void        shiftHorzLeft();
    BOOL        shiftHorzLeftIs();

    void        shiftHorzRight();
    BOOL        shiftHorzRightIs();

    void        shiftHorzCtr();
    BOOL        shiftHorzCtrIs();

    void        staggerUpDown();
    BOOL        staggerUpDownIs();

    void        staggerDownUp();
    BOOL        staggerDownUpIs();
                // Can be used to spec the shift of the render position of
                // any given text relative to any given projection text-point.


private:

    void        ctorInit();

    bf_Color    bf_clrTextForeground_;
    bf_Color    bf_clrTextBackground_;

    //---------------------------------------------------------------
    // Positioning Vars -- i.e. where do we place the output text?
    //---------------------------------------------------------------
    BOOL        bHorizShiftLeft_;       // Ctor inits = FALSE
    BOOL        bHorizShiftRight_;      // Ctor inits = FALSE
    BOOL        bHorizCentered_;        // Ctor inits = TRUE

    BOOL        bVertShiftUp_;          // Ctor inits = FALSE
    BOOL        bVertShiftDown_;        // Ctor inits = FALSE
    BOOL        bVertCentered_;         // Ctor inits = TRUE

    BOOL        bStaggerUpDown_;        // Ctor inits = FALSE
    BOOL        bStaggerDownUp_;        // Ctor inits = FALSE
                // The default POSITIONING of any output TEXT BOX is CENTERED
                // (vertically AND horizontally ) at any given screen-point.
                // However, this can be toggled to Shift the Draw Point to
                // any of the Text Box's four corners, or the Center Point,
                // with the shiftVert() and/or shiftHorz() methods above:

    cf_String   cf_strPreferredNumFormat_;
                // Use to format numerical items per standard sprintf(...)
                // usage.  Typically set to "%g" by the c-tor...


};  // end of class cf_TextAttribs decleartion


#endif      // Terminates include re-definition protection

//////////////////////////////////////
// END of File: C0_TATB.HPP
//////////////////////////////////////

