/////////////////////////////////////////
// START of File: C1_XYZ.HPP
/////////////////////////////////////////

#ifndef C1_XYZ_HPP          // Avoid multiple includes...
#define C1_XYZ_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/c1_xyz.hpp>
// Chart Framework 3D "Cartesian Coordinate Triplet Value" 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/bf_defs.h>
            // Base-Framework-Assumed typedefs and consts...
            
#include    <cf_api/cf_const.h>
            // Platform-Independent Chart Framework constants...

class       cf_String;
#include    <cf_api/c0_dystr.hpp>
            // Mapping onto base framework "dynamic string" object(s)...

// 
//-----------------------------------------------------------
// Declare a Chart Framework "3D XYZ" class.  This class 
// describes the attributes and operations for an abstract 
// set of 3D coordinates.
//
// It is important to realize that this class does NOT 
// know about any other Chart Framework classes (e.g. 
// 3D-Point, 3D-PolyLine, etc.) even though it is designed 
// to be used by them (as their data repository).
//-----------------------------------------------------------
// 
class CF_EXPORT   cf_XYZ 

{

public:

    cf_XYZ();   // Default c-tor is important for dynamic arrays

    cf_XYZ( double dInitX, double dInitY, double dInitZ  );
                // Standard c-tor lets users specify object's data state.

    ~cf_XYZ();  // Standard (non-virtual) D-tor
    
    cf_XYZ      operator=( const cf_XYZ& cr_cf_xyzUserVal );
                // Fulfills obvious need for equaltiy assignment op.
    
    cf_XYZ      operator+( const cf_XYZ& cr_cf_xyzUserVal );
                // Functions as a "coordinate translation" op.
    
    cf_XYZ      operator*( const cf_XYZ& cr_cf_xyzUserVal );
                // Functions as a "coordinate scaling" op.

    void        assign( double dNewX, double dNewY, double dNewZ );
                // "Set member value" method

    BOOL        inUse();
    void        inUse( BOOL bNewState );
                // Some user objects will want to mark this XYX 
                // triplet as being "in-use" or "not-in-use".

    cf_String*  labelIs();
                // Get a ptr to our XYZ's "dynamic string" label.
    
    void        labelNew(   const char      *ca_cStringForNewLabel );

    void        labelNew(   const double    cdValueForNewLabel,
                            const char      *ca_cFormatString = "%g" );

    void        labelNew(   const int       ciValueForNewLabel,
                            const char      *ca_cFormatString = "%d" );
                // Sets (and allocates) an (optional) label for the
                // data point from a const array of chars in a
                // null-terminated string, or a data value (that
                // gets turned into a string).  Data-value-conversion
                // methods have optional sprintf()-like format specifiers.

    BOOL        labelSet();
                // Queries to see if label was ever set (and allocated).

    void        labelUsing( cf_String *p_cf_strSomeoneElsesLabel ); 
                // "Borrow" a pointer to another object's dynamic
                // string to use as a label.  "Taget" object (typically
                // a "data model/data group" MUST take care NOT to delete
                // the "someone else's label" string and then have this
                // object try to reference it -- doohhpp !!!...

    double      x();
    double      y();
    double      z();
                // "Get member values" methods

private:

    double  dX, dY, dZ;
                //
                // X, Y, & Z Coords, which can be manipulated 
                // by the member functions and operators above
                //

    cf_String   *p_cf_strLabel;    // C-tor inits to NULL.
    BOOL        bWasLabelNewed;     // C-tor inits to FALSE.
    BOOL        bWasLabelSet;       // C-tor inits to FALSE.
                // An optional labels for the data point -- used 
                // for things like generating tick marks, etc...
                // Subsequent labelIs(...), etc. calls will cause 
                // storage/allocation and value (re)settings.

    BOOL        bInUse;     // C-tor inits to TRUE.
                // User objects will need to have the ability to
                // mark whether or not this data value is "in-use"

};  // End of cf_XYZ declaration.

#endif      // Terminates include re-definition protection

/////////////////////////////////////////
// END of File: C1_XYZ.HPP
/////////////////////////////////////////

