gls_text_grid.h

Go to the documentation of this file.

#ifndef _GLS_TEXT_GRID_H
#define _GLS_TEXT_GRID_H

/*! \file gls_text_grid.h

\brief  This header defines the GlsTextGrid 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 an mxn display grid of characters.
  * \invariant base class invariant holds,
  *            _columns > 0, _rows > 0,
  *            _charAttributes invariant holds,
  *            each _rowInfo element has a length field <= columns
  */
class GlsTextGrid : public GlsText
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsTextGrid )

    /** initialization parameters for a GlsTextGrid */
    struct InitParameters
    {
        const GlsText::InitParameters textInitParameters; /**< base class initialization parameters */

        const GlsUInt32 columns;                           /**< number of columns in grid ( > 0 ) */

        #if defined( GLS_DEBUG )
            /** Determine if the initialization parameters are valid ( GLS_DEBUG only )
              * \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
      */
    GlsTextGrid( 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 );

    /** Set the character attributes for a character at a given column and row
      * \param column column in question ( < _columns )
      * \param row row in question ( < _rows )
      * \param charAttribute new attributes for character at given column, row
      * \pre column < _columns, row < _rows, charAttribute.IsValid()
      * \post character at column, row has new character attributes
      */
    void SetCharAttribute( const GlsUInt32 column, const GlsUInt32 row, const GlsText::CharAttribute &charAttribute );

protected:
    /** Helper class encapsulates a grid of GlsText::CharAttribute 's
      * \invariant _columns > 0, _rows > 0,
      *            GLS_NULL != _charAttributes,
      *            each element in the _charAttributes array is valid
      */
    class CharAttributeGrid
    {
    public:
        GLS_CLASS_INVARIANT_DECLARATION( CharAttributeGrid )

        /** Constructor - create an instance
          * \param columns number of columns in grid ( > 0 )
          * \param rows number of rows in grid ( > 0 )
          * \param initialAttributes initial value of each attribute in the grid
          * \pre columns > 0, rows > 0, initialAttributes.IsValid()
          * \post instance created
          */
        CharAttributeGrid( const GlsUInt32 columns, const GlsUInt32 rows,
                           const GlsText::CharAttribute &initialAttributes );

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

        /**  get a const ref to the attribute at the given column and row
          * \param column column in question ( column < _columns )
          * \param row row in question ( row < _rows )
          * \return ref to character attribute at given column and row
          * \pre column < _columns, row < _rows
          * \post none
          */
        const GlsText::CharAttribute& GetCharAttribute( const GlsUInt32 column, const GlsUInt32 row ) const;

        /**  set the attribute at the given column and row
          * \param column column in question ( column < _columns )
          * \param row row in question ( row < _rows )
          * \param charAttribute new value for attribue
          * \pre column < _columns, row < _rows
          * \post attribute at column, row is set to new value
          */
        void SetCharAttribute( const GlsUInt32 column, const GlsUInt32 row,
                               const GlsText::CharAttribute &charAttribute );

    protected:
        const GlsUInt32               _columns;        /**< number of columns in grid ( > 0 ) */
        const GlsUInt32               _rows;           /**< number of rows in grid ( > 0 ) */
        GlsText::CharAttribute* const _charAttributes; /**< grid array of attributes (_columns*_rows) in row major */

    private:
        // Disable implicit generated Members
        CharAttributeGrid& operator=( const CharAttributeGrid &rhs );
        CharAttributeGrid( const CharAttributeGrid &src );
    };

    const GlsUInt32    _columns;                           /**< number of columns in grid ( > 0 ) */
    CharAttributeGrid  _charAttributes;                    /**< grid (_columns*_rows) of character attributes */
    GlsBool            _perCharAttributes;                 /**< GLS_TRUE if grid utilizes character attributes on
                                                             * a per character basis else GLS_FALSE if all text uses
                                                             * the first character attribute in _charAttributes */


    /** Draw the characters associated with the text grid
      * \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 based on the current display string
      * \pre none
      * \post _rowInfo array is populated based on the current display string
      */
    virtual void CalculateRowData( void );

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

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

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

#endif // _GLS_TEXT_GRID_H