gls_text_box.h

Go to the documentation of this file.

#ifndef _GLS_TEXT_BOX_H
#define _GLS_TEXT_BOX_H

/*! \file gls_text_box.h

\brief  This header defines the GlsTextBox class
        in the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_text.h"
#include "gls_texture_vertex_array.h"
#include "gls_class_invariant.h"

// forward ref
class GlsPolygon;

/** This class implements a box of proportionally spaced text
  * \invariant base class invariant holds,
  *            GlsTextBoxVerticalAlignmentIsValid( _verticalAlignment ),
  *            _charAttribute.IsValid(),
  *            GlsFloatIsValid( _cellWidthRatio ), GlsFloatIsValid( _startingCellY )
  */
class GlsTextBox : public GlsText
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsTextBox )

    /** enumeration describing possible vertical alignment modes */
    enum VerticalAlignment
    {
        VERTICAL_ALIGNMENT_TOP,         /**< align to top of box */
        VERTICAL_ALIGNMENT_CENTER,      /**< align to center of box */
        VERTICAL_ALIGNMENT_BOTTOM,      /**< align to bottom of box */

        #if defined( GLS_DEBUG )
            VERTICAL_ALIGNMENT_INVALID  /**< invalid vertical alignment ( GLS_DEBUG only ) */
        #endif // GLS_DEBUG
    };
        
    /** initialization parameters for a GlsTextBox */
    struct InitParameters
    {
        const GlsText::InitParameters textInitParameters; /**< base class initialization parameters */

        const VerticalAlignment       verticalAlignment;  /**< vertical alignment mode for text */

        #if defined( GLS_DEBUG )
            /** Determine if the initialization parameters are valid
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** Constructor - create an instance
      * \param initParameters initialization parameters
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid()
      * \post instance created
      */
    GlsTextBox( const InitParameters &initParameters, GlsEventDispatcher* const eventDispatcher );

    /** Set the character attributes for all of the text 
      * \param charAttribute new character attributes for the text
      * \pre charAttribue.IsValid()
      * \post text has new character attribute
      */
    virtual void SetCharAttributes( const GlsText::CharAttribute &charAttribute );

protected:
    static const GlsFloat32 TAB_SPACING;        /**< number of tab char widths to count for one tab char */

    const VerticalAlignment _verticalAlignment; /**< vertical alignment mode for text */
    GlsText::CharAttribute  _charAttribute;     /**< character attribute for all characters */

    const GlsFloat32        _cellWidthRatio;    /**< ratio of cell width to width of widest character in
                                                  * the font */
    GlsFloat32              _startingCellY;     /**< starting Y coordinate of first cell in text box
                                                  * ( populated by CalculateRowData() ) */

    /** Draw the characters associated with the text box
      * \param gl GL state manager to draw into
      * \pre all necessary GL matrix adjustments have been applied,
      *      the font texture has been bound to GL with GlsFontBase::BindFontTexture()
      *      and its texture filter settings have been setup
      * \post text characters are drawn to GL
      */
    virtual void DrawCharacters( GlsStateManager &gl );

    /** Populate the _rowInfo array and _startingCellY based on the current display string
      * \pre none
      * \post _rowInfo array and _startingCellY are populated based on the current display string
      */
    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
      */
    void GetNextRowInfo( const GlsUInt32 strIndex, GlsUInt32 &rowLength, GlsFloat32 &rowPixelWidth,
                         GlsUInt32 &nextRowStartIndex ) const;

    /**  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
      */
    GlsFloat32 GetCharWidth( const GlsChar c ) const;

    /** Destructor - shall never be called
      * \pre none
      * \post none
      */
    virtual ~GlsTextBox();

private:
    typedef GlsText _BaseClass; /**< base class alias */

    // Disable implicit generated Members
    GlsTextBox& operator=( const GlsTextBox &rhs );
    GlsTextBox( const GlsTextBox &src );
};

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given vertical alignment is valid ( GLS_DEBUG only )
  * \param verticalAlignment alignment in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsTextBoxVerticalAlignmentIsValid( const GlsTextBox::VerticalAlignment verticalAlignment )
{
    return( ( GlsTextBox::VERTICAL_ALIGNMENT_TOP    == verticalAlignment ) ||
            ( GlsTextBox::VERTICAL_ALIGNMENT_CENTER == verticalAlignment ) ||
            ( GlsTextBox::VERTICAL_ALIGNMENT_BOTTOM == verticalAlignment ) );

}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_TEXT_BOX_H