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
//===========================================================================
/// Macro to refresh geometry in ES, that does nothing on Desktop.
#ifdef GLES
#    define GLS_TEXT_SET_GEOMETRY_REFRESH GeometryRefresh();
#else
#    define GLS_TEXT_SET_GEOMETRY_REFRESH
#endif
 
/// Macro to set a given attribute on all characters with the given value.
#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; ///< Deprecated typedef for the base class.
    typedef GLPolygon BaseClass;  ///< Typedef for the base class.
 
    typedef GlsFontBase::Char_t Char_t; ///< Typedef shorthand for GlsFontBase::Char_t.
 
    static GLS_EXPORT const Char_t EOL; ///< Carriage return (end of line) character
 
    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;          ///< The code point for this character.
        float    baselineShift; ///< The base line shift in pixels.
        GlsColor bgColor;       ///< The background color.
        GlsColor fgColor;       ///< The foreground (glyph itself) color.
        bool     fauxBold;      ///< Whether or not faux bold is enabled.
        bool     inverse;       ///< Whether or not inverse is enabled.
        float    scale;         ///< Scaled size of this character.
        float    spacing;       ///< Scale of spacing between this character.
        bool     strikeThru;    ///< Whether or not strike through is enabled.
        bool     underline;     ///< Whether or not underline is enabled.
 
        GLS_EXPORT CharAttr_t();
 
        /// Copy constructor
        /// \param r The object to copy from.
        GLS_EXPORT CharAttr_t( const CharAttr_t& r );
 
        /// Reset values to their defaults.
        GLS_EXPORT void Clear();
 
        /// Assignment operator
        /// \param r The object to copy from.
        /// \return The resulting object (this).
        GLS_EXPORT CharAttr_t& operator=( const CharAttr_t& r );
    };
 
    /** Class Constructor. */
    GLS_EXPORT GlsText();
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name for this object.
    GLS_EXPORT GlsText( const GlsText& that, const bool generateNames );
 
    /** Class Constructor. */
    GLS_EXPORT virtual ~GlsText();
 
    virtual GLS_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
 
    /** 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 );
 
    /// \return 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 );
 
    /// \return 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 );
 
    /// \return 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 Unicode 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.
    /// \param index The index whose attributes are to be returned.
    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 );
 
    /// \return 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 );
 
    /// \return 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;
    }
 
    GLS_EXPORT virtual void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
    GLS_EXPORT virtual void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
    /** 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 );
 
    /// \return 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
    virtual GLS_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLS_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    /** Set the halo state to on or off for the text
      * \param halo  halo state
      */
    GLS_EXPORT void Halo( bool halo );
 
    /// \return Whether or not the halo is visible.
    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 );
 
    /// \return The current halo 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 );
 
    /// \return 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
    virtual GLS_EXPORT void Rotate( const Vector& orig, float angle, const Vector& axis ) DISTI_METHOD_OVERRIDE;
 
    virtual GLS_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
 
#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 ) DISTI_METHOD_OVERRIDE;
#endif
 
    /** Set the shadow state to on or off for the text
      * \param shadow  shadow state
      */
    GLS_EXPORT void Shadow( bool shadow );
 
    /// \return Whether or not text shadow is visible.
    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 );
 
    /// \return The current shadow 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 );
 
    /// \return The current shadow 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 );
 
    /// \return The strikethru state for the first character.
    GLS_EXPORT bool StrikeThru();
 
    /** Sets the Unicode string to be displayed for this object
      * \param s STD Template Library String
      */
    virtual GLS_EXPORT void String( const std::string& s );
 
    /** Sets the Unicode string to be displayed for this object
      * \param s C Style string
      */
    virtual 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 );
 
    /// \return 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 );
 
    /// \return 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 );
 
    /// \return The current uppercase state.
    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();
    }
 
    /// \return 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;            ///< Left side of the segment.
        float    x2;            ///< Right side of the segment.
        float    y;             ///< Vertical position of the segment.
        float    thickness;     ///< Thickness of the segment in logical units.
        float    shadowOffsetX; ///< X offset of the shadow in logical units.
        float    shadowOffsetY; ///< Y offset of the shadow in logical units.
        GlsColor color;         ///< Color the segment is to be drawn.
 
        LineSegment_t()
            : x1( 0.0f )
            , x2( 0.0f )
            , y( 0.0f )
            , thickness( 0.0f )
            , shadowOffsetX( 0.0f )
            , shadowOffsetY( 0.0f )
        {
        }
 
        /// Constructor
        /// \param segmentX1 Left side of the segment.
        /// \param segmentX2 Right side of the segment.
        /// \param segmentY Vertical position of the segment.
        /// \param segmentThickness Thickness of the segment in logical units.
        /// \param segmentShadowOffsetX X offset of the shadow in logical units.
        /// \param segmentShadowOffsetY Y offset of the shadow in logical units.
        /// \param segmentColor Color the segment is to be drawn.
        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; ///< Typedef for a list of character attributes.
 
    static GLS_EXPORT const Vector XAXIS; ///< Vector for the global X axis.
    static GLS_EXPORT const Vector YAXIS; ///< Vector for the global Y axis.
 
    static GLS_EXPORT Vertex INITIAL_VERTICES[ NUM_VERTICES ]; ///< Default corners for new text objects.
 
    /** 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 ]; ///< The corners of the text object.
 
    /** 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;
 
    bool _halo; ///< Whether or not the halo effect is on.
 
    /** 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;
 
    bool _shadow; ///< Whether or not the shadow effect is on.
 
    /** 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;
 
public: // protected is preferred, but VC 7.0 has issues with it.
#ifndef GLES
 
    /// 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.
    /// \param x1 The left point.
    /// \param y1 The top point.
    /// \param x2 The right point.
    /// \param y2 The bottom point.
    static void DrawScalableLine( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 )
    {
        // 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();
    }
#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 );
 
    /// Calculates direction vectors based on the orientation of its vertices.
    /// \note Not normally called by users.
    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 in operator
/// \param instr The stream to read from.
/// \param j The returned value read from the stream.
/// \return The stream in its current state.
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;
}
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param j The value to write to the stream.
/// \return The stream in its current state.
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; ///< Deprecated typedef for the base class.
    typedef DistiAttributeDictionaryAttribute BaseClass;  ///< Typedef for the base class.
 
    /// Constructor
    /// \param name The name to use for this attribute.
    /// \param text The text object associated with this attribute.
    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 DISTI_METHOD_OVERRIDE
    {
        return false;
    }
 
    virtual std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
    {
        _charAttr = _text->CharAttr( 0 );
        return BaseClass::WriteValue( outstr );
    }
 
    virtual std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
    {
        // 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;     ///< Observing pointer to the text object holding the attributes.
    GlsText::CharAttr_t _charAttr; ///< Character attribute structure to apply to text.
};
 
} // namespace disti
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param c The value to write to the stream.
/// \return The stream in its current state.
DISTI_EXPORT std::ostream& operator<<( std::ostream& outstr, const disti::GlsText::CharAttr_t& c );
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param c The returned value read from the stream.
/// \return The stream in its current state.
DISTI_EXPORT std::istream& operator>>( std::istream& instr, disti::GlsText::CharAttr_t& c );
 
#endif