ICU-59173.0.1.tar.gz

[apple/icu.git] / icuSources / layoutex / layout / ParagraphLayout.h

diff --git a/icuSources/layoutex/layout/ParagraphLayout.h b/icuSources/layoutex/layout/ParagraphLayout.h
index a2c8e172a5ba3b6bc3a44fcb1ee72675c611336f..0d9f08f7343f0fcbfd66e3d81a3c070692419302 100644 (file)
--- a/icuSources/layoutex/layout/ParagraphLayout.h
+++ b/icuSources/layoutex/layout/ParagraphLayout.h
@@ -1,6 +1,8 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html

 /*
  **********************************************************************
 /*
  **********************************************************************

- *   Copyright (C) 2002-2003, International Business Machines
+ *   Copyright (C) 2002-2014, International Business Machines

  *   Corporation and others.  All Rights Reserved.
  **********************************************************************
  */
  *   Corporation and others.  All Rights Reserved.
  **********************************************************************
  */


@@ -9,6 +11,11 @@
 
 #define __PARAGRAPHLAYOUT_H
 
 
 #define __PARAGRAPHLAYOUT_H
 

+/**
+ * \file 
+ * \brief C++ API: Paragraph Layout
+ */
+

 /*
  * ParagraphLayout doesn't make much sense without
  * BreakIterator...
 /*
  * ParagraphLayout doesn't make much sense without
  * BreakIterator...


@@ -35,6 +42,13 @@ U_NAMESPACE_BEGIN
  *
  * Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
  *
  *
  * Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
  *

+ * Note that {@link icu::LayoutEngine} is deprecated, but this class is not.
+ * You may use this class with the HarfBuzz icu-le-hb wrapper,
+ *  see http://www.freedesktop.org/wiki/Software/HarfBuzz/
+ *
+ *  See http://userguide.icu-project.org/layoutengine for special build instructions.
+ *
+ * @see icu::LayoutEngine

  */
 class U_LAYOUTEX_API ParagraphLayout : public UObject
 {
  */
 class U_LAYOUTEX_API ParagraphLayout : public UObject
 {


@@ -50,7 +64,7 @@ public:
      * @see ParagraphLayout
      * @see ParagraphLayout::VisualRun
      *
      * @see ParagraphLayout
      * @see ParagraphLayout::VisualRun
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     class U_LAYOUTEX_API Line : public UObject
     {
      */
     class U_LAYOUTEX_API Line : public UObject
     {


@@ -61,7 +75,7 @@ public:
          * clients responsibility to destroy the objects, so the destructor
          * is public.
         *
          * clients responsibility to destroy the objects, so the destructor
          * is public.
         *

-        * @draft ICU 2.6
+        * @stable ICU 3.2

          */
         ~Line();
 
          */
         ~Line();
 


@@ -70,9 +84,9 @@ public:
          *
          * @return the number of visual runs.
          *
          *
          * @return the number of visual runs.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        le_int32 countRuns() const;
+        inline le_int32 countRuns() const;

 
         /**
          * Get the ascent of the line. This is the maximum ascent
 
         /**
          * Get the ascent of the line. This is the maximum ascent


@@ -80,7 +94,7 @@ public:
          *
          * @return the ascent of the line.
          *
          *
          * @return the ascent of the line.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
         le_int32 getAscent() const;
 
          */
         le_int32 getAscent() const;
 


@@ -90,7 +104,7 @@ public:
          *
          * @return the descent of the line.
          *
          *
          * @return the descent of the line.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
         le_int32 getDescent() const;
 
          */
         le_int32 getDescent() const;
 


@@ -100,9 +114,20 @@ public:
          *
          * @return the leading of the line.
          *
          *
          * @return the leading of the line.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
         le_int32 getLeading() const;
          */
         le_int32 getLeading() const;

+
+        /**
+         * Get the width of the line. This is a convenience method
+         * which returns the last X position of the last visual run
+         * in the line.
+         *
+         * @return the width of the line.
+         *
+         * @stable ICU 2.8
+         */
+        le_int32 getWidth() const;

     
         /**
          * Get a <code>ParagraphLayout::VisualRun</code> object for a given
     
         /**
          * Get a <code>ParagraphLayout::VisualRun</code> object for a given


@@ -117,23 +142,23 @@ public:
          *
          * @see ParagraphLayout::VisualRun
          *
          *
          * @see ParagraphLayout::VisualRun
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
         const VisualRun *getVisualRun(le_int32 runIndex) const;
 
         /**
          */
         const VisualRun *getVisualRun(le_int32 runIndex) const;
 
         /**

-         * ICU "poor man's RTTI", returns a UClassID for the actual class.
+         * ICU "poor man's RTTI", returns a UClassID for this class.

          *
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
+        static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }

 
         /**
 
         /**

-         * ICU "poor man's RTTI", returns a UClassID for this class.
+         * ICU "poor man's RTTI", returns a UClassID for the actual class.

          *
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
+        virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }

 
     private:
 
 
     private:
 


@@ -154,9 +179,9 @@ public:
 
         VisualRun **fRuns;
 
 
         VisualRun **fRuns;
 

-        Line();
-               Line(const Line &other);
-               Line &operator=(const Line & /*other*/) { return *this; };
+        inline Line();
+        inline Line(const Line &other);
+        inline Line &operator=(const Line & /*other*/) { return *this; };

 
         void computeMetrics();
 
 
         void computeMetrics();
 


@@ -172,12 +197,12 @@ public:
      * a table which maps indices into the glyph array to indices into
      * the original character array which was used to create the paragraph.
      *
      * a table which maps indices into the glyph array to indices into
      * the original character array which was used to create the paragraph.
      *

-     * These objects are only created by <code>ParagraphLayout::Line<code> objects,
+     * These objects are only created by <code>ParagraphLayout::Line</code> objects,

      * so their constructors and destructors are private.
      *
      * @see ParagraphLayout::Line
      *
      * so their constructors and destructors are private.
      *
      * @see ParagraphLayout::Line
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     class U_LAYOUTEX_API VisualRun : public UObject
     {
      */
     class U_LAYOUTEX_API VisualRun : public UObject
     {


@@ -192,9 +217,9 @@ public:
          *
          * @see LEFontInstance
          *
          *
          * @see LEFontInstance
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        const LEFontInstance *getFont() const;
+        inline const LEFontInstance *getFont() const;

 
         /**
          * Get the direction of the visual run.
 
         /**
          * Get the direction of the visual run.


@@ -202,18 +227,18 @@ public:
          * @return the direction of the run. This will be UBIDI_LTR if the
          *         run is left-to-right and UBIDI_RTL if the line is right-to-left.
          *
          * @return the direction of the run. This will be UBIDI_LTR if the
          *         run is left-to-right and UBIDI_RTL if the line is right-to-left.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        UBiDiDirection getDirection() const;
+        inline UBiDiDirection getDirection() const;

 
         /**
          * Get the number of glyphs in the visual run.
          *
          * @return the number of glyphs.
          *
 
         /**
          * Get the number of glyphs in the visual run.
          *
          * @return the number of glyphs.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        le_int32 getGlyphCount() const;
+        inline le_int32 getGlyphCount() const;

 
         /**
          * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
 
         /**
          * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and


@@ -223,9 +248,9 @@ public:
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        const LEGlyphID *getGlyphs() const;
+        inline const LEGlyphID *getGlyphs() const;

 
         /**
          * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
 
         /**
          * Get the (x, y) positions of the glyphs in the visual run. To simplify storage


@@ -238,9 +263,9 @@ public:
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        const float *getPositions() const;
+        inline const float *getPositions() const;

 
         /**
          * Get the glyph-to-character map for this visual run. This maps the indices into
 
         /**
          * Get the glyph-to-character map for this visual run. This maps the indices into


@@ -250,9 +275,9 @@ public:
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *
          *         is owned by the <code>VisualRun</code> object and must not be deleted.
          *         It will remain valid as long as the <code>VisualRun</code> object is valid.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        const le_int32 *getGlyphToCharMap() const;
+        inline const le_int32 *getGlyphToCharMap() const;

 
         /**
          * A convenience method which returns the ascent value for the font
 
         /**
          * A convenience method which returns the ascent value for the font


@@ -260,9 +285,9 @@ public:
          *
          * @return the ascent value of this run's font.
          *
          *
          * @return the ascent value of this run's font.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        le_int32 getAscent() const;
+        inline le_int32 getAscent() const;

 
         /**
          * A convenience method which returns the descent value for the font
 
         /**
          * A convenience method which returns the descent value for the font


@@ -270,9 +295,9 @@ public:
          *
          * @return the descent value of this run's font.
          *
          *
          * @return the descent value of this run's font.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        le_int32 getDescent() const;
+        inline le_int32 getDescent() const;

 
         /**
          * A convenience method which returns the leading value for the font
 
         /**
          * A convenience method which returns the leading value for the font


@@ -280,23 +305,23 @@ public:
          *
          * @return the leading value of this run's font.
          *
          *
          * @return the leading value of this run's font.
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        le_int32 getLeading() const;
+        inline le_int32 getLeading() const;

 
         /**
 
         /**

-         * ICU "poor man's RTTI", returns a UClassID for the actual class.
+         * ICU "poor man's RTTI", returns a UClassID for this class.

          *
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
+        static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }

 
         /**
 
         /**

-         * ICU "poor man's RTTI", returns a UClassID for this class.
+         * ICU "poor man's RTTI", returns a UClassID for the actual class.

          *
          *

-         * @draft ICU 2.6
+         * @stable ICU 3.2

          */
          */

-        static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
+        virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }

 
     private:
 
 
     private:
 


@@ -317,11 +342,11 @@ public:
 
         friend class Line;
 
 
         friend class Line;
 

-        VisualRun();
-               VisualRun(const VisualRun &other);
-               VisualRun &operator=(const VisualRun &other) { return *this; };
+        inline VisualRun();
+        inline VisualRun(const VisualRun &other);
+        inline VisualRun &operator=(const VisualRun &/*other*/) { return *this; };

 
 

-        VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
+        inline VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,

                   const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
 
         ~VisualRun();
                   const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
 
         ~VisualRun();


@@ -336,6 +361,9 @@ public:
      * Clients can optionally specify directional runs and / or script runs. If these aren't specified
      * they will be computed.
      *
      * Clients can optionally specify directional runs and / or script runs. If these aren't specified
      * they will be computed.
      *

+     * If any errors are encountered during construction, <code>status</code> will be set, and the object
+     * will be set to be empty.
+     *

      * @param chars is an array of the characters in the paragraph
      *
      * @param count is the number of characters in the paragraph.
      * @param chars is an array of the characters in the paragraph
      *
      * @param count is the number of characters in the paragraph.


@@ -356,27 +384,30 @@ public:
      *
      * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
      *
      *
      * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
      *

-     * @param vertical is <code>true</code> if the paragraph should be set vertically.
+     * @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
+     *
+     * @param status will be set to any error code encountered during construction.

      *
      * @see ubidi.h
      * @see LEFontInstance.h
      * @see LayoutEngine.h
      * @see RunArrays.h
      *
      *
      * @see ubidi.h
      * @see LEFontInstance.h
      * @see LayoutEngine.h
      * @see RunArrays.h
      *

-     * @draft ICU 2.6
+     * @stable ICU 2.8

      */
     ParagraphLayout(const LEUnicode chars[], le_int32 count,
                     const FontRuns *fontRuns,
                     const ValueRuns *levelRuns,
                     const ValueRuns *scriptRuns,
                     const LocaleRuns *localeRuns,
      */
     ParagraphLayout(const LEUnicode chars[], le_int32 count,
                     const FontRuns *fontRuns,
                     const ValueRuns *levelRuns,
                     const ValueRuns *scriptRuns,
                     const LocaleRuns *localeRuns,

-                    UBiDiLevel paragraphLevel, le_bool vertical);
+                    UBiDiLevel paragraphLevel, le_bool vertical,
+                    LEErrorCode &status);

 
     /**
      * The destructor. Virtual so that it works correctly with
      * sublcasses.
      *
 
     /**
      * The destructor. Virtual so that it works correctly with
      * sublcasses.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     ~ParagraphLayout();
 
      */
     ~ParagraphLayout();
 


@@ -395,9 +426,9 @@ public:
      *
      * @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
      *
      *
      * @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
      *

-     * @return <code>true</code> if the paragraph contains complex text.
+     * @return <code>TRUE</code> if the paragraph contains complex text.

      *
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     static le_bool isComplex(const LEUnicode chars[], le_int32 count, const FontRuns *fontRuns);
 #else
      */
     static le_bool isComplex(const LEUnicode chars[], le_int32 count, const FontRuns *fontRuns);
 #else


@@ -409,9 +440,9 @@ public:
      *
      * @param count is the number of characters in the paragraph.
      *
      *
      * @param count is the number of characters in the paragraph.
      *

-     * @return <code>true</code> if any of the text requires complex processing.
+     * @return <code>TRUE</code> if any of the text requires complex processing.

      *
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     static le_bool isComplex(const LEUnicode chars[], le_int32 count);
 
      */
     static le_bool isComplex(const LEUnicode chars[], le_int32 count);
 


@@ -424,9 +455,9 @@ public:
      *
      * @return the resolved paragraph level.
      *
      *
      * @return the resolved paragraph level.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
      */

-    UBiDiLevel getParagraphLevel();
+    inline UBiDiLevel getParagraphLevel();

 
     /**
      * Return the directionality of the text in the paragraph.
 
     /**
      * Return the directionality of the text in the paragraph.


@@ -435,9 +466,9 @@ public:
      *         <code>UBIDI_RTL</code> if the text is all right to left,
      *         or <code>UBIDI_MIXED</code> if the text has mixed direction.
      *
      *         <code>UBIDI_RTL</code> if the text is all right to left,
      *         or <code>UBIDI_MIXED</code> if the text has mixed direction.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
      */

-    UBiDiDirection getTextDirection();
+    inline UBiDiDirection getTextDirection();

 
     /**
      * Return the max ascent value for all the fonts
 
     /**
      * Return the max ascent value for all the fonts


@@ -445,7 +476,7 @@ public:
      *
      * @return the ascent value.
      *
      *
      * @return the ascent value.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     virtual le_int32 getAscent() const;
 
      */
     virtual le_int32 getAscent() const;
 


@@ -455,7 +486,7 @@ public:
      *
      * @return the decent value.
      *
      *
      * @return the decent value.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     virtual le_int32 getDescent() const;
 
      */
     virtual le_int32 getDescent() const;
 


@@ -465,7 +496,7 @@ public:
      *
      * @return the leading value.
      *
      *
      * @return the leading value.
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     virtual le_int32 getLeading() const;
 
      */
     virtual le_int32 getLeading() const;
 


@@ -473,9 +504,22 @@ public:
      * Reset line breaking to start from the beginning of the paragraph.
      *
      *
      * Reset line breaking to start from the beginning of the paragraph.
      *
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2
+     */
+    inline void reflow();
+
+#ifndef U_HIDE_INTERNAL_API
+    /**
+     *
+     * Convenience method for determining if paragraph layout processing is complete ( i.e. there
+     * are no more lines left to process. )
+     *
+     * @return true if there are no more lines to be processed
+     *
+     * @internal 

      */
      */

-    void reflow();
+    inline le_bool isDone() const;
+#endif  /* U_HIDE_INTERNAL_API */

 
     /**
      * Return a <code>ParagraphLayout::Line</code> object which represents next line
 
     /**
      * Return a <code>ParagraphLayout::Line</code> object which represents next line


@@ -488,27 +532,27 @@ public:
      *
      * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
      *         is responsible for deleting the object. Returns <code>NULL</code> if there are no
      *
      * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
      *         is responsible for deleting the object. Returns <code>NULL</code> if there are no

-        *         more lines in the paragraph.
+     *         more lines in the paragraph.

      *
      * @see ParagraphLayout::Line
      *
      *
      * @see ParagraphLayout::Line
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
     Line *nextLine(float width);
 
     /**
      */
     Line *nextLine(float width);
 
     /**

-     * ICU "poor man's RTTI", returns a UClassID for the actual class.
+     * ICU "poor man's RTTI", returns a UClassID for this class.

      *
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
      */

-    virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
+    static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }

 
     /**
 
     /**

-     * ICU "poor man's RTTI", returns a UClassID for this class.
+     * ICU "poor man's RTTI", returns a UClassID for the actual class.

      *
      *

-     * @draft ICU 2.6
+     * @stable ICU 3.2

      */
      */

-    static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
+    virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }

 
 private:
 
 
 private:
 


@@ -536,7 +580,7 @@ private:
 
     ParagraphLayout() {};
     ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};
 
     ParagraphLayout() {};
     ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};

-    ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };
+    inline ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };

 
     void computeLevels(UBiDiLevel paragraphLevel);
 
 
     void computeLevels(UBiDiLevel paragraphLevel);
 


@@ -547,7 +591,7 @@ private:
 
     void computeLocales();
 
 
     void computeLocales();
 

-    void computeSubFonts(const FontRuns *fontRuns);
+    void computeSubFonts(const FontRuns *fontRuns, LEErrorCode &status);

 
     void computeMetrics();
 
 
     void computeMetrics();
 


@@ -580,7 +624,8 @@ private:
           le_int32 fLeading;
 
           le_int32 *fGlyphToCharMap;
           le_int32 fLeading;
 
           le_int32 *fGlyphToCharMap;

-          le_int32 *fCharToGlyphMap;
+          le_int32 *fCharToMinGlyphMap;
+          le_int32 *fCharToMaxGlyphMap;

           float    *fGlyphWidths;
           le_int32  fGlyphCount;
 
           float    *fGlyphWidths;
           le_int32  fGlyphCount;
 


@@ -685,7 +730,7 @@ inline ParagraphLayout::VisualRun::VisualRun()
     // nothing
 }
 
     // nothing
 }
 

-inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &other)
+inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &/*other*/)

     : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
 {
     // nothing
     : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
 {
     // nothing


@@ -699,13 +744,6 @@ inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance *font, UBiDiDi
     // nothing else needs to be done!
 }
 
     // nothing else needs to be done!
 }
 

-inline ParagraphLayout::VisualRun::~VisualRun()
-{
-    LE_DELETE_ARRAY(fGlyphToCharMap);
-    LE_DELETE_ARRAY(fPositions);
-    LE_DELETE_ARRAY(fGlyphs);
-}
-

 U_NAMESPACE_END
 #endif
 #endif
 U_NAMESPACE_END
 #endif
 #endif