gls_text.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsText class.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef _GLS_TEXT_H
#define _GLS_TEXT_H

#include "unhide_globals.h"

#include "gls_gl.h"
#include <string>

#include "glpolygon.h"
#include "gls_color.h"
#include "gls_cpp_lang_support.h"
#include "gls_font_base.h"
#include "gls_font_man.h"
#include "gls_metadata_attributes.h"
#include "gls_runtime_font_base.h"
#include "gls_unicode_font_base.h"
#include "scoped_ptr.h"

//===========================================================================
//                             MACROS
//===========================================================================
#ifdef GLES
#    define GLS_TEXT_SET_GEOMETRY_REFRESH GeometryRefresh();
#else
#    define GLS_TEXT_SET_GEOMETRY_REFRESH
#endif

#define SET_ALL_CHARS( attribute, value )                                          \
    {                                                                              \
        for( CharAttrCont_t::iterator i = _chars.begin(); i != _chars.end(); ++i ) \
        {                                                                          \
            i->attribute = value;                                                  \
        }                                                                          \
        GLS_TEXT_SET_GEOMETRY_REFRESH                                              \
    }

//===========================================================================
//                         BEGIN NAMESPACE
//===========================================================================
namespace disti
{
#ifdef GLES
// Forward Declaration
class GlsGloFileAttribute;
#endif

// Forward Declaration
class RuntimeGlyphGenerationText;

// Initializers for text
typedef enum
{
    GLS_TEXT_BORDER = GLS_LAST_INITIALIZER + 1,
    GLS_TEXT_CELL_HEIGHT,
    GLS_TEXT_CELL_WIDTH,
    GLS_TEXT_CONSTRAIN_CELL_RATIO,
    GLS_TEXT_CONTROL_CELL_SIZE,
    GLS_TEXT_FONT,
    GLS_TEXT_HALO,
    GLS_TEXT_LINESPACING,
    GLS_TEXT_LOCK_CELL_SIZE,
    GLS_TEXT_JUSTIFY,
    GLS_TEXT_SHADOW,
    GLS_TEXT_STRING,
    GLS_TEXT_UPPERCASE,
    GLS_TEXT_WRAP,
    GLS_LAST_TEXT_INITIALIZER = GLS_TEXT_WRAP
} GlsTextInitializers_t;

/** helper method for safely getting a runtime font base from a font base (if possible)
  * \param font font in question
  * \return runtime font else NULL
  */
inline GlsRuntimeFontBase* GetGlsRuntimeFontBase( const GlsFontBase* font )
{
    GlsRuntimeFontBase* rtf = NULL;
    if( font )
    {
        // determine if font can be safely cast to a runtime font by inspecting the family name
        if( 0 == font->Family().find( GLS_RUNTIME_FONT_NAME_PREFIX ) )
        {
            rtf = static_cast<GlsRuntimeFontBase*>( (GlsFontBase*)font );
        }
    }
    return ( rtf );
}

/** helper method for safely getting a unicode font base from a font base (if possible)
  * \param font font in question
  * \return unicode font else NULL
  */
inline const GlsUnicodeFontBase* GetGlsUnicodeFontBase( const GlsFontBase* font )
{
    const GlsUnicodeFontBase* unf = NULL;
    if( font )
    {
        // determine if font can be safely cast to a unicode font by inspecting the family name
        if( 0 == font->Family().find( GLS_UNICODE_FONT_NAME_PREFIX ) )
        {
            unf = static_cast<const GlsUnicodeFontBase*>( font );
        }
    }
    return ( unf );
}

//===========================================================================
/**
* The GlsText class provides a base class for all GLStudio text components.
*/
//===========================================================================
class GlsText : public GLPolygon
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef GLPolygon _BaseClass;
    typedef GLPolygon BaseClass;

    typedef GlsFontBase::Char_t Char_t;

    // Carriage return (end of line) character
    static GLS_EXPORT const Char_t EOL;

    enum
    {
        NUM_VERTICES = 4
    };

    /// Different text justifications.
    enum Justify_t
    {
        LEFT,
        CENTER,
        RIGHT
    };

    /// Attributes for each character position in the grid.
    struct CharAttr_t
    {
        Char_t   code;
        float    baselineShift;
        GlsColor bgColor;
        GlsColor fgColor;
        bool     fauxBold;
        bool     inverse;
        float    scale;
        float    spacing;
        bool     strikeThru;
        bool     underline;

        //----------------------------------------------------------------------
        GLS_EXPORT CharAttr_t();

        //----------------------------------------------------------------------
        GLS_EXPORT CharAttr_t( const CharAttr_t& r );

        //----------------------------------------------------------------------
        GLS_EXPORT void Clear();

        //----------------------------------------------------------------------
        GLS_EXPORT CharAttr_t& operator=( const CharAttr_t& r );
    };

#ifndef WIN32

    /** helper class that enables use of basic_string< unsigned short > on unix
      * \see std::char_traits
      */
    struct CharTraitsUnsignedShort
    {
        typedef unsigned short char_type;
        typedef int            int_type;
        typedef std::streampos pos_type;
        typedef std::streamoff off_type;
        typedef std::mbstate_t state_type;

        static void assign( char_type& c1, const char_type& c2 )
        {
            c1 = c2;
        }

        static bool eq( const char_type& c1, const char_type& c2 )
        {
            return c1 == c2;
        }

        static bool lt( const char_type& c1, const char_type& c2 )
        {
            return c1 < c2;
        }

        static int compare( const char_type* s1, const char_type* s2, size_t n )
        {
            if( n == 0 )
            {
                return ( 0 );
            }
            do
            {
                if( *s1 != *s2++ )
                {
                    return ( *s1 - *( s2 - 1 ) );
                }
                if( *s1++ == 0 )
                {
                    break;
                }
            } while( --n != 0 );
            return ( 0 );
        }

        static size_t length( const char_type* s )
        {
            size_t x = 0u;
            while( *s++ )
            {
                ++x;
            }
            return ( x );
        }

        static const char_type* find( const char_type* s, size_t n, const char_type& a )
        {
            while( n-- > 0 )
            {
                if( *s == a )
                {
                    return s;
                }
                s++;
            }
            return NULL;
        }

        static char_type* move( char_type* s1, const char_type* s2, size_t n )
        {
            return static_cast<char_type*>( memmove( s1, s2, n * sizeof( char_type ) ) );
        }

        static char_type* copy( char_type* s1, const char_type* s2, size_t n )
        {
            return static_cast<char_type*>( memcpy( s1, s2, n * sizeof( char_type ) ) );
        }

        static char_type* assign( char_type* s, size_t n, char_type a )
        {
            for( size_t idx = 0u; idx < n; ++idx )
            {
                s[ idx ] = a;
            }
            return ( s );
        }

        static char_type to_char_type( const int_type& c )
        {
            return static_cast<char_type>( c );
        }

        static int_type to_int_type( const char_type& c )
        {
            return static_cast<int_type>( c );
        }

        static bool eq_int_type( const int_type& c1, const int_type& c2 )
        {
            return c1 == c2;
        }

        static int_type eof()
        {
            return static_cast<int_type>( EOF );
        }

        static int_type not_eof( const int_type& c )
        {
            return ( c == eof() ) ? 0 : c;
        }
    };

    typedef std::basic_string<unsigned short, CharTraitsUnsignedShort> UnicodeString;

#else

    typedef std::wstring UnicodeString;

#endif

    /** Class Constructor. */
    GLS_EXPORT GlsText();
    GLS_EXPORT GlsText( const GlsText& that, const bool generateNames );

    /** Class Constructor. */
    GLS_EXPORT virtual ~GlsText();

    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value );

    /** Sets the baseline shift for all characters.
      * \param baselineShift  multiplier used to shift the baseline. This will
      *                       be multiplied by the character height to 
      *                       determine how much to shift. A value of 0 does
      *                       not shift at all, a value of 1 will shift up
      *                       by the height of 1 character.
      */
    GLS_EXPORT void Baseline( const float& baselineShift );

    /** Gets the baseline shift for the first character
      */
    GLS_EXPORT float Baseline();

    /** Sets the background color for all characters
      * \param color  The background color to set
      */
    GLS_EXPORT void BgColor( const GlsColor& color );

    /** Gets the background color for the first character
      */
    GLS_EXPORT GlsColor BgColor();

    /** Sets the spacing between the box outline and the text in logical units.
      * \param units  Border offset value in logical units
      */
    GLS_EXPORT void Border( const float& units );

    /** Sets the spacing between the box outline and the text in logical units.
      */
    float Border() const
    {
        return _border;
    }

    /** Sets the height of a character cell of the grid in logical units 
      * when stretch to fit mode is in effect.  When stretch to fit mode
      * is not in effect, this call will not affect the grid since the
      * font determines the cell size.
      * \param height the new character cell height.
      */
    GLS_EXPORT void CellHeight( float height );

    /** \return the height of a char cell of the grid in logical units.
      */
    float CellHeight() const
    {
        return _cellHeight;
    }

    /** Sets the width of a character cell of the grid in logical units 
      * when stretch to fit mode is in effect. When stretch to fit mode
      * is not in effect, this call will not affect the grid since the
      * font determines the cell size.
      * \param width the new character cell width.
      */
    GLS_EXPORT void CellWidth( float width );

    /** \return the width of a char cell of the grid in logical units. */
    float CellWidth() const
    {
        return _cellWidth;
    }

    /** Sets the character code for all cell positions in the text grid
      * \param code  The ASCII character code to set
      */
    GLS_EXPORT void Char( Char_t code );

    /** Accessor method used by metadata to read and write the character attributes
      * for this object.  Currently only allows you to load and save attributes for the
      * entire object, not on a per character basis.
      * \return  The character attribute for the first character in the object and therefore
      *          for every character in the object
      */
    CharAttr_t CharAttribs() const
    {
        return _chars[ 0 ];
    }

    /** \return a particular cell's character attributes. */
    CharAttr_t CharAttr( unsigned int index ) const
    {
        return _chars[ index < _chars.size() ? index : 0 ];
    }

    /** Sets the scale factor of all characters  NOTE:  This is the size of the character in its
      * cell not the overall scale of the entire object
      * \param newScale  The new scale factor of the characters (0.0 < newScale <= 1.0)
      */
    GLS_EXPORT void CharScaling( const float& newScale );

    /** Gets the scale factor of the first character
      */
    GLS_EXPORT float CharScaling();

    /** Sets the horizontal character spacing for all characters (spacing 
      * from the start of one character to the start of the next character.
      * 1.0 is the default spacing 2.0 would be twice the normal spacing
      * \param horizontalSpacing  The horizontalSpacing value
      */
    GLS_EXPORT void CharSpacing( const float& horizontalSpacing );

    /** Gets the horizontal character spacing for the first character
      */
    GLS_EXPORT float CharSpacing();

    /** Sets whether to constrain cell width and height proportions when
      * in stretch to fit mode and changing the size of character cells.
      * \param constrain true to constrain proportions.
      */
    GLS_EXPORT void ConstrainCellRatio( bool constrain );

    /** \return whether to constrain cell width and height proportions when
      * in stretch to fit mode and changing the size of character cells.
      */
    bool ConstrainCellRatio() const
    {
        return _constrainRatio;
    }

    /** Sets whether or not the character cell size will stretch to fit 
      * this object's bounding box or if it is based on its font and font.
      * \param control  True if stretch to fit will be enabled
      */
    GLS_EXPORT void ControlCellSize( bool control );

    /** \return whether or not the character cell size will stretch to fit 
      * this object's bounding box or if it is based on its font and font 
      */
    bool ControlCellSize() const
    {
        return _controlCellSize;
    }

    /* See base class */
    GLS_EXPORT virtual void CopyGeometry( DisplayObject* src );

    /* See base class */
    GLS_EXPORT virtual void CopyProperties( DisplayObject* src );

    /** Erase all characters. */
    GLS_EXPORT void Erase();

    /** Set the bold state on or off for all characters
      * \param bold  Bold state
      */
    GLS_EXPORT void FauxBold( const bool& bold );

    /** Gets the bold state on or off for the first character
      */
    GLS_EXPORT bool FauxBold();

    /** \return The font currently being used to render this text.
      */
    GlsFontBase* Font() const
    {
        return _font;
    }

    /** Set the font used to render this text.
      * \param font  Pointer to a font instance to set
      */
    GLS_EXPORT void Font( GlsFontBase* font );

#ifndef GLES
    /* See base class */
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription(
        InterfaceListType* addToThisList = NULL );

    /* See base class */
    virtual GLS_EXPORT void GetCppInterfaceDescriptionFree(
        InterfaceListType* array );
#endif

    /** Set the halo state to on or off for the text
      * \param halo  halo state
      */
    GLS_EXPORT void Halo( bool halo );

    bool Halo() const
    {
        return _halo;
    }

    /** Set the color of the halo around the text
      * \param color  halo color
      */
    GLS_EXPORT void HaloColor( const GlsColor& color );

    GlsColor HaloColor() const
    {
        return _haloColor;
    }

    /** Invalidates the font for this object.  If the font is invalidated, this object will
      * draw using the default font.  This is used in the editor and should not need to
      * be called by any user code at run-time.
      */
    GLS_EXPORT void InvalidateFont();

    /** Set the inverse video state on or off for all characters
      * \param inverse  inverse video state
      */
    GLS_EXPORT void Inverse( const bool& inverse );

    /** Gets the inverse video state on or off for the first character
      */
    GLS_EXPORT bool Inverse();

    /** Set the justification mode for this text object
      * \param justification The justification mode (LEFT, RIGHT, CENTER)
      */
    GLS_EXPORT void Justify( Justify_t justification );

    /** \return the justification mode (LEFT, RIGHT, CENTER)*/
    Justify_t Justify() const
    {
        return _justify;
    }

    /** Sets the linespacing for the text object.  A line spacing of 1.0 indicates normal
      * "single spaced" text.  2.0 would be double spaced, etc.
      * \param spacing  The new linespacing value
      */
    GLS_EXPORT void LineSpacing( float spacing );

    /** \return the linespacing for the text object. */
    float LineSpacing() const
    {
        return _lineSpacing;
    }

    /** Sets whether or not the cell size is locked while in stretch to fit
      * mode. If locked, changing other attributes will not affect the
      * cell size, but the box size instead.  If not locked, changing
      * certain attributes, eg. border, will affect the cell size.
      * \param lock  true to lock cell size, false otherwise
      */
    GLS_EXPORT void LockCellSize( bool lock );

    /** \return the setting of lock cell size. */
    bool LockCellSize() const
    {
        return _lockCellSize;
    }

#if !defined( GCC_2_95 )
    /* Unhides base class implementation. */
    using BaseClass::Rotate;
#endif

    /* See base class */
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis );

    /* See base class */
    virtual GLS_EXPORT void SetValue( int spec, va_list& args );

#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLS_EXPORT void SetFromGloData( GlsGloFileAttribute& data );
#endif

    /** Set the shadow state to on or off for the text
      * \param shadow  shadow state
      */
    GLS_EXPORT void Shadow( bool shadow );

    bool Shadow() const
    {
        return _shadow;
    }

    /** Set the color of the shadow behind the text
      * \param color  shadow color
      */
    GLS_EXPORT void ShadowColor( const GlsColor& color );

    GlsColor ShadowColor() const
    {
        return _shadowColor;
    }

    /** Set the distance of the shadow from the text. Distance represent a percentage of the character
     * width. Negative values are up and to the left. Positive values are down and to the right.  Note that the
     * corresponding getter was removed because ShadowDistance is deprecated in favor of ShadowOffset.
     * \param dist  shadow distance
     */
    void ShadowDistance( const float& dist )
    {
        ShadowOffset( Vector( dist, -dist, 0.0f ) );
    }

    /** Set the Cartesian offset of the shadow from the text. Offset represent a percentage of the character
     * width. Negative values are down and to the left. Positive values are up and to the right.
     * Z component is ignored.
     * \param offset  shadow offset
     */
    GLS_EXPORT void ShadowOffset( const Vector& offset );

    Vector ShadowOffset()
    {
        return _shadowOffset;
    }

    /** Sets the strikethru state for all characters
      * \param strike Whether or not set strikethru
      */
    GLS_EXPORT void StrikeThru( const bool& strike );

    /** Gets the strikethru state for the first character
      */
    GLS_EXPORT bool StrikeThru();

    /** Sets the ASCII string to be displayed for this object
      * \param s STD Template Library String
      */
    GLS_EXPORT void String( const std::string& s );

    /** Sets the ASCII string to be displayed for this object
      * \param s C Style string
      */
    void String( const char* s )
    {
        String( std::string( s ) );
    }

    /** \return The string currently stored in this object.
      *         NOTE: This can contain extra characters not being displayed
      *               in the grid if the string size is greater than will 
      *               fit within the grid.  
    */
    std::string String() const
    {
        return _text;
    }

    /** Sets the foreground color for all characters in the text grid.
      * \param color  The foreground color to set
      */
    GLS_EXPORT void TextColor( const GlsColor& color );

    /** Gets the foreground color for the first character in the text grid.
      */
    GLS_EXPORT GlsColor TextColor();

    /** Turns on/off underlines for all characters
      * \param underline  Whether or not to enable underline
      */
    GLS_EXPORT void Underline( const bool& underline );

    /** Gets the on/off state of underline for the first character
      */
    GLS_EXPORT bool Underline();

    /** Makes all characters uppercase when rendered.
      * \param uppercase  Whether or not to enable uppercase
      */
    GLS_EXPORT void Uppercase( bool uppercase );
    bool            Uppercase() const
    {
        return _uppercase;
    }

    /** Enable/disable word wrap behavior for this object
      * \param wrap  Whether or not to enable word wrap
      */
    GLS_EXPORT void WrapText( bool wrap );

    /** \return current word wrap behavior for this object */
    bool WrapText() const
    {
        return _wrapText;
    }

    /** Sets the rebuild flag, which forces the text object to rebuild itself on the next call to Calculate, PreDraw, or Draw. */
    void SetRebuild()
    {
        _needToRebuild = true;
        InvalidatePainter();
    }

    /** whether or not this text object requires a font file to work.  If this returns true, the text object may not work with the generated ASCII / UNICODE font types */
    virtual bool RequiresFontFile() const
    {
        return false;
    }

public: // protected is prefered, but VC 7.0 has issues with it.
    /** Line Segment_t */
    class LineSegment_t
    {
    public:
        float    x1;
        float    x2;
        float    y;
        float    thickness;
        float    shadowOffsetX;
        float    shadowOffsetY;
        GlsColor color;

        LineSegment_t()
            : x1( 0.0f )
            , x2( 0.0f )
            , y( 0.0f )
            , thickness( 0.0f )
            , shadowOffsetX( 0.0f )
            , shadowOffsetY( 0.0f )
        {
        }

        LineSegment_t(
            const float     segmentX1,
            const float     segmentX2,
            const float     segmentY,
            const float     segmentThickness,
            const float     segmentShadowOffsetX,
            const float     segmentShadowOffsetY,
            const GlsColor& segmentColor )
            : x1( segmentX1 )
            , x2( segmentX2 )
            , y( segmentY )
            , thickness( segmentThickness )
            , shadowOffsetX( segmentShadowOffsetX )
            , shadowOffsetY( segmentShadowOffsetY )
            , color( segmentColor )
        {
        }
    };

protected:
    typedef std::vector<CharAttr_t> CharAttrCont_t;

    static GLS_EXPORT const Vector XAXIS;
    static GLS_EXPORT const Vector YAXIS;

    static GLS_EXPORT Vertex INITIAL_VERTICES[ NUM_VERTICES ];

    /** The border offset in logical units for this object. 
      * Defines the size of the empty space between the outline of the box
      * and its text 
      */
    float _border;

    /** Container of character attributes */
    CharAttrCont_t _chars;

    Vertex _currentVertices[ NUM_VERTICES ];

    /** Height of each character cell in the grid in logical units */
    float _cellHeight;

    /** Width of each character cell in the grid in logical units */
    float _cellWidth;

    /** Only effective when _controlCellSize is true. Whether or not to 
     * constrain cell size ratio when changing cell height or width. 
     */
    bool _constrainRatio;

    /** If true, font size does not control cell size */
    bool _controlCellSize;

    /** Current font being used for the text */
    GlsFontBase* _font;

    /* Whether or not the halo effect is on. */
    bool _halo;

    /** Color of the halo effect behind the characters */
    GlsColor _haloColor;

    /** Justification setting (LEFT, RIGHT, CENTER) */
    Justify_t _justify;

    /** Line spacing between grid rows as a percentage */
    float _lineSpacing;

    /** Only effective when _controlCellSize is true. If true, changes to
      * rows, columns, border, line spacing, column spacing, etc. will
      * not change the cell size. Normally, when _controlCellSize is true
      * these attributes affect the cell size.
      */
    bool _lockCellSize;

    /** This is set to true whenever an attribute changes that will affect
      * the size of the grid or its cells.  
      */
    bool _needToRebuild;

    /* Whether or not the shadow effect is on. */
    bool _shadow;

    /** Color of the shadow effect behind the characters */
    GlsColor _shadowColor;

    /** Offset of the shadow effect from the characters.  Z component is ignored. */
    Vector _shadowOffset;

    /** String of text to be displayed. */
    std::string _text;

    /** If true, all characters will be displayed in uppercase */
    bool _uppercase;

    /** Direction vector indicating direction of horizontal travel for rendering */
    Vector _vX;

    /** Direction vector indicating direction of vertical travel for rendering */
    Vector _vY;

    /** Normal to the Vx Vy plane */
    Vector _vZ;

    /** Whether or not to word wrap text */
    bool _wrapText;

    //-----------------------------------------------------------------------
    /** 
    * Draw a line by rendering a filled polygon with a line around it so that
    * the thickness scales and anti-aliasing will work if enabled.
    */
    //-----------------------------------------------------------------------
public: // protected is preferred, but VC 7.0 has issues with it.
#ifndef GLES
    static void DrawScalableLine(
        GLfloat x1,  // Left point
        GLfloat y1,  // Top point
        GLfloat x2,  // Right Point
        GLfloat y2 ) // Bottom Point
    {
        // APR: The Text Objects send x1,y1 as TOP-RIGHT. Rewrote glVertex calls to support CCW drawing.
        glBegin( GL_POLYGON );
        glVertex2f( x1, y1 );
        glVertex2f( x1, y2 );
        glVertex2f( x2, y2 );
        glVertex2f( x2, y1 );
        glEnd();
        /*
        glBegin(GL_LINE_LOOP);
            glVertex2f(x1, y1);
            glVertex2f(x2, y1);
            glVertex2f(x2, y2);
            glVertex2f(x1, y2);
        glEnd();
        */
    }
#endif
protected:
    /**
     * Allocate a text buffer of the appropriate size for this grid and output snprintf style format 
     *  into the buffer 
     * \param format snprintf style format spec
     * \param args arguments for sprintf style formatting
     * \param initialBufferLength the length of the initial character buffer
     * \return formatted textbuffer ( must be deleted by caller )
     */
    GLS_EXPORT char* FormatVarArgList( const int initialBufferLength, const char* format, va_list args );

    //-----------------------------------------------------------------------
    /**
    */
    //-----------------------------------------------------------------------
    GLS_EXPORT void RecalcDirectionVectors();

    /** Pointer to the internal data needed for runtime glyph generation. */
    ScopedPtr<RuntimeGlyphGenerationText> _runtimeGlyphGenerationText;

private:
    // Allow derived classes to perform a custom action when cell height/width changes.
    virtual GLS_EXPORT void OnCellDimensionChanged()
    {}

    // Disable copying.
    GlsText( const GlsText& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const GlsText& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

//---------------------------------------------------------------------------
//  Stream operators for text enumeration types
//---------------------------------------------------------------------------
inline std::istream& operator>>(
    std::istream& instr, disti::GlsText::Justify_t& j )
{
    std::string str;
    instr >> str;

    if( str == "LEFT" )
    {
        j = disti::GlsText::LEFT;
    }
    else if( str == "CENTER" )
    {
        j = disti::GlsText::CENTER;
    }
    else if( str == "RIGHT" )
    {
        j = disti::GlsText::RIGHT;
    }
    return instr;
}

//---------------------------------------------------------------------------
inline std::ostream& operator<<( std::ostream& outstr, disti::GlsText::Justify_t j )
{
    switch( j )
    {
    case disti::GlsText::LEFT:
        outstr << "LEFT";
        break;
    case disti::GlsText::CENTER:
        outstr << "CENTER";
        break;
    case disti::GlsText::RIGHT:
        outstr << "RIGHT";
        break;
    }
    return outstr;
}

//===========================================================================
/** 
* Attributes of a text character.
* NOTE: Use of this attribute is deprecated.
* Instead use individual top-level attributes such as ("FauxBold" and "TextColor").
*/
//===========================================================================
class GlsTextCharAttr : public DistiAttributeDictionaryAttribute
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef DistiAttributeDictionaryAttribute _BaseClass;
    typedef DistiAttributeDictionaryAttribute BaseClass;

    GlsTextCharAttr( const AttributeName& name, GlsText* text );

    virtual ~GlsTextCharAttr()
    {
        delete _dict;
    }

    // Do not write out, because this interface is only for backward
    // compatability
    virtual bool OkToWrite() const
    {
        return false;
    }

    virtual std::ostream& WriteValue( std::ostream& outstr )
    {
        _charAttr = _text->CharAttr( 0 );
        return BaseClass::WriteValue( outstr );
    }
    virtual std::istream& ReadValue( std::istream& instr )
    {
        // First get _charAttr to the current value.
        // This is because the instr may not contain
        // new values for all the attributes.
        _charAttr = _text->CharAttr( 0 );

        BaseClass::ReadValue( instr );

        _text->Baseline( _charAttr.baselineShift );
        _text->BgColor( _charAttr.bgColor );
        _text->CharSpacing( _charAttr.spacing );
        _text->TextColor( _charAttr.fgColor );
        _text->FauxBold( _charAttr.fauxBold );
        _text->Inverse( _charAttr.inverse );
        _text->CharScaling( _charAttr.scale );
        _text->StrikeThru( _charAttr.strikeThru );
        _text->Underline( _charAttr.underline );

        return instr;
    }

protected:
    GlsText*            _text;
    GlsText::CharAttr_t _charAttr;
};

} // namespace disti

DISTI_EXPORT std::ostream& operator<<( std::ostream& outstr, const disti::GlsText::CharAttr_t& c );
DISTI_EXPORT std::istream& operator>>( std::istream& instr, disti::GlsText::CharAttr_t& c );

#endif