gls_text_grid.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsTextGrid 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_GRID_H
#define _GLS_TEXT_GRID_H
 
#include "gls_gl.h"
#include "gls_text.h"
#include "unhide_globals.h"
#include <string>
 
#ifdef GLES
#    include "gls_quad_storage.h"
#endif
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GLSTEXTGRID ) || defined( GLSGEN_IMPORT_GLSTEXTGRID ) || defined( GLSGEN_GLSTEXTGRID_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSTEXTGRID ) || defined( GLSGEN_GLSTEXTGRID_EXPORT_GENERATED )
#        define GLSGEN_GLSTEXTGRID_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSTEXTGRID_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSTEXTGRID_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
/// Automatically link the runtime library plugin (on Windows).
#define LIB_BASE_NAME "gls_text_grid"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
 
//===========================================================================
//                             MACROS
//===========================================================================
 
/// Convenience macro to set an arbitrary attribute in a given character range to a given value.
#define SET_CHAR_RANGE( startCol, startRow, len, attribute, value )                          \
    {                                                                                        \
        unsigned int charsSet( 0 );                                                          \
        unsigned int col( startCol );                                                        \
        bool         notifyChanged = false;                                                  \
                                                                                             \
        if( startCol < _cols && startRow < _rows )                                           \
        {                                                                                    \
            for( unsigned int row = startRow; ( row < _rows ) && ( charsSet < len ); ++row ) \
            {                                                                                \
                for( ; ( col < _cols ) && ( charsSet < len ); ++col )                        \
                {                                                                            \
                    if( _chars[ IndexOf( col, row ) ].attribute != value )                   \
                    {                                                                        \
                        _chars[ IndexOf( col, row ) ].attribute = value;                     \
                        notifyChanged                           = true;                      \
                    }                                                                        \
                    ++charsSet;                                                              \
                }                                                                            \
                col = 0;                                                                     \
            }                                                                                \
        }                                                                                    \
                                                                                             \
        if( notifyChanged )                                                                  \
        {                                                                                    \
            EnablePerCharAttribs();                                                          \
            SetRebuild();                                                                    \
        }                                                                                    \
    }
 
//===========================================================================
//                         BEGIN NAMESPACE
//===========================================================================
namespace disti
{
#ifdef GLES
// Forward Declaration
class GlsGloFileAttribute;
#endif
 
// Initializers for text
enum
{
    GLS_TEXT_GRID_SIZE = GLS_LAST_TEXT_INITIALIZER + 1,
    GLS_TEXT_GRID_LEFT_TO_RIGHT
};
 
//===========================================================================
/**
* The GlsTextGrid   
*/
class GlsTextGrid : public GlsText
{
protected:
    /// Helper function that performs the underlying text draw.
    /// \note Not normally called by users.
    void DrawText();
 
#ifdef GLES
    GlsQuadListVC_3D  _backgrounds; ///< Quads used to render the backgrounds. This is rendered behind the other quads associated with this text grid.
    GlsQuadListVCT_2D _shadows;     ///< Quads used to render the shadow behind the text.
    GlsQuadListVC_3D  _shadowLines; ///< Quads used to render the shadows for lines such as underlines and strikethroughs.
    GlsQuadListVCT_2D _characters;  ///< Quads used to render the characters in the foreground.
    GlsQuadListVC_3D  _lines;       ///< Quads used to render lines such as underlines and strikethroughs.
 
    /// Constructs primitives and renders each character. This function considers the text grid's position, justification, character size,
    /// and decorations (such as strikethroughs and shadows).
    void PopulateQuadStorage();
#endif
 
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef GlsText _BaseClass; ///< Deprecated typedef for the base class.
    typedef GlsText BaseClass;  ///< Typedef for the base class.
 
    friend class GlsTextGridEditor;
 
    /** Class Constructor. */
    GLSGEN_GLSTEXTGRID_EXPORT GlsTextGrid();
 
    /// Copy constructor
    /// \param that The object to copy from.
    /// \param generateNames Whether or not to generate an instance name for this object.
    GLSGEN_GLSTEXTGRID_EXPORT GlsTextGrid( const GlsTextGrid& that, const bool generateNames );
 
    /** Class Deconstructor. */
    virtual GLSGEN_GLSTEXTGRID_EXPORT ~GlsTextGrid();
 
    // Need to declare using all base class methods that we overload
    using BaseClass::Baseline;
    using BaseClass::BgColor;
    using BaseClass::CellHeight;
    using BaseClass::CellWidth;
    using BaseClass::Char;
    using BaseClass::CharAttr;
    using BaseClass::CharScaling;
    using BaseClass::CharSpacing;
    using BaseClass::Erase;
    using BaseClass::FauxBold;
    using BaseClass::Inverse;
    using BaseClass::StrikeThru;
    using BaseClass::String;
    using BaseClass::TextColor;
    using BaseClass::Underline;
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;
 
    /** Sets the baseline shift for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param baselineShift  multiplier used to shift the baseline.
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Baseline(
        unsigned int col,
        unsigned int row,
        float        baselineShift );
 
    /** Sets the baseline shift for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param baselineShift  multiplier used to shift the baseline.
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Baseline(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        float        baselineShift );
 
    /** Sets the cell background color for one character.
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param color  The background color to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void BgColor(
        unsigned int    col,
        unsigned int    row,
        const GlsColor& color );
 
    /** Sets the cell background color for a range of characters.
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param color  The background color to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void BgColor(
        unsigned int    startCol,
        unsigned int    startRow,
        unsigned int    len,
        const GlsColor& color );
 
    /* Peform any necessary non-draw calculations like resizing
      * the grid.
      * \param time   The time since the start of program execution
      */
    virtual GLSGEN_GLSTEXTGRID_EXPORT void Calculate( double time ) DISTI_METHOD_OVERRIDE;
 
    /** Sets the character code for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param code  The ASCII character code to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Char( unsigned int col, unsigned int row, Char_t code );
 
    /** Sets the character code for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param code  The ASCII character code to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Char(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        Char_t       code );
 
    /// \return A particular cell's character attributes.
    /// \param col The column index of the character attribute to return.
    /// \param row The row index of the character attribute to return.
    CharAttr_t CharAttr( unsigned int col, unsigned int row ) const
    {
        return _chars[ IndexOf( col, row ) ];
    }
 
    /** Sets the scale factor of one character  NOTE:  This is the size of the character in its
      * cell not the overall scale of the entire object
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param newScale  The new scale factor of the characters (0.0 < newScale <= 1.0)
      */
    GLSGEN_GLSTEXTGRID_EXPORT void CharScaling(
        unsigned int col,
        unsigned int row,
        float        newScale );
 
    /** Sets the scale factor of a range of characters  NOTE:  This is the size of the character in its
      * cell not the overall scale of the entire object
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param newScale  The new scale factor of the characters (0.0 < newScale <= 1.0)
      */
    GLSGEN_GLSTEXTGRID_EXPORT void CharScaling(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        float        newScale );
 
    /** Sets the horizontal character spacing for one character
      * 1.0 is the default spacing 2.0 would be twice the normal spacing
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param horizontalSpacing  The horizontalSpacing value
      */
    GLSGEN_GLSTEXTGRID_EXPORT void CharSpacing(
        unsigned int col,
        unsigned int row,
        float        horizontalSpacing );
 
    /** Sets the horizontal character spacing for a range of  characters
      * 1.0 is the default spacing 2.0 would be twice the normal spacing
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param horizontalSpacing  The horizontalSpacing value
      */
    GLSGEN_GLSTEXTGRID_EXPORT void CharSpacing(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        float        horizontalSpacing );
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;
 
    /** Gets the width of this object in characters
       * \return The width of this object in characters (number of columns) */
    unsigned int Columns() const
    {
        return _cols;
    }
 
    /** Sets the number of columns the text grid contains.
      * \param newCols new number of columns to size the grid with. 
      */
    void Columns( unsigned int newCols )
    {
        Size( newCols, _rows );
    }
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT void CopyGeometry( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
    GLSGEN_GLSTEXTGRID_EXPORT virtual void CopyProperties( DisplayObject* src ) DISTI_METHOD_OVERRIDE;
 
#ifdef GLES
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
#endif
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT void Draw() DISTI_METHOD_OVERRIDE;
 
    /** Erase one character. 
      * \param col  X coordinate of the character to erase
      * \param row  Y coordinate of the character to erase  
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Erase( unsigned int col, unsigned int row );
 
    /** Erase all characters after a given position. 
      * \param startCol  X coordinate of the first character to erase
      * \param startRow  Y coordinate of the first character to erase
      * \param rows      Number of rows to erase
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Erase(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int rows );
 
    /** Erase a range of characters. 
      * \param startCol  X coordinate of the first character to erase
      * \param startRow  Y coordinate of the first character to erase
      * \param endCol    X coordinate of the last character to erase
      * \param endRow    Y coordinate of the last character to erase.
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Erase(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int endCol,
        unsigned int endRow );
 
    /** Set the bold state on or off for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param bold  Bold state
      */
    GLSGEN_GLSTEXTGRID_EXPORT void FauxBold( unsigned int col, unsigned int row, bool bold );
 
    /** Set the bold state on or off for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param bold  Bold state
      */
    GLSGEN_GLSTEXTGRID_EXPORT void FauxBold(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        bool         bold );
 
#ifndef GLES
    virtual GLSGEN_GLSTEXTGRID_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSTEXTGRID_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array ) DISTI_METHOD_OVERRIDE;
#endif
 
    /// Sets the initial state of this object.
    virtual GLSGEN_GLSTEXTGRID_EXPORT void Initialize();
 
    /** Set the inverse video state on or off for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param inverse  inverse video state
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Inverse( unsigned int col, unsigned int row, bool inverse );
 
    /** Set the inverse video state on or off for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param inverse  inverse video state
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Inverse(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        bool         inverse );
 
    /** \return The length of a given line in characters. This will search the
      * specified row until a \n or NULL is encountered or until it reaches the
      * end of the row (number of columns in the grid).
      * \param row  The row to return the length of
      */
    GLSGEN_GLSTEXTGRID_EXPORT unsigned int LineLength( unsigned int row ) const;
 
    /** The number of rows in this text grid 
      * \return The number of rows in this text grid */
    unsigned int Rows() const
    {
        return _rows;
    }
 
    /** Change the number of rows the text grid contains.
      * \param newRows new number of rows to size the grid with. 
      */
    void Rows( unsigned int newRows )
    {
        Size( _cols, newRows );
    }
 
    /* Unhides base class implementation. */
    using BaseClass::Scale;
 
    /** Scales the object, either the handleBar, or the Anchor is
      * used to translate the object, not both.  Anchor takes 
      * presidence, if it is set HandleBar is ignored.
      * The footprint is different from the 2D scale so the compiler can destinguish the two.
      * \param px Value of the percentage of scale in x-axis
      * \param py Value of the percentage of scale in y-axis
      * \param pz Value of the percentage of scale in z-axis
      * \param anchor Anchor from which to scale object relative to
      * \param handleBar Vertex that is being dragged
      */
    virtual GLSGEN_GLSTEXTGRID_EXPORT void Scale( float px, float py, float pz, Vertex* anchor, int handleBar ) DISTI_METHOD_OVERRIDE;
 
    virtual GLSGEN_GLSTEXTGRID_EXPORT void SetValue( int spec, va_list& args ) DISTI_METHOD_OVERRIDE;
    virtual GLSGEN_GLSTEXTGRID_EXPORT void SetVertices( unsigned int nPoints, Vertex* vertices ) DISTI_METHOD_OVERRIDE;
 
    /** Sets the number of rows and columns for this object
      * \param cols The new number of columns
      * \param rows The new number of rows
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Size( unsigned int cols, unsigned int rows );
 
    /** Sets the strikethru state for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param strike Whether or not set strike to fit
      */
    GLSGEN_GLSTEXTGRID_EXPORT void StrikeThru( unsigned int col, unsigned int row, bool strike );
 
    /** Sets the strikethru state for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param strike Whether or not set strike to fit
      */
    GLSGEN_GLSTEXTGRID_EXPORT void StrikeThru(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        bool         strike );
 
    /** Sets the ASCII string to be displayed for this object starting 
      * at an col,row coordinate and wrapping on newlines and column count
      * \param startCol  X coordinate (column) to start at
      * \param startRow  Y coordinate (row) to start at
      * \param s  STD Template Library string to print
      */
    GLSGEN_GLSTEXTGRID_EXPORT void String(
        unsigned int       startCol,
        unsigned int       startRow,
        const std::string& s );
 
    /** Sets the ASCII string to be displayed for this object starting 
      * at an col,row coordinate and wrapping on newlines and column count
      * \param startCol  X coordinate (column) to start at
      * \param startRow  Y coordinate (row) to start at
      * \param s  C style string to print
      */
    void String( unsigned int startCol, unsigned int startRow, const char* s )
    {
        String( startCol, startRow, std::string( s ) );
    }
 
    /** Sets the foreground color for one character
      * \param col  X coordinate of the character to set
      * \param row  Y coordinate of the character to set
      * \param color  The foreground color to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void TextColor(
        unsigned int    col,
        unsigned int    row,
        const GlsColor& color );
 
    /** Sets the foreground color for a range of characters
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param color  The foreground color to set
      */
    GLSGEN_GLSTEXTGRID_EXPORT void TextColor(
        unsigned int    startCol,
        unsigned int    startRow,
        unsigned int    len,
        const GlsColor& color );
 
    /** Returns the foreground color for the specified character.
      * If no character is specified, the color at 0,0 will be returned.
      * \param col   X coordinate of the character of interest
      * \param row   Y coordinate of the character of interest
      * \return The requested color
      */
    GLSGEN_GLSTEXTGRID_EXPORT GlsColor TextColor(
        unsigned int col = 0,
        unsigned int row = 0 ) const;
 
    /** Turns on/off underlines for one character
      * \param col  X coordinate of the character of interest
      * \param row  Y coordinate of the character of interest
      * \param underline  Whether or not to enable underline
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Underline(
        unsigned int col,
        unsigned int row,
        bool         underline );
 
    /** Turns on/off underlines for a range character
      * \param startCol  X coordinate of the first character to set
      * \param startRow  Y coordinate of the first character to set
      * \param len Number of characters to set
      * \param underline  Whether or not to enable underline
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Underline(
        unsigned int startCol,
        unsigned int startRow,
        unsigned int len,
        bool         underline );
 
    /** Print a string into this text object starting at 0,0 and proceeding Left
      * to right. Wraps at newline characters.  Does not change the color or any
      * other modes.  Replaces the entire string. If substring replacement is desired, 
      * use VaString(col, row, format) instead.
      * \param format  printf style varargs formatting string.
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaString( const char* format, ... );
 
    /** Print a string into this text object starting at col,row and proceeding Left
      * to right. Assumes current string does not contain newline characters. 
      * If a newline is encountered it will be overwritten.
      * Does not change the color or any other modes.  Just inserts/overwrites
      * characters.
      * This replaces a substring within the current string. If you want full string replacement
      * use VaString(format)
      * \param startCol X position (column)
      * \param startRow Y position (row)
      * \param format  printf style varargs formatting string.
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaString(
        unsigned int startCol,
        unsigned int startRow,
        const char*  format,
        ... );
 
    /** Print a string into this text object starting at col,row and proceeding Left to right
      * Assumes current string does not contain newline characters. If a newline is encountered it
      * will be overwritten.
      * Inserts/overwrites characters and changes the color.
      * This replaces a substring within the current string. If you want full string replacement
      * use VaString(format)
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param rgba The color to set
      * \param format  printf style varargs formatting string.
      * \since GL Studio 6.0.1
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaString(
        unsigned int  col,
        unsigned int  row,
        unsigned char rgba[],
        const char*   format,
        ... );
 
    //-----------------------------------------------------------------------
    //-----------------------------------------------------------------------
    // Routines for comapability with TextDisplay.gls
    //-----------------------------------------------------------------------
    //-----------------------------------------------------------------------
 
    /** Enable/disable centering mode 
      * (TextDisplay compatability method)
      * \param flag  True if text should be centered, false if it should be
      *              left justified 
      * \deprecated use Justify instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Center( bool flag )
    {
        Justify( CENTER );
    }
 
    /** Clears all of the characters and resets the attributes of all
      * characters (TextDisplay compatability method)
      * \deprecated use Erase instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void Clear()
    {
        Erase();
    }
 
    /** Clears all of the characters. Does NOT reset the attributes
      * of the characters (TextDisplay compatability method)
      * \deprecated
      */
    GLSGEN_GLSTEXTGRID_EXPORT void ClearChars()
    {
        _text.erase();
        SetRebuild();
    }
 
    /** Set an individual character at the given position
      * Assumes current string does not contain newline characters.
      * If a newline character is encountered in the current string it will be overwritten.
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param ch ASCII code of the character
      * \deprecated use Char instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void SetChar( unsigned int col, unsigned int row, char ch )
    {
        Char( col, row, Char_t( ch ) );
    }
 
    /** Set an individual character at the given position.  Also set its color.
      * Assumes current string does not contain newline characters.
      * If a newline character is encountered in the current string it will be overwritten.
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param ch ASCII code of the character
      * \param rgba  Color value for character
      * \deprecated use Char instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void SetChar(
        unsigned int  col,
        unsigned int  row,
        char          ch,
        unsigned char rgba[] )
    {
        Char( col, row, Char_t( ch ) );
        TextColor( col, row, GlsColor( rgba ) );
    }
 
    /** SetColor() meaning has changed, now use TextColor */
 
    /** Print a string into this text object starting at 0,0 and proceeding Left
      * to right. Wraps at newline characters.  Does not change the color or any
      * other modes. Replaces the entire string. If substring replacement is desired, use String(col, row, s).
      * (TextDisplay compatability method)
      * \param s  The string to print
      * \deprecated use String instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void SetString( const char* s )
    {
        String( s );
    }
 
    /** Print a string into this text object starting at col,row and proceeding
      * Assumes current string does not contain newline characters. 
      * If a newline is encountered in the current string it will be overwritten. Does not change the color
      * or any other modes.  Just inserts/overwrites characters.
      * This replaces a substring within the current string. If you want full string replacement
      * use String(s)
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param s  The string to print
      * \deprecated use String instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void SetString( unsigned int col, unsigned int row, const char* s )
    {
        String( col, row, s );
    }
 
    /** Print a string into this text object starting at col,row and proceeding
      * Assumes current string does not contain newline characters. 
      * If a newline is encountered in the current string it will be overwritten.
      * Inserts/overwrites characters and changes the color.
      * This replaces a substring within the current string. If you want full string replacement
      * use String(s)
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param rgba The color to set
      * \param s  The string to print
      * \deprecated use String instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void SetString(
        unsigned int  col,
        unsigned int  row,
        unsigned char rgba[],
        const char*   s );
 
    /** Print a string into this text object starting at 0,0 and proceeding Left to right
      * Assumes current string does not contain newline characters. If a newline is encountered in the 
      * current string it will be overwritten.  Does not change the color or any other modes.
      * Replaces the entire string. If substring replacement is desired, use VaString(col, row, format).
      * (TextDisplay compatability method)
      * \param format  printf style varargs formatting string.
      * \deprecated use VaString instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaSetString( const char* format, ... );
 
    /** Print a string into this text object starting at col,row and proceeding Left to right
      * Assumes current string does not contain newline characters.  Does not change the color or any other modes.  Just 
      * inserts/overwrites characters.
      * This replaces a substring within the current string. If you want full string replacement
      * use VaString(format)
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param format  printf style varargs formatting string.
      * \deprecated use VaString instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaSetString(
        unsigned int col,
        unsigned int row,
        const char*  format,
        ... );
 
    /** Print a string into this text object starting at col,row and proceeding Left to right
      * Assumes current string does not contain newline characters. If a newline is 
      * encountered in the current string it will be overwritten.
      * Inserts/overwrites characters and changes the color.
      * This replaces a substring within the current string. If you want full string replacement
      * use VaString(format)
      * (TextDisplay compatability method)
      * \param col X position (column)
      * \param row Y position (row)
      * \param rgba The color to set
      * \param format  printf style varargs formatting string.
      * \deprecated use VaString instead
      */
    GLSGEN_GLSTEXTGRID_EXPORT void VaSetString(
        unsigned int  col,
        unsigned int  row,
        unsigned char rgba[],
        const char*   format,
        ... );
 
    /** Determine if the text direction is set to left->right or right->left
      * \return true if if the text direction is set to left->right else false for right->left
      */
    GLSGEN_GLSTEXTGRID_EXPORT bool LeftToRight();
 
    /** Set the text direction 
      * \param leftToRight true for left->right else false for right->left
      */
    GLSGEN_GLSTEXTGRID_EXPORT void LeftToRight( bool leftToRight );
 
protected:
#ifdef GLES
    /** Set a single attribute from the GLO file.
     * \param data The attribute to set and its associated data.
     */
    virtual GLSGEN_GLSTEXTGRID_EXPORT void SetFromGloData( GlsGloFileAttribute& data ) DISTI_METHOD_OVERRIDE;
#endif
 
    /** info for one row of text in the display */
    struct RowInfo
    {
        unsigned int startingIndex; /**< starting text index into the _unicodeText for row
                                      * else GLSUINT32_MAX if row has no characters */
        unsigned int length;        /**< the number of characters in row */
        float        pixelWidth;    /**< the width of row in pixels */
    };
 
    /** Number of columns of characters in the text grid (line length) */
    unsigned int _cols;
 
    /** Number of rows of characters in the text grid (number of lines) */
    unsigned int _rows;
 
    bool _numRowsChanged; ///< If true (note that this is a flag despite the name) the row information will be rebuilt.
 
    /** true  -> grid will draw characters using "per character attributes" else 
     *  false -> all characters will be drawn using the first character's attribute
     *  NOTE: This defaults to false and automatically enables to true if the user calls
     *        a method that requires per character attributes
     */
    bool _perCharAttribs;
 
    RowInfo* _rowInfo; /**< array ( _rows number of elements ) of RowInfo */
 
    bool _leftToRight; /**< true to render characters from left to right else 
                                 * false for right to left */
 
    UTF16String _unicodeText; /**< unicode version of _text from base class, updated by CalculateRowData */
 
    /**
     * Erase a single character at a given index. Use TextIndexOf to find the character using coordinates.
     * \param textIndex index of the character to erase
     */
    GLSGEN_GLSTEXTGRID_EXPORT void EraseIndex( unsigned int textIndex );
 
    /**
     * Enable per character attribute drawing for this grid
     */
    GLSGEN_GLSTEXTGRID_EXPORT void EnablePerCharAttribs()
    {
        if( !_perCharAttribs )
        {
            _perCharAttribs = true;
            SetRebuild();
        }
    }
 
    /**
     * 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
     * \return formatted textbuffer ( must be deleted by caller )
     */
    GLSGEN_GLSTEXTGRID_EXPORT char* FormatVarArgList( const char* format, va_list args );
 
    /// \return The current maximum height of the grid in logical units.
    GLSGEN_GLSTEXTGRID_EXPORT float BoxHeight();
 
    /// \return The current maximum width of the grid in logical units.
    GLSGEN_GLSTEXTGRID_EXPORT float BoxWidth();
 
    /** Converts col,row into linear index
      * \param col The column number
      * \param row  The line number (row)
      * \return The linear index of line & column
      */
    unsigned int IndexOf( unsigned int col, unsigned int row ) const
    {
        unsigned int index( 0 );
 
        if( col < _cols && row < _rows )
        {
            index = ( row * _cols ) + col;
        }
        else
        {
            index = _rows * _cols;
        }
        return index;
    }
 
    /// \return The offset needed to justify the given row from the left side in logical units.
    /// \param row The row index whose offset needs to be calculated.
    GLSGEN_GLSTEXTGRID_EXPORT float JustificationOffset( unsigned int row );
 
    /// \return The width of a given row in logical units.
    /// \param line The row index whose width needs to be calculated.
    /// \param cellWidth The cell width value to use for calculation.
    GLSGEN_GLSTEXTGRID_EXPORT float LinePixelWidth( unsigned int line, float cellWidth ) const;
 
    /// Rebuilds this text grid layout. This may be an expensive call, so it should only be called when a property changes.
    GLSGEN_GLSTEXTGRID_EXPORT void Rebuild();
 
    /// Helper function to calculate cell sizes based on the
    /// scale of the object if control cell size is enabled.
    /// \note Not normally called by users.
    GLSGEN_GLSTEXTGRID_EXPORT void RecalcCellSize();
 
    /// Helper function to readjust vertices back to the local origin being aligned with vertex 0.
    /// \note Not normally called by users.
    GLSGEN_GLSTEXTGRID_EXPORT void RecalcVertices();
 
    /// Helper function to resize the underlying character attributes array.
    /// \note Not normally called by users.
    GLSGEN_GLSTEXTGRID_EXPORT void ResizeGrid();
 
    /** Converts col,row into linear index returning the end of the string if this index would go beyond it
      * \param col      The column number
      * \param row      The line number (row)
      * \param startRow The row to start the search from
      * \return The linear index of line & column
      */
    GLSGEN_GLSTEXTGRID_EXPORT
    unsigned int TextIndexOf( unsigned int col, unsigned int row, unsigned int startRow = 0 ) const;
 
    /** Converts col,row into grid index returning the end of the string if this index would go outside the bounds of the grid
      * \param col The column number
      * \param row  The line number (row)
      * \return The grid index of line & column
      */
    GLSGEN_GLSTEXTGRID_EXPORT
    unsigned int GridIndexOf( unsigned int col, unsigned int row ) const;
 
    /** Populate the _rowInfo array based on the current display string
      * \pre none
      * \post _rowInfo array is populated based on the current display string
      */
    GLSGEN_GLSTEXTGRID_EXPORT virtual void CalculateRowData();
 
    /** helper class for processing underline and strike-thru when drawing text grid */
    class UnderlineStrikeThruHelper
    {
    public:
        /**
         * \param cellWidth width of a character cell in the text grid
         * \param cellHeight height of a character cell in the text grid
         * \param cellYScale unused
         * \param shadow true if text grid has shadow enabled
         * \param shadowOffset offset for shadow
         * \param shadowColor color of shadow in text grid
         * \param underlineOffset offset of underline
         * \param underlineSize size of underline
         * \param halo true if text grid has halo enabled
         * \param haloOffset offset for halo
         * \param haloColor color of halo in text grid
         * \param leftToRight true if text flows left to right else false for right to left
         */
        UnderlineStrikeThruHelper( float cellWidth, float cellHeight, float cellYScale, bool shadow, const Vector& shadowOffset, const GlsColor& shadowColor,
            float underlineOffset, float underlineSize, bool halo, float haloOffset, GlsColor haloColor, bool leftToRight );
 
        /**
         * Setup to process a new row in the text grid
         */
        void NewRow();
 
        /**
         * Pre Process the given character attributes
         * \param charAttr attributes in question
         * \param cellX x coord of character cell
         * \param nextCellX x coord of character cell one past the given character
         * \param charY y coord of character
         * \param endOfLine true if character was the end of the current line
         */
        void ProcessCharacter( const CharAttr_t& charAttr, float cellX, float nextCellX, float charY, bool endOfLine );
 
#ifdef GLES
        /// Render the line segments for the underline / strikethru
        /// \param quadStorage object responsible for holding the quads for the line segments.
        void RenderLineSegments( GlsQuadListVC_3D& quadStorage );
#else
        /// Render the line segments for the underline / strikethru
        void RenderLineSegments();
#endif
        /// Sets the shadow visibility flag to false.
        void IgnoreShadowAndHalo()
        {
            _allowShadow = false;
        }
 
    protected:
        // cell constants
        const float _cellWidth;  ///< Height of each character cell in the grid in logical units.
        const float _cellHeight; ///< Width of each character cell in the grid in logical units.
 
        // shadow constants
        const bool     _shadow;       ///< Whether or not the shadow effect is on.
        const Vector   _shadowOffset; ///< Offset of the shadow effect from the characters. Z component is ignored.
        const GlsColor _shadowColor;  ///< Color of the shadow effect behind the characters.
        bool           _allowShadow;  ///< Whether or not shadows are being drawn in general.
 
        // underline constants
        const float _underlineOffset; ///< Vertical offset of the underline in logical units.
        const float _underlineSize;   ///< Thickness of the underline in logical units.
 
        // halo constants
        const bool     _halo;       ///< Whether or not the halo effect is on.
        const float    _haloOffset; ///< Offset multiplier for the halo effect.
        const GlsColor _haloColor;  ///< Color of the halo effect behind the characters.
 
        // left to right
        const bool _leftToRight; ///< If true, characters are rendered left to right, otherwise right to left.
 
        // state vars for underline processing
        float    _underlineX1;    ///< Current underline state left X coordinate.
        float    _underlineX2;    ///< Current underline state right X coordinate.
        float    _underlineY;     ///< Current underline state Y coordinate.
        float    _underlineScale; ///< Current underline drawing scale.
        GlsColor _underlineColor; ///< Current underline drawing color.
        bool     _underlineOn;    ///< If true, underline drawing is enabled.
 
        // state vars for strike-thru processing
        float    _strikeX1;    ///< Current strike through state left X coordinate.
        float    _strikeX2;    ///< Current strike through state right X coordinate.
        float    _strikeY;     ///< Current strike through state Y coordinate.
        float    _strikeScale; ///< Current strike through drawing scale.
        GlsColor _strikeColor; ///< Current strike through drawing color.
        bool     _strikeOn;    ///< If true, strike through drawing is enabled.
 
        // line segments to draw
        typedef std::list<LineSegment_t> LineSegmentCont_t; ///< Typedef for a list of line segments.
        LineSegmentCont_t                _lineSegments;     ///< The list of line segments to draw.
    };
 
private:
    void OnCellDimensionChanged() DISTI_METHOD_OVERRIDE
    {
        RecalcVertices();
    }
 
    GlsTextGrid& operator=( const GlsTextGrid& );
    GlsTextGrid( const GlsTextGrid& );
};
 
} // namespace disti
 
#endif