gls_ctl_text_box.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsCTLTextBox 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 INCLUDED_GLS_CTL_TEXT_BOX_H
#define INCLUDED_GLS_CTL_TEXT_BOX_H

// CTL Text box does not work for WebGL/RPi due to issues with the Pango library and its dependencies
// CTL Text boxes will fall back to stock GlsTextBoxes, and any CTL functions will do nothing.
// GLS-5903: Remove Pango from CTL Text Box
#if defined( EMSCRIPTEN ) || defined( RPI_ARCH )
#    define GLS_CTL_FALLBACK_ENABLED
#    ifndef GLES
#        error "GLES should always be enabled when using the CTL fallback code"
#    endif
#endif

//////////////////// Provides support for creating DLLs ////////////////////////
#if( defined( GLSGEN_EXPORT_GLSCTLTEXTBOX ) || defined( GLSGEN_IMPORT_GLSCTLTEXTBOX ) || defined( GLSGEN_GLSCTLTEXTBOX_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSCTLTEXTBOX ) || defined( GLSGEN_GLSCTLTEXTBOX_EXPORT_GENERATED )
#        define GLSGEN_GLSCTLTEXTBOX_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSCTLTEXTBOX_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSCTLTEXTBOX_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////

#include "gls_cpp_lang_support.h"
#include "gls_gl.h"
#include "scoped_ptr.h"
#include "unhide_globals.h"
#include <string>

#ifndef GLS_CTL_FALLBACK_ENABLED
#    include "gls_text.h"
#    define CTL_BASE_CLASS GlsText
#else
#    include "gls_text_box.h"
#    define CTL_BASE_CLASS GlsTextBox
#endif

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

// Force inclusion of the pango libraries
#ifdef WIN32
#    if !defined( NO_GLS_AUTOLIB ) && !defined( GLS_IMPORT_LIBRARY )
#        ifdef _WIN64
#            define PANGO_SUFFIX "_64"
#        else
#            define PANGO_SUFFIX ""
#        endif
#        pragma message( "Will automatically link with libpango" PANGO_SUFFIX "-1.0.lib" )
#        pragma message( "Will automatically link with libpangoft2" PANGO_SUFFIX "-1.0.lib" )
#        pragma message( "Will automatically link with libgobject" PANGO_SUFFIX "-2.0.lib" )
#        pragma comment( lib, "libpango" PANGO_SUFFIX "-1.0.lib" )
#        pragma comment( lib, "libpangoft2" PANGO_SUFFIX "-1.0.lib" )
#        pragma comment( lib, "libgobject" PANGO_SUFFIX "-2.0.lib" )
#    endif
#endif

namespace disti
{
// Forward Declarations
#ifndef GLS_CTL_FALLBACK_ENABLED
class GlsPangoWrapper;
struct PangoRect;
#else
class GlsTextBoxFontRenderer;
#endif // GLS_CTL_FALLBACK_ENABLED

#ifdef GLES
class GlsGloFileAttribute;
class GlsStateManager;
class GlsQuadListVCT_2D;
#endif // GLES

//===========================================================================
/** \brief The Gls CTL (Complex Text Layout) Text Box.
  * 
  * On certain platforms, the text layout library is unavailable, and complex text rendering in the runtime will be missing.
  * 
  * To account for this, the GlsCTLTextBox will 'Fallback' to being treated as a GlsTextBox.  In those cases, certain 
  * GlsCTLTextBox functions will not have no effect.
  */
class GlsCTLTextBox : public CTL_BASE_CLASS
{
public:
    typedef CTL_BASE_CLASS _BaseClass;

    /** The internal border between the layout edges and the glyph edges.
      * This will keep the glyph edges from appearing cut-off when linear texture filtering is applied. 
      */
    static const unsigned int INTERNAL_BORDER = 1;

    friend class GlsCTLTextBoxEditor;

#ifndef GLS_CTL_FALLBACK_ENABLED
    /** The vertical alignment types. */
    enum VerticalAlignment_t{
        ALIGN_CENTER,
        ALIGN_TOP,
        ALIGN_BOTTOM
    };
#else
    typedef Align_t VerticalAlignment_t;
#endif // GLS_CTL_FALLBACK_ENABLED

    /** Deprecated */
    enum VerticalAlignmentCTL_t
    {
        VERTICAL_ALIGNMENT_CENTER = ALIGN_CENTER,
        VERTICAL_ALIGNMENT_TOP    = ALIGN_TOP,
        VERTICAL_ALIGNMENT_BOTTOM = ALIGN_BOTTOM
    };

    /** The ellipsize mode types. */
    enum EllipsizeMode_t
    {
        ELLIPSIZE_MODE_NONE,
        ELLIPSIZE_MODE_START,
        ELLIPSIZE_MODE_MIDDLE,
        ELLIPSIZE_MODE_END
    };

    /** The structure returned to the caller when getting the glyph metrics.
      * These are in logical units, relative to the bottom-left corner of the text box.
      */
    struct GlyphMetrics
    {
        float minX;
        float minY;
        float maxX;
        float maxY;

        GlyphMetrics()
            : minX( 0.0f )
            , minY( 0.0f )
            , maxX( 0.0f )
            , maxY( 0.0f )
        {}
    };

    /** Default constructor. */
    GLSGEN_GLSCTLTEXTBOX_EXPORT GlsCTLTextBox();

    /** The copy constructor for GlsCTLTextBox
     * 
     * \param that          The GlsCTLTextBox object that is being copied
     * \param generateNames Whether or not to generate a new instance name
     */
    GLSGEN_GLSCTLTEXTBOX_EXPORT GlsCTLTextBox( const GlsCTLTextBox& that, const bool generateNames );

    /** Destructor.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT ~GlsCTLTextBox();

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetAvailableAttributes( unsigned int value );

#ifndef GLS_CTL_FALLBACK_ENABLED
    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT DisplayObject* CloneObject( bool generateNames = false );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void CopyGeometry( DisplayObject* src );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void CopyProperties( DisplayObject* src );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void PreDraw( const OpenGLMatrices& current, Culler& culler );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void Draw();

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetVertices( unsigned int nPoints, Vertex* vertices );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void Scale( float px, float py, float pz, Vertex* anchor, int handleBar );

    /** Print a string into this text object.
      * Replaces the entire string.
      * \param format  printf style varargs formatting string.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void VaString( const char* format, ... );

    /** Set the vertical alignment for this text object
      * \param[in] verticalAlignment The vertical alignment type.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void VerticalAlignment( VerticalAlignment_t verticalAlignment );
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void VerticalAlignment( VerticalAlignmentCTL_t verticalAlignment ) { VerticalAlignment( static_cast<VerticalAlignment_t>( verticalAlignment ) ); }

    /** Get the vertical alignment for this text object
      * \return The vertical alignment type.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT VerticalAlignment_t VerticalAlignment();

#else

    /** Set the vertical alignment for this text object
      * \param[in] verticalAlignment The vertical alignment type.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void VerticalAlignment( VerticalAlignment_t verticalAlignment ) { _BaseClass::VerticalAlignment( verticalAlignment ); }
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void VerticalAlignment( VerticalAlignmentCTL_t verticalAlignment );

#endif // GLS_CTL_FALLBACK_ENABLED

#ifndef GLES

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL );

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void GetCppInterfaceDescriptionFree( InterfaceListType* array );

#endif // GLES

    /** Rebuilds this text box layout.  This may be an expensive call, so it should only be called when a property changes.
      * \note In CTL Fallback mode, GlsText::SetRebuild will be called instead, as this is a protected method in GlsTextBox.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void Rebuild();

    // NO CTL-only functions should be disabled when using the GlsTextBox fallback.
    // They should be available to every runtime, even if they do nothing.

    /** Gets the type of automatic ellipsize if the text does not fit in the boundary.
      * \return The type of automatic ellipsize if the text does not fit in the boundary.
      * \note In CTL Fallback mode, returns ELLIPSIZE_MODE_NONE.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT EllipsizeMode_t EllipsizeMode();

    /** Sets the type of automatic ellipsize if the text does not fit in the boundary.
      * \param[in] ellipsizeMode The type of automatic ellipsize if the text does not fit in the boundary.
      * \note In CTL Fallback mode, has no effect.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void EllipsizeMode( const EllipsizeMode_t ellipsizeMode );

    /** Gets the number of lines in the layout.
      * \return The number of lines in the layout.
      * \note In CTL Fallback mode, returns 0.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT unsigned int GetLineCount();

    /** Gets the number of glyphs in the layout.
      * \return The number of glyphs in the layout.
      * \note In CTL Fallback mode, returns 0.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT unsigned int GetGlyphCount();

    /** Gets the glyph metrics for the given glyph index.
      * \param[in] glyphIndex The index of the glyph in the layout line to get the glyph metrics for.
      * \return The glyph metrics for the given glyph index.
      * \note In CTL Fallback mode, returns a default GlyphMetrics struct.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT GlyphMetrics GetGlyphMetrics( const unsigned int glyphIndex );

    /** Set the Pango Layout auto dir, exposes pango_layout_set_auto_dir () 
     * see: https://developer.gnome.org/pango/stable/pango-Layout-Objects.html#pango-layout-set-auto-dir
     * \param[in] autoDir Whether or not the layout should automatically determine base direction based on content
      * \note In CTL Fallback mode, has no effect.
     */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetLayoutAutoDir( bool autoDir );

    /** Set width used to render the text.  If the width of the vertices is smaller than this width, the text will be truncated.  If the
      * value is 0.0, the text will be rendered to the full width of the vertices
      * \note In CTL Fallback mode, has no effect.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetAltWidth( float width );

    /** Set height used to render the text.  If the height of the vertices is smaller than this height, the text will be truncated.  If the
      * value is 0.0, the text will be rendered to the full height of the vertices
      * \note In CTL Fallback mode, has no effect.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetAltHeight( float height );

    /** Scales the text horizontally by the given value.  Text is still clamped by the bounds of the text box 
      * \param value the horizontal scale
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void TextHorizontalScale( float value );

    /** Get the horizontal scale */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT float TextHorizontalScale();

    /** Scales the text vertically by the given value.  Text is still clamped by the bounds of the text box 
      * \param value the vertical scale
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void TextVerticalScale( float value );

    /** Get the vertical scale */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT float TextVerticalScale();

    /** \see GlsText */
    bool RequiresFontFile() const DISTI_METHOD_OVERRIDE
    {
        return true;
    }

protected:
#ifndef GLS_CTL_FALLBACK_ENABLED
    /** Width used to render the text */
    float _altWidth;
    /** Height used to render the text */
    float _altHeight;

    /** the horizontal scale */
    float _textHorizontalScale;
    /** the vertical scale */
    float _textVerticalScale;

    /** Pointer to the internal data needed for Pango. */
    ScopedPtr<GlsPangoWrapper> _glsPangoWrapper;

    /** makes adjustment to the image verts and texture coords for the alt width / height and text scaling properties
      * \param[inout] verts the image verts
      * \param[inout] texCoords the image texture coords
      */
    void AdjustImageVertsAndCoords( PangoRect& verts, PangoRect& texCoords );

#endif // GLS_CTL_FALLBACK_ENABLED

#ifdef GLES

    // See DisplayObject
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void SetFromGloData( GlsGloFileAttribute& data );

#    ifndef GLS_CTL_FALLBACK_ENABLED
    /** The list of quads to draw for the shadows. */
    ScopedPtr<GlsQuadListVCT_2D> _shadows;
    /** The list of quads to draw for the characters. */
    ScopedPtr<GlsQuadListVCT_2D> _characters;

    /** True if _geometryRefresh was true in PreDraw.  This is just so we can rebuild the quads in Draw(). */
    bool _geometryRefreshDraw;

    /** Populate the quad storage
      * \param stateManager  
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void PopulateQuadStorage( IGlsStateManager* stateManager );

    /** Draws the polygons that make up the characters.
      * \param stateManager  
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void DrawText( IGlsStateManager* stateManager );
#    endif // GLS_CTL_FALLBACK_ENABLED

#else
    /** Draws the polygons that make up the characters.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void DrawText();
#endif // GLES
#ifndef GLS_CTL_FALLBACK_ENABLED
    /** Rebuilds the vertices of the text box.
      */
    virtual GLSGEN_GLSCTLTEXTBOX_EXPORT void RecalcVertices();
#endif // GLS_CTL_FALLBACK_ENABLED

private:
    /* See base class */
    void OnCellDimensionChanged()
    {
        // Prevent changing cell dimensions for CTL Textbox
        _cellHeight = 0;
        _cellWidth  = 0;
        ControlCellSize( false );
    }

    GlsCTLTextBox& operator=( const GlsCTLTextBox& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    GlsCTLTextBox( const GlsCTLTextBox& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

#ifndef GLS_CTL_FALLBACK_ENABLED

/** In stream operator for VerticalAlignment_t enumeration.
  */
inline std::istream& operator>>( std::istream& instr, disti::GlsCTLTextBox::VerticalAlignment_t& verticalAlignment )
{
    std::string str;
    instr >> str;

    if( str == "ALIGN_TOP" || str == "VERTICAL_ALIGNMENT_TOP" )
    {
        verticalAlignment = disti::GlsCTLTextBox::ALIGN_TOP;
    }
    else if( str == "ALIGN_CENTER" || str == "VERTICAL_ALIGNMENT_CENTER" )
    {
        verticalAlignment = disti::GlsCTLTextBox::ALIGN_CENTER;
    }
    else if( str == "ALIGN_BOTTOM" || str == "VERTICAL_ALIGNMENT_BOTTOM" )
    {
        verticalAlignment = disti::GlsCTLTextBox::ALIGN_BOTTOM;
    }
    return instr;
}

/** Out stream operator for VerticalAlignment_t enumeration.
  */
inline std::ostream& operator<<( std::ostream& outstr, disti::GlsCTLTextBox::VerticalAlignment_t verticalAlignment )
{
    switch( verticalAlignment )
    {
    case disti::GlsCTLTextBox::ALIGN_TOP:
        outstr << "ALIGN_TOP";
        break;
    case disti::GlsCTLTextBox::ALIGN_CENTER:
        outstr << "ALIGN_CENTER";
        break;
    case disti::GlsCTLTextBox::ALIGN_BOTTOM:
        outstr << "ALIGN_BOTTOM";
        break;
    }
    return outstr;
}
#endif // GLS_CTL_FALLBACK_ENABLED

/** In stream operator for EllipsizeMode_t enumeration.
  */
inline std::istream& operator>>( std::istream& instr, disti::GlsCTLTextBox::EllipsizeMode_t& ellipsizeMode )
{
    std::string str;
    instr >> str;

    if( str == "ELLIPSIZE_MODE_NONE" )
    {
        ellipsizeMode = disti::GlsCTLTextBox::ELLIPSIZE_MODE_NONE;
    }
    else if( str == "ELLIPSIZE_MODE_START" )
    {
        ellipsizeMode = disti::GlsCTLTextBox::ELLIPSIZE_MODE_START;
    }
    else if( str == "ELLIPSIZE_MODE_MIDDLE" )
    {
        ellipsizeMode = disti::GlsCTLTextBox::ELLIPSIZE_MODE_MIDDLE;
    }
    else if( str == "ELLIPSIZE_MODE_END" )
    {
        ellipsizeMode = disti::GlsCTLTextBox::ELLIPSIZE_MODE_END;
    }
    return instr;
}

/** Out stream operator for EllipsizeMode_t enumeration.
  */
inline std::ostream& operator<<( std::ostream& outstr, disti::GlsCTLTextBox::EllipsizeMode_t ellipsizeMode )
{
    switch( ellipsizeMode )
    {
    case disti::GlsCTLTextBox::ELLIPSIZE_MODE_NONE:
        outstr << "ELLIPSIZE_MODE_NONE";
        break;
    case disti::GlsCTLTextBox::ELLIPSIZE_MODE_START:
        outstr << "ELLIPSIZE_MODE_START";
        break;
    case disti::GlsCTLTextBox::ELLIPSIZE_MODE_MIDDLE:
        outstr << "ELLIPSIZE_MODE_MIDDLE";
        break;
    case disti::GlsCTLTextBox::ELLIPSIZE_MODE_END:
        outstr << "ELLIPSIZE_MODE_END";
        break;
    }
    return outstr;
}

} // namespace disti

#endif // INCLUDED_GLS_CTL_TEXT_BOX_H