gls_text_box.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsTextBox 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_BOX_H
#define _GLS_TEXT_BOX_H

//////////////////// Provides support for creating DLLs ////////////////////////
#if( defined( GLSGEN_EXPORT_GLSTEXTBOX ) || defined( GLSGEN_IMPORT_GLSTEXTBOX ) || defined( GLSGEN_GLSTEXTBOX_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSTEXTBOX ) || defined( GLSGEN_GLSTEXTBOX_EXPORT_GENERATED )
#        define GLSGEN_GLSTEXTBOX_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSTEXTBOX_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSTEXTBOX_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////

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

#include "gls_cpp_lang_support.h"
#include "gls_text.h"
#include "unhide_globals.h"

#ifdef GLES
#    include "gls_quad_storage.h"
#    include "gls_state_manager.h"
#endif

#define LIB_BASE_NAME "gls_text_box"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME

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

//===========================================================================
/**
* The GlsTextBox   
*/
class GlsTextBox : public GlsText
{
protected:
    class UnderlineStrikeThruHelper;
    void DrawText();

#ifdef GLES
    GlsQuadListVC_3D  _backgrounds;
    GlsQuadListVCT_2D _shadows;
    GlsQuadListVC_3D  _shadowLines;
    GlsQuadListVCT_2D _characters;
    GlsQuadListVC_3D  _lines;

    void PopulateQuadStorage();
#endif

public:
    enum ResizeMode_t
    {
        RESIZE_MODE_FIXED,
        RESIZE_MODE_AUTO_WIDTH,
        RESIZE_MODE_AUTO_HEIGHT
    };

    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef GlsText _BaseClass;
    typedef GlsText BaseClass;

    friend class GlsTextBoxEditor;

    /** Class Constructor. */
    GLSGEN_GLSTEXTBOX_EXPORT GlsTextBox();
    GLSGEN_GLSTEXTBOX_EXPORT GlsTextBox( const GlsTextBox& that, const bool generateNames );

    /** Class Constructor. */
    virtual GLSGEN_GLSTEXTBOX_EXPORT ~GlsTextBox();

    // 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;

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void SetAvailableAttributes( unsigned int value ) DISTI_METHOD_OVERRIDE;

    /* Peform any necessary non-draw calculations like resizing
      * the grid.
      * \param time   The time since the start of program execution
      */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void Calculate( double time ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT DisplayObject* CloneObject( bool generateNames = false ) DISTI_METHOD_OVERRIDE;

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

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

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void Draw( void ) DISTI_METHOD_OVERRIDE;

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

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

#ifdef GLES
    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler ) DISTI_METHOD_OVERRIDE;
#endif

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void SetVertices( unsigned int nPoints, Vertex* vertices ) DISTI_METHOD_OVERRIDE;

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void Initialize();

    /** Rebuilds this text box layout.  This may be an expensive call, so it should only be called when a property changes.   */
    GLSGEN_GLSTEXTBOX_EXPORT void Rebuild();

    /* Unhides base class implementation. */
    using BaseClass::Scale;

    /**
        We need to know the Max number of lines/rows possible to display, we
        may run out of characters to print/display before we hit the max 
        number of lines though.
        \return A value between Zero and INT_MAX, representing the max lines/rows to draw
        \pre The TextBox object has been initialized
        \post The value of max lines returned to the caller
    */
    virtual GLSGEN_GLSTEXTBOX_EXPORT unsigned int MaxLinesToDraw( void );

    /* See base class */
    virtual GLSGEN_GLSTEXTBOX_EXPORT void Scale( float px, float py, float pz, Vertex* anchor, int handleBar ) DISTI_METHOD_OVERRIDE;

    // Different text justifications.
    enum Align_t
    {
        ALIGN_CENTER,
        ALIGN_TOP,
        ALIGN_BOTTOM
    };

    /** Set the vertical justification for this text object
      * \param justification The justification mode (TOP, BOTTOM, CENTER)
      */
    GLSGEN_GLSTEXTBOX_EXPORT void VerticalAlignment( Align_t justification );

    /** Get the vertical justification for this text object 
      * \return vertical justification
      */
    virtual Align_t VerticalAlignment() const
    {
        return _verticalAlignment;
    }

    //-----------------------------------------------------------------------
    //-----------------------------------------------------------------------
    // Routines for compatbility with TextDisplay.gls
    //-----------------------------------------------------------------------
    //-----------------------------------------------------------------------

    /** Clears all of the characters and resets the attributes of all
      * characters (TextDisplay compatability method)
      * \deprecated use Erase instead
      */
    GLSGEN_GLSTEXTBOX_EXPORT void Clear( void )
    {
        Erase();
    }

    /** Clears all of the characters. Does NOT reset the attributes
      * of the characters (TextDisplay compatability method)
      * \deprecated
      */
    GLSGEN_GLSTEXTBOX_EXPORT void ClearChars( void )
    {
        _text.erase();
        SetRebuild();
    }

    /** SetColor() meaning has changed, now use TextColor */

    /** Print a string into this text object starting at index 0 and proceeding Left
      * to right Wraps at newline characters.  Does not change the color or any
      * other modes. Replaces the entire string.
      * (TextDisplay compatability method)
      * \param s  The string to print
      * \deprecated use String instead
      */
    GLSGEN_GLSTEXTBOX_EXPORT void SetString( const char* s )
    {
        String( s );
    }

    /** Print a string into this text object 
      * to right. Wraps at newline characters.  Does not change the color or any
      * other modes. Replaces the entire string.
      * \param format  printf style varargs formatting string.
      */
    GLSGEN_GLSTEXTBOX_EXPORT void VaString( const char* format, ... );

    /* Undocumented.
      * This method is used to calculate the lines of the text box and is likely to change in future releases.
      */
    GLSGEN_GLSTEXTBOX_EXPORT void NextLineInfo( const unsigned int currentStringIndex,
        unsigned int*                                              lineEndIndex,
        unsigned int*                                              nextLineStringIndex,
        float*                                                     startXpixels,
        float*                                                     lineLengthPixels );

    /* Undocumented.
      * This method is used to calculate the lines of the text box and may change in future releases.
      */
    GLSGEN_GLSTEXTBOX_EXPORT unsigned int GetLineCount();

    /** Sets tab space multiplier, 1.0 == same as specified in font */
    GLSGEN_GLSTEXTBOX_EXPORT void TabSpacing( float );

    /** Returns the current tab space multiplier
      * \return the current tab space multiplier
      */
    GLSGEN_GLSTEXTBOX_EXPORT float TabSpacing();

    /** 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_GLSTEXTBOX_EXPORT bool LeftToRight( void );

    /** Set the text direction 
      * \param leftToRight true for left->right else false for right->left
      */
    GLSGEN_GLSTEXTBOX_EXPORT void LeftToRight( bool leftToRight );

    virtual GLSGEN_GLSTEXTBOX_EXPORT void         ResizeMode( ResizeMode_t value );
    virtual GLSGEN_GLSTEXTBOX_EXPORT ResizeMode_t ResizeMode();

    virtual GLSGEN_GLSTEXTBOX_EXPORT void  MaxWidth( float value );
    virtual GLSGEN_GLSTEXTBOX_EXPORT float MaxWidth();

    virtual GLSGEN_GLSTEXTBOX_EXPORT void  MaxHeight( float value );
    virtual GLSGEN_GLSTEXTBOX_EXPORT float MaxHeight();

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

    /*
     * 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_GLSTEXTBOX_EXPORT char* FormatVarArgList( const char* format, va_list args );

    /*  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;

    /*
     * Enable per character attribute drawing for this grid
     */
    GLSGEN_GLSTEXTBOX_EXPORT void EnablePerCharAttribs( void )
    {
        if( !_perCharAttribs )
        {
            _perCharAttribs = true;
            SetRebuild();
        }
    }

    /* Justification setting (TOP, CENTER, BOTTOM) */
    Align_t _verticalAlignment;

    /* Space multiplier for tabs */
    float _tabSpacing;

    //-----------------------------------------------------------------------
    /*
    */
    GLSGEN_GLSTEXTBOX_EXPORT void RecalcCellSize();

    //-----------------------------------------------------------------------
    /*
    */
    GLSGEN_GLSTEXTBOX_EXPORT void RecalcVertices();

    /** Populate the _rowInfo array based on the current display string
      * \pre none
      * \post _rowInfo array is populated based on the current display string
      */
    GLSGEN_GLSTEXTBOX_EXPORT virtual void CalculateRowData( void );

    /* Get the row info for the row starting at the given string index
     * \param strIndex starting index into string
     * \param rowLength [out] gets number of characters in row
     * \param rowPixelWidth [out] gets pixel width of row
     * \param nextRowStartIndex [out] gets starting string index for next row
     *                                else GLSUINT32_MAX if there is no string data for the next row
     * \pre strIndex < _str.GetLength()
     * \post rowLength has the number of characters in the row,
     *       rowPixelWidth has the pixel width of the row,
     *       nextRowStartIndex has the starting string index for the next row
     *           else GLSUINT32_MAX if there is no string data for the next row
     */
    GLSGEN_GLSTEXTBOX_EXPORT void GetNextRowInfo( const unsigned int strIndex,
        unsigned int&                                                rowLength,
        float&                                                       rowPixelWidth,
        unsigned int&                                                nextRowStartIndex ) const;

    float GetMaxLineLengthForResizeMode() const;

    void SetVerticesToTextBounds();

public:
    /** Get the width for the given character taking into account cell sizing, character spacing, uppercasing
     * and tab characters width being expanded
     * \param c character in question
     * \return width for given character
     * \pre none
     * \post none
     */
    GLSGEN_GLSTEXTBOX_EXPORT float GetCharWidth( const unsigned short c ) const;

protected:
    /** info for one row of text in the display */
    struct RowInfo
    {
        unsigned int startingIndex; /**< starting text index into the display 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 rows of characters in the text grid (number of lines) */
    unsigned int _lineCount;
    bool         _lineCountChanged;

    RowInfo* _rowInfo; /**< array ( _rows number of elements ) of RowInfo */

    float _cellWidthRatio;

    float        _maxLineLengthPixels;
    float        _maxTextHeightPixels;
    unsigned int _maxLinesToDraw;

    bool _leftToRight; /**< true to render characters from left to right else 
                                 * false for right to left */

    ResizeMode_t _resizeMode;
    float        _resizeMaxWidth;
    float        _resizeMaxHeight;

    UTF16String _unicodeText; /**< unicode version of _text from base class, updated by CalculateRowData */

    /* helper class for processing underline and strike-thru when drawing text grid */
    class UnderlineStrikeThruHelper
    {
    public:
        /**
         * \param cellWidth maximum width of a character cell in the text box
         * \param cellHeight height of a character cell in the text box
         * \param cellYScale unused
         * \param shadow true if text box has shadow enabled
         * \param shadowOffset offset for shadow
         * \param shadowColor color of shadow in text box
         * \param underlineOffset offset of underline
         * \param underlineSize size of underline
         * \param halo true if text box has halo enabled
         * \param haloOffset offset for halo
         * \param haloColor color of halo in text box
         * \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 box.
         */
        void NewRow( void );

        /**
         * Pre Process the given character attributes
         * \param charAttr attributes in question
         * \param c the character code to process.
         * \param cellX x coord of character cell
         * \param charY y coord of character
         */
        void PreProcessCharacter( const CharAttr_t& charAttr, const Char_t& c, float cellX, float charY );

        /**
         * Post Process the given character attributes
         * \param charAttr attributes in question
         * \param c the character code to process.
         * \param cellX x coord of character cell
         * \param charY y coord of character cell
         * \param cellWidth the width of the current character 
         * \param endOfLine true if character was the end of the current line
         */
        void PostProcessCharacter( const CharAttr_t& charAttr, const Char_t& c, float cellX, float charY, float cellWidth, bool endOfLine );

#ifdef GLES
        /**
         * Render the line segments for the underline / strikethru
         * \param quadStorage The quad storage list to render
         */
        void RenderLineSegments( GlsQuadListVC_3D& quadStorage );
#else
        /**
         * Render the line segments for the underline / strikethru
         */
        void RenderLineSegments( void );
#endif

        void IgnoreShadow( void );

        void AllowShadow( void );

    protected:
        // cell constants
        const float _cellWidth;
        const float _cellHeight;

        // shadow constants
        const bool     _shadow;
        const Vector   _shadowOffset;
        const GlsColor _shadowColor;
        bool           _allowShadow;

        // underline constants
        const float _underlineOffset;
        const float _underlineSize;

        // halo constants
        const bool     _halo;
        const float    _haloOffset;
        const GlsColor _haloColor;

        // left to right
        const bool _leftToRight;

        // state vars for underline processing
        float    _underlineX1, _underlineX2, _underlineY, _underlineScale;
        GlsColor _underlineColor;
        bool     _underlineOn;

        // state vars for strike-thru processing
        float    _strikeX1, _strikeX2, _strikeY, _strikeScale;
        GlsColor _strikeColor;
        bool     _strikeOn;

        // state vars for line processing
        bool _whiteSpaceYes;

        // line segments to draw
        typedef std::list<LineSegment_t> LineSegmentCont_t;
        LineSegmentCont_t                _lineSegments;
    };

private:
    GlsTextBox& operator=( const GlsTextBox& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsTextBox( const GlsTextBox& ) DISTI_SPECIAL_MEM_FUN_DELETE;

    /* See base class */
    void OnCellDimensionChanged() DISTI_METHOD_OVERRIDE
    {
        _needToRebuild = true;
    }
};

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

    if( str == "ALIGN_TOP" )
    {
        j = disti::GlsTextBox::ALIGN_TOP;
    }
    else if( str == "ALIGN_CENTER" )
    {
        j = disti::GlsTextBox::ALIGN_CENTER;
    }
    else if( str == "ALIGN_BOTTOM" )
    {
        j = disti::GlsTextBox::ALIGN_BOTTOM;
    }
    return instr;
}

//---------------------------------------------------------------------------
inline std::ostream& operator<<( std::ostream& outstr, disti::GlsTextBox::Align_t j )
{
    switch( j )
    {
    case disti::GlsTextBox::ALIGN_TOP:
        outstr << "ALIGN_TOP";
        break;
    case disti::GlsTextBox::ALIGN_CENTER:
        outstr << "ALIGN_CENTER";
        break;
    case disti::GlsTextBox::ALIGN_BOTTOM:
        outstr << "ALIGN_BOTTOM";
        break;
    }
    return outstr;
}

/** In stream operator for ResizeMode_t enumeration.
  */
inline std::istream& operator>>( std::istream& instr, disti::GlsTextBox::ResizeMode_t& direction )
{
    std::string str;
    instr >> str;

    if( str == "RESIZE_MODE_FIXED" )
    {
        direction = disti::GlsTextBox::RESIZE_MODE_FIXED;
    }
    else if( str == "RESIZE_MODE_AUTO_WIDTH" )
    {
        direction = disti::GlsTextBox::RESIZE_MODE_AUTO_WIDTH;
    }
    else if( str == "RESIZE_MODE_AUTO_HEIGHT" )
    {
        direction = disti::GlsTextBox::RESIZE_MODE_AUTO_HEIGHT;
    }
    return instr;
}

/** Out stream operator for ResizeMode_t enumeration.
  */
inline std::ostream& operator<<( std::ostream& outstr, disti::GlsTextBox::ResizeMode_t direction )
{
    switch( direction )
    {
    case disti::GlsTextBox::RESIZE_MODE_FIXED:
        outstr << "RESIZE_MODE_FIXED";
        break;
    case disti::GlsTextBox::RESIZE_MODE_AUTO_WIDTH:
        outstr << "RESIZE_MODE_AUTO_WIDTH";
        break;
    case disti::GlsTextBox::RESIZE_MODE_AUTO_HEIGHT:
        outstr << "RESIZE_MODE_AUTO_HEIGHT";
        break;
    }
    return outstr;
}

} // namespace disti

#endif