ICU-62107.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 7aeb54d3e6259fdc1b30df629462a8396c4ea295..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-2004, 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,7 +114,7 @@ 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;
 


@@ -111,7 +125,7 @@ public:
          *
          * @return the width of the line.
          *
          *
          * @return the width of the line.
          *

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

          */
         le_int32 getWidth() const;
     
          */
         le_int32 getWidth() const;
     


@@ -128,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:
 


@@ -165,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();
 


@@ -188,7 +202,7 @@ public:
      *
      * @see ParagraphLayout::Line
      *
      *
      * @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
     {


@@ -203,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.


@@ -213,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


@@ -234,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


@@ -249,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


@@ -261,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


@@ -271,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


@@ -281,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


@@ -291,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:
 


@@ -328,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();


@@ -379,7 +393,7 @@ public:
      * @see LayoutEngine.h
      * @see RunArrays.h
      *
      * @see LayoutEngine.h
      * @see RunArrays.h
      *

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

      */
     ParagraphLayout(const LEUnicode chars[], le_int32 count,
                     const FontRuns *fontRuns,
      */
     ParagraphLayout(const LEUnicode chars[], le_int32 count,
                     const FontRuns *fontRuns,


@@ -393,7 +407,7 @@ public:
      * 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();
 


@@ -414,7 +428,7 @@ public:
      *
      * @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


@@ -428,7 +442,7 @@ public:
      *
      * @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);
 


@@ -441,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.


@@ -452,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


@@ -462,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;
 


@@ -472,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;
 


@@ -482,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;
 


@@ -490,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

      */
      */

-    void reflow();
+    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 
+     */
+    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


@@ -509,23 +536,23 @@ public:
      *
      * @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:
 


@@ -553,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);
 


@@ -703,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