content/base/public/nsLineBreaker.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Novell code.
  16  *
  17  * The Initial Developer of the Original Code is Novell.
  18  * Portions created by the Initial Developer are Copyright (C) 2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *         Robert O'Callahan <robert@ocallahan.org> (Original Author)
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef NSLINEBREAKER_H_
  39 #define NSLINEBREAKER_H_
  40
  41 #include "nsString.h"
  42 #include "nsTArray.h"
  43 #include "nsILineBreaker.h"
  44
  45 class nsIAtom;
  46
  47 /**
  48  * A receiver of line break data.
  49  */
  50 class nsILineBreakSink {
  51 public:
  52   /**
  53    * Sets the break data for a substring of the associated text chunk.
  54    * One or more of these calls will be performed; the union of all substrings
  55    * will cover the entire text chunk. Substrings may overlap (i.e., we may
  56    * set the break-before state of a character more than once).
  57    * @param aBreakBefore the break-before states for the characters in the substring.
  58    */
  59   virtual void SetBreaks(PRUint32 aStart, PRUint32 aLength, PRPackedBool* aBreakBefore) = 0;
  60
  61   /**
  62    * Indicates which characters should be capitalized. Only called if
  63    * BREAK_NEED_CAPITALIZATION was requested.
  64    */
  65   virtual void SetCapitalization(PRUint32 aStart, PRUint32 aLength, PRPackedBool* aCapitalize) = 0;
  66 };
  67
  68 /**
  69  * A line-breaking state machine. You feed text into it via AppendText calls
  70  * and it computes the possible line breaks. Because break decisions can
  71  * require a lot of context, the breaks for a piece of text are sometimes not
  72  * known until later text has been seen (or all text ends). So breaks are
  73  * returned via a call to SetBreaks on the nsILineBreakSink object passed
  74  * with each text chunk, which might happen during the corresponding AppendText
  75  * call, or might happen during a later AppendText call or even a Reset()
  76  * call.
  77  *
  78  * The linebreak results MUST NOT depend on how the text is broken up
  79  * into AppendText calls.
  80  *
  81  * The current strategy is that we break the overall text into
  82  * whitespace-delimited "words". Then those words are passed to the nsILineBreaker
  83  * service for deeper analysis if they contain a "complex" character as described
  84  * below.
  85  *
  86  * This class also handles detection of which characters should be capitalized
  87  * for text-transform:capitalize. This is a good place to handle that because
  88  * we have all the context we need.
  89  */
  90 class nsLineBreaker {
  91 public:
  92   nsLineBreaker();
  93   ~nsLineBreaker();
  94
  95   static inline PRBool IsSpace(PRUnichar u) { return NS_IsSpace(u); }
  96
  97   static inline PRBool IsComplexASCIIChar(PRUnichar u)
  98   {
  99     return !((0x0030 <= u && u <= 0x0039) ||
 100              (0x0041 <= u && u <= 0x005A) ||
 101              (0x0061 <= u && u <= 0x007A));
 102   }
 103
 104   static inline PRBool IsComplexChar(PRUnichar u)
 105   {
 106     return IsComplexASCIIChar(u) ||
 107            NS_NeedsPlatformNativeHandling(u) ||
 108            (0x1100 <= u && u <= 0x11ff) || // Hangul Jamo
 109            (0x2000 <= u && u <= 0x21ff) || // Punctuations and Symbols
 110            (0x2e80 <= u && u <= 0xd7ff) || // several CJK blocks
 111            (0xf900 <= u && u <= 0xfaff) || // CJK Compatibility Idographs
 112            (0xff00 <= u && u <= 0xffef);   // Halfwidth and Fullwidth Forms
 113   }
 114
 115   // Break opportunities exist at the end of each run of breakable whitespace
 116   // (see IsSpace above). Break opportunities can also exist between pairs of
 117   // non-whitespace characters, as determined by nsILineBreaker. We pass a whitespace-
 118   // delimited word to nsILineBreaker if it contains at least one character
 119   // matching IsComplexChar.
 120   // We provide flags to control on a per-chunk basis where breaks are allowed.
 121   // At any character boundary, exactly one text chunk governs whether a
 122   // break is allowed at that boundary.
 123   //
 124   // We operate on text after whitespace processing has been applied, so
 125   // other characters (e.g. tabs and newlines) may have been converted to
 126   // spaces.
 127
 128   /**
 129    * Flags passed with each chunk of text.
 130    */
 131   enum {
 132     /*
 133      * Do not introduce a break opportunity at the start of this chunk of text.
 134      */
 135     BREAK_SUPPRESS_INITIAL = 0x01,
 136     /**
 137      * Do not introduce a break opportunity in the interior of this chunk of text.
 138      * Also, whitespace in this chunk is treated as non-breakable.
 139      */
 140     BREAK_SUPPRESS_INSIDE = 0x02,
 141     /**
 142      * The sink currently is already set up to have no breaks in it;
 143      * if no breaks are possible, nsLineBreaker does not need to call
 144      * SetBreaks on it. This is useful when handling large quantities of
 145      * preformatted text; the textruns will never have any breaks set on them,
 146      * and there is no need to ever actually scan the text for breaks, except
 147      * at the end of textruns in case context is needed for following breakable
 148      * text.
 149      */
 150     BREAK_SKIP_SETTING_NO_BREAKS = 0x04,
 151     /**
 152      * We need to be notified of characters that should be capitalized
 153      * (as in text-transform:capitalize) in this chunk of text.
 154      */
 155     BREAK_NEED_CAPITALIZATION = 0x08
 156   };
 157
 158   /**
 159    * Append "invisible whitespace". This acts like whitespace, but there is
 160    * no actual text associated with it. Only the BREAK_SUPPRESS_INSIDE flag
 161    * is relevant here.
 162    */
 163   nsresult AppendInvisibleWhitespace(PRUint32 aFlags);
 164
 165   /**
 166    * Feed Unicode text into the linebreaker for analysis. aLength must be
 167    * nonzero.
 168    * @param aSink can be null if the breaks are not actually needed (we may
 169    * still be setting up state for later breaks)
 170    */
 171   nsresult AppendText(nsIAtom* aLangGroup, const PRUnichar* aText, PRUint32 aLength,
 172                       PRUint32 aFlags, nsILineBreakSink* aSink);
 173   /**
 174    * Feed 8-bit text into the linebreaker for analysis. aLength must be nonzero.
 175    * @param aSink can be null if the breaks are not actually needed (we may
 176    * still be setting up state for later breaks)
 177    */
 178   nsresult AppendText(nsIAtom* aLangGroup, const PRUint8* aText, PRUint32 aLength,
 179                       PRUint32 aFlags, nsILineBreakSink* aSink);
 180   /**
 181    * Reset all state. This means the current run has ended; any outstanding
 182    * calls through nsILineBreakSink are made, and all outstanding references to
 183    * nsILineBreakSink objects are dropped.
 184    * After this call, this linebreaker can be reused.
 185    * This must be called at least once between any call to AppendText() and
 186    * destroying the object.
 187    * @param aTrailingBreak this is set to true when there is a break opportunity
 188    * at the end of the text. This will normally only be declared true when there
 189    * is breakable whitespace at the end.
 190    */
 191   nsresult Reset(PRBool* aTrailingBreak);
 192
 193 private:
 194   // This is a list of text sources that make up the "current word" (i.e.,
 195   // run of text which does not contain any whitespace). All the mLengths
 196   // are are nonzero, these cannot overlap.
 197   struct TextItem {
 198     TextItem(nsILineBreakSink* aSink, PRUint32 aSinkOffset, PRUint32 aLength,
 199              PRUint32 aFlags)
 200       : mSink(aSink), mSinkOffset(aSinkOffset), mLength(aLength), mFlags(aFlags) {}
 201
 202     nsILineBreakSink* mSink;
 203     PRUint32          mSinkOffset;
 204     PRUint32          mLength;
 205     PRUint32          mFlags;
 206   };
 207
 208   // State for the nonwhitespace "word" that started in previous text and hasn't
 209   // finished yet.
 210
 211   // When the current word ends, this computes the linebreak opportunities
 212   // *inside* the word (excluding either end) and sets them through the
 213   // appropriate sink(s). Then we clear the current word state.
 214   nsresult FlushCurrentWord();
 215
 216   nsAutoTArray<PRUnichar,100> mCurrentWord;
 217   // All the items that contribute to mCurrentWord
 218   nsAutoTArray<TextItem,2>    mTextItems;
 219   PRPackedBool                mCurrentWordContainsComplexChar;
 220
 221   // True if the previous character was breakable whitespace
 222   PRPackedBool                mAfterBreakableSpace;
 223   // True if a break must be allowed at the current position because
 224   // a run of breakable whitespace ends here
 225   PRPackedBool                mBreakHere;
 226 };
 227
 228 #endif /*NSLINEBREAKER_H_*/