mi32/bidi.h

Go to the documentation of this file.

/**
 * \file bidi.h <mi32/bidi.h>
 * \brief BiDirectional text conversion
 *
 * \if NODOC
 * $Id: bidi.h_v 1.15 2006/02/16 16:11:10 dwilliss Exp $
 *
 * $Log: bidi.h_v $
 * Revision 1.15  2006/02/16 16:11:10  dwilliss
 * renamed obsolete #define
 *
 * Revision 1.14  2005/03/31 16:57:09  fileserver!dwilliss
 * Rename one of our types to MIUNICODE because it conflicted with a Microsoft #define
 *
 * Revision 1.13  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.12  2003/07/09 14:36:20  mju
 * Fix endif.
 * Use conventional name for classlibexport.
 *
 * Revision 1.11  2003/07/09 14:34:26  dwilliss
 * Define and undefine MUSYSTEMCLASSEXPORT ourselves.  Don't expect ucstring
 * to do it for us, cause it shouldn't have been leaving it defined in the
 * first place
 *
 * Revision 1.10  2002/07/05 14:34:20  dwilliss
 * Undefine USEEXPORTPRAGMA before end of include file
 *
 * Revision 1.9  2000/12/07 22:51:00  dwilliss
 * Added method to get cursor position relative to visual string
 *
 * Revision 1.8  2000/12/01 22:21:24  dwilliss
 * Added method to set cursor position in visual units.
 *
 * Revision 1.7  2000/10/13 16:43:52  dwilliss
 * Must use "friend class NAME", not "friend NAME"
 *
 * Revision 1.6  2000/06/07 20:00:22  dwilliss
 * Renamed a #define for Mike
 *
 * Revision 1.5  2000/05/22 16:55:33  dwilliss
 * Cleaned up. Split out BIDI cursor into a derived class so we don't
 * have to keep track of cursor info in "normal" cases
 *
 * \endif
 */

#ifndef INC_MI32_BIDI_H
#define INC_MI32_BIDI_H

#ifndef INC_MI32_UCSTRING_H
#include <mi32/ucstring.h>
#endif

#ifdef MISYSTEMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif

class BIDICURSOR;

//!
//! This class handles the Bi-Directional ("BiDi") issues of rendering
//! strings which have a mixture of Left-To-Right and Right-To-Left
//! text (such as Hebrew and Arabic)
//!
//! Besides flipping the string as necessary, it can also keep track
//! or a cursor position within the string and resolve the logical 
//! position of the cursor withing the string while moving in visual
//! order.
//!
class CLASSLIBEXPORT BIDISTRING {
public:
   // Enums
   
   enum DIRECTION {
      DIRECTION_LTR,
      DIRECTION_RTL 
      };

   enum ORDER {
      ORDER_VISUAL,
      ORDER_LOGICAL
      };

   // Constructors

   BIDISTRING();

   //! Construct with initial values
   BIDISTRING (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR,
      ORDER StringOrder = ORDER_LOGICAL
      );

   // Destructor
   
   virtual ~BIDISTRING();

   // Methods

   //! Clear the string.
   void Clear (
      );

   //! Get the primary direction of the string.
   DIRECTION GetStringDirection (
      ) const;

   //! Return a copy of the string in logical order.
   //! Caller should free the returned string.
   MIUNICODE* GetStringLogical (
      ) const;

   //! Return a copy of the string in visual order.
   //! Caller should free the returned string.
   MIUNICODE* GetStringVisual (
      ) const;

   //! Set the string from a logical order string.
   //!
   //! Note: Normally, the directionality of a string is determined by the first
   //! strongly directional character in the string.  In this case, the DefaultDirection
   //! is only used as a fallback, unless bForceDirection is true.
   //! 
   void SetStringLogical (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR,
      bool bForceDirection = false
      );

   //! Set the string from a visual order string.
   //! Nore: The DefaultDirection is VERY important with a visual order string.
   //! This is because it is impossible to tell by looking at a visual order
   //! string if it was supposed to be right-to-left or left-to-right.  Take
   //! the following examples: (assume lowercase letters are left-to-right and
   //! capital letters are right to left)
   //!
   //! <table>
   //! <tr><td></td><td>logical</td><td>visual</td></tr>
   //! <tr><td>1</td><td>ABC abc DEF</td><td>FED abc CBA</td></tr>
   //! <tr><td>2</td><td>ABC abc DEF def</td><td>def FED abc CBA</td></tr>
   //! <tr><td>3</td><td>abc ABC def</td><td>abc CBA def</td></tr>
   //! <tr><td>4</td><td>abc ABC def DEF def</td><td>abc CBA def FED</td></tr>
   //! </table>
   //!
   //!  Strings 1 and 2 are right-to-left, 3 and 4 are left to right (based
   //!  on the first character in the logical order string).  Without prior
   //!  knowledge of the source strings, you can't tell what direction they
   //!  were by looking at the visual order strings.
   //!
   void SetStringVisual (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR
      );

private:
   #ifndef GENERATING_DOXYGEN_OUTPUT
   class SPAN {
      public:

      SPAN (
         BIDISTRING* str,
         const MIUNICODE* src,
         UINT32 start,
         UINT32 end,
         DIRECTION direction,
         ORDER format
         );

      ~SPAN();

      // Members
      SPAN *m_VisualPrev;  //!< Pointer to the previous visual run.    
      SPAN *m_VisualNext;  //!< Pointer to the next visual run.       

      SPAN *m_LogicalPrev; //!< Pointer to the previous logical run. 
      SPAN *m_LogicalNext; //!< Pointer to the next logical run.    

      DIRECTION m_direction;           //!< Direction of the run.            

      INT32 m_cursor;             //!< Position of "cursor" in the string. (-1 means just before first char)
                              

      MIUNICODE *m_chars;          //!< List of characters for the run.  
      UINT32 *m_positions;      //!< List of original positions in source.

      UINT32 m_start;           //!< Beginning offset in the source string.
      UINT32 m_end;             //!< Ending offset in the source string.  
      };

   void AddLTRLogicalSegment (
      const MIUNICODE* source,
      UINT32 start,
      UINT32 end
      );

   void AddRTLLogicalSegment (
      const MIUNICODE* source,
      UINT32 start,
      UINT32 end
      );

   void AddLTRVisualSegment (
      const MIUNICODE* source,
      UINT32 start,
      UINT32 end
      );

   void AddRTLVisualSegment (
      const MIUNICODE* source,
      UINT32 start,
      UINT32 end
      );

   //! Set the string
   //! SetStringLogical() first calls Clear() then calls SetStringLogicalNoClear()
   //! The constructor doesn't bother to call Clear()
   void SetStringLogicalNoClear (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR,
      bool bForceDirection = false
      );

   //! Set the string
   //! SetStringVisual() first calls Clear() then calls SetStringVisualNoClear()
   void SetStringVisualNoClear (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR
      );


   // Members
   DIRECTION m_direction;            //!< Overall direction of the string. 


   SPAN *m_cursor;              //!< The run containing the "cursor."    

   SPAN *m_LogicalFirst;       //!< First run in the logical order.    
   SPAN *m_LogicalLast;        //!< Last run in the logical order.    

   SPAN *m_VisualFirst;        //!< First run in the visual order.   
   SPAN *m_VisualLast;         //!< Last run in the visual order.   

   MIUNICODE *m_source;          //!< The logical order string.           
   UINT32 m_start;            //!< The beginning offset in the source. (always 0)
   UINT32 m_end;              //!< The ending offset in the source.  
   bool m_bNeedCursorInfo;

   friend class BIDISTRING::SPAN;
   friend class BIDICURSOR;
   #endif // GENERATING_DOXYGEN_OUTPUT
   };


//!
//! An extention of BIDISTRING to handle cursor support.
//!
//!   This takes a lot more memory than BIDISTRING itself.
//!
class CLASSLIBEXPORT BIDICURSOR : public BIDISTRING {
public:
   // Constructors
   BIDICURSOR ();


   //! Construct with initial values.
   //! Note, this one doesn't let you specify the string order.
   //! The string passed to the constructor must be in logical order.
   BIDICURSOR (
      const MIUNICODE* source,
      DIRECTION DefaultDirection = DIRECTION_LTR
      );

   // Destructor
   virtual ~BIDICURSOR();

   // Methods

   //! Move the cursor to the left.
   //!
   //! This method moves the cursor to the left in either the logical or
   //! visual order depending on the current setting of CursorMotion.
   //! It moves the cursor "count" spaces to the left and returns the
   //! new offset from the beginning of the logical string.
   UINT32 CursorLeft (
      UINT32 count
      );

   //! Move the cursor to the right.
   //!
   //! This method moves the cursor to the right in either the logical or
   //! visual order depending on the current setting of CursorMotion.
   //! It moves the cursor "count" spaces to the right and returns the
   //! new offset from the beginning of the logical string.
   UINT32 CursorRight (
      UINT32 count
      );

   //! Return the direction of the text under the cursor.
   //! Returns the direction that the text under the cursor should
   //! be read.
   DIRECTION GetCursorDirection (
      ) const;

   //! Returns the current CursorMotion setting.
   //! Logical cursor motion means that moving to the right will step
   //! through the data in the order it is in memory, which may or may
   //! not be the same as on the screen.  Visual motion is what you
   //! expect on the screen.
   ORDER GetCursorMotion (
      ) const;

   
   //! Get the current cursor position relative to the start of the string in
   //! it's logical order.  The cursor should be thought of as a box covering
   //! the character position returned.
   UINT32 GetCursorPosition (
      ) const;

   //! Get the current cursor position relative to the start of the string in
   //! it's visual order.  The cursor should be thought of as a box covering
   //! the character position returned.
   UINT32 GetCursorPositionVisual (
      ) const;

   //! Set the cursor motion.
   //! Returns the previous value
   ORDER SetCursorMotion (
      ORDER CursorMotion
      );

   //! Set the cursor position (visual order, left-most glyph == 0)
   void SetCursorPositionVisual (
      UINT32 pos
      );

private:
   #ifndef GENERATING_DOXYGEN_OUTPUT
   UINT32 CursorLeftLogical (
      UINT32 count
      );

   UINT32 CursorRightLogical (
      UINT32 count
      );

   UINT32 CursorLeftVisual (
      UINT32 count
      );

   UINT32 CursorRightVisual (
      UINT32 count
      );

   ORDER m_CursorMotion;        //!< Logical or visual cursor motion flag.
   #endif // GENERATING_DOXYGEN_OUTPUT
   };



#undef CLASSLIBEXPORT 


#endif //!<  INC_MI32_BIDI_H 

---