am b241f60f: am c3d0a81a: Merge "Fix bug #8656546 API REVIEW: android.text.bidi / android.text" into jb-mr2-dev
* commit 'b241f60fe76677d106d472d4118d1e6959563331':
Fix bug #8656546 API REVIEW: android.text.bidi / android.text
diff --git a/api/current.txt b/api/current.txt
index 9954596..8ada2ed 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -22731,6 +22731,28 @@
method public static int getSize(android.view.View);
}
+ public final class BidiFormatter {
+ method public static android.text.BidiFormatter getInstance();
+ method public static android.text.BidiFormatter getInstance(boolean);
+ method public static android.text.BidiFormatter getInstance(java.util.Locale);
+ method public boolean getStereoReset();
+ method public boolean isRtl(java.lang.String);
+ method public boolean isRtlContext();
+ method public java.lang.String unicodeWrap(java.lang.String, android.text.TextDirectionHeuristic, boolean);
+ method public java.lang.String unicodeWrap(java.lang.String, android.text.TextDirectionHeuristic);
+ method public java.lang.String unicodeWrap(java.lang.String, boolean);
+ method public java.lang.String unicodeWrap(java.lang.String);
+ }
+
+ public static final class BidiFormatter.Builder {
+ ctor public BidiFormatter.Builder();
+ ctor public BidiFormatter.Builder(boolean);
+ ctor public BidiFormatter.Builder(java.util.Locale);
+ method public android.text.BidiFormatter build();
+ method public android.text.BidiFormatter.Builder setTextDirectionHeuristic(android.text.TextDirectionHeuristic);
+ method public android.text.BidiFormatter.Builder stereoReset(boolean);
+ }
+
public class BoringLayout extends android.text.Layout implements android.text.TextUtils.EllipsizeCallback {
ctor public BoringLayout(java.lang.CharSequence, android.text.TextPaint, int, android.text.Layout.Alignment, float, float, android.text.BoringLayout.Metrics, boolean);
ctor public BoringLayout(java.lang.CharSequence, android.text.TextPaint, int, android.text.Layout.Alignment, float, float, android.text.BoringLayout.Metrics, boolean, android.text.TextUtils.TruncateAt, int);
@@ -23225,49 +23247,6 @@
}
-package android.text.bidi {
-
- public final class BidiFormatter {
- method public java.lang.String dirAttr(java.lang.String);
- method public java.lang.String dirAttr(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String dirAttr(boolean);
- method public java.lang.String dirAttrValue(java.lang.String);
- method public java.lang.String dirAttrValue(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String dirAttrValue(boolean);
- method public java.lang.String endEdge();
- method public static android.text.bidi.BidiFormatter getInstance();
- method public static android.text.bidi.BidiFormatter getInstance(boolean);
- method public static android.text.bidi.BidiFormatter getInstance(java.util.Locale);
- method public boolean getStereoReset();
- method public boolean isRtl(java.lang.String);
- method public boolean isRtlContext();
- method public java.lang.String mark();
- method public java.lang.String markAfter(java.lang.String);
- method public java.lang.String markAfter(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String markBefore(java.lang.String);
- method public java.lang.String markBefore(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String spanWrap(java.lang.String, android.text.TextDirectionHeuristic, boolean);
- method public java.lang.String spanWrap(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String spanWrap(java.lang.String, boolean);
- method public java.lang.String spanWrap(java.lang.String);
- method public java.lang.String startEdge();
- method public java.lang.String unicodeWrap(java.lang.String, android.text.TextDirectionHeuristic, boolean);
- method public java.lang.String unicodeWrap(java.lang.String, android.text.TextDirectionHeuristic);
- method public java.lang.String unicodeWrap(java.lang.String, boolean);
- method public java.lang.String unicodeWrap(java.lang.String);
- }
-
- public static final class BidiFormatter.Builder {
- ctor public BidiFormatter.Builder();
- ctor public BidiFormatter.Builder(boolean);
- ctor public BidiFormatter.Builder(java.util.Locale);
- method public android.text.bidi.BidiFormatter build();
- method public android.text.bidi.BidiFormatter.Builder setTextDirectionHeuristic(android.text.TextDirectionHeuristic);
- method public android.text.bidi.BidiFormatter.Builder stereoReset(boolean);
- }
-
-}
-
package android.text.format {
public class DateFormat {
diff --git a/core/java/android/text/bidi/BidiFormatter.java b/core/java/android/text/BidiFormatter.java
similarity index 78%
rename from core/java/android/text/bidi/BidiFormatter.java
rename to core/java/android/text/BidiFormatter.java
index 7a08213..3fab35b 100644
--- a/core/java/android/text/bidi/BidiFormatter.java
+++ b/core/java/android/text/BidiFormatter.java
@@ -14,18 +14,14 @@
* limitations under the License.
*/
-package android.text.bidi;
+package android.text;
-import android.text.TextDirectionHeuristic;
-import android.text.TextDirectionHeuristics;
-import android.text.TextUtils;
import android.view.View;
import static android.text.TextDirectionHeuristics.FIRSTSTRONG_LTR;
import java.util.Locale;
-
/**
* Utility class for formatting text for display in a potentially opposite-directionality context
* without garbling. The directionality of the context is set at formatter creation and the
@@ -34,14 +30,12 @@
* <p>
* 1. Bidi Wrapping
* When text in one language is mixed into a document in another, opposite-directionality language,
- * e.g. when an English business name is embedded in a Hebrew web page, both the inserted string
+ * e.g. when an English business name is embedded in some Hebrew text, both the inserted string
* and the text surrounding it may be displayed incorrectly unless the inserted string is explicitly
* separated from the surrounding text in a "wrapper" that:
* <p>
- * - Declares its directionality so that the string is displayed correctly. This can be done in HTML
- * markup (e.g. a 'span dir="rtl"' element) by {@link #spanWrap} and similar methods, or - only in
- * contexts where markup can't be used - in Unicode bidi formatting codes by {@link #unicodeWrap}
- * and similar methods.
+ * - Declares its directionality so that the string is displayed correctly. This can be done in
+ * Unicode bidi formatting codes by {@link #unicodeWrap} and similar methods.
* <p>
* - Isolates the string's directionality, so it does not unduly affect the surrounding content.
* Currently, this can only be done using invisible Unicode characters of the same direction as
@@ -80,16 +74,6 @@
* estimated at run-time. The bidi formatter can do this automatically using the default
* first-strong estimation algorithm. It can also be configured to use a custom directionality
* estimation object.
- * <p>
- * 3. Escaping
- * When wrapping plain text - i.e. text that is not already HTML or HTML-escaped - in HTML markup,
- * the text must first be HTML-escaped to prevent XSS attacks and other nasty business. This of
- * course is always true, but the escaping can not be done after the string has already been wrapped
- * in markup, so the bidi formatter also serves as a last chance and includes escaping services.
- * <p>
- * Thus, in a single call, the formatter will escape the input string as specified, determine its
- * directionality, and wrap it as necessary. It is then up to the caller to insert the return value
- * in the output.
*/
public final class BidiFormatter {
@@ -134,36 +118,6 @@
private static final String RLM_STRING = Character.toString(RLM);
/**
- * "ltr" string constant.
- */
- private static final String LTR_STRING = "ltr";
-
- /**
- * "rtl" string constant.
- */
- private static final String RTL_STRING = "rtl";
-
- /**
- * "dir=\"ltr\"" string constant.
- */
- private static final String DIR_LTR_STRING = "dir=\"ltr\"";
-
- /**
- * "dir=\"rtl\"" string constant.
- */
- private static final String DIR_RTL_STRING = "dir=\"rtl\"";
-
- /**
- * "right" string constant.
- */
- private static final String RIGHT = "right";
-
- /**
- * "left" string constant.
- */
- private static final String LEFT = "left";
-
- /**
* Empty string constant.
*/
private static final String EMPTY_STRING = "";
@@ -325,102 +279,21 @@
}
/**
- * Returns "rtl" if {@code str}'s estimated directionality is RTL, and "ltr" if it is LTR.
- *
- * @param str String whose directionality is to be estimated.
- * @return "rtl" if {@code str}'s estimated directionality is RTL, and "ltr" otherwise.
- */
- public String dirAttrValue(String str) {
- return dirAttrValue(isRtl(str));
- }
-
- /**
- * Operates like {@link #dirAttrValue(String)}, but uses a given heuristic to estimate the
- * {@code str}'s directionality.
- *
- * @param str String whose directionality is to be estimated.
- * @param heuristic The text direction heuristic that will be used to estimate the {@code str}'s
- * directionality.
- * @return "rtl" if {@code str}'s estimated directionality is RTL, and "ltr" otherwise.
- */
- public String dirAttrValue(String str, TextDirectionHeuristic heuristic) {
- return dirAttrValue(heuristic.isRtl(str, 0, str.length()));
- }
-
- /**
- * Returns "rtl" if the given directionality is RTL, and "ltr" if it is LTR.
- *
- * @param isRtl Whether the directionality is RTL or not.
- * @return "rtl" if the given directionality is RTL, and "ltr" otherwise.
- */
- public String dirAttrValue(boolean isRtl) {
- return isRtl ? RTL_STRING : LTR_STRING;
- }
-
- /**
- * Returns "dir=\"ltr\"" or "dir=\"rtl\"", depending on {@code str}'s estimated directionality,
- * if it is not the same as the context directionality. Otherwise, returns the empty string.
- *
- * @param str String whose directionality is to be estimated.
- * @return "dir=\"rtl\"" for RTL text in non-RTL context; "dir=\"ltr\"" for LTR text in non-LTR
- * context; else, the empty string.
- */
- public String dirAttr(String str) {
- return dirAttr(isRtl(str));
- }
-
- /**
- * Operates like {@link #dirAttr(String)}, but uses a given heuristic to estimate the
- * {@code str}'s directionality.
- *
- * @param str String whose directionality is to be estimated.
- * @param heuristic The text direction heuristic that will be used to estimate the {@code str}'s
- * directionality.
- * @return "dir=\"rtl\"" for RTL text in non-RTL context; "dir=\"ltr\"" for LTR text in non-LTR
- * context; else, the empty string.
- */
- public String dirAttr(String str, TextDirectionHeuristic heuristic) {
- return dirAttr(heuristic.isRtl(str, 0, str.length()));
- }
-
- /**
- * Returns "dir=\"ltr\"" or "dir=\"rtl\"", depending on the given directionality, if it is not
- * the same as the context directionality. Otherwise, returns the empty string.
- *
- * @param isRtl Whether the directionality is RTL or not
- * @return "dir=\"rtl\"" for RTL text in non-RTL context; "dir=\"ltr\"" for LTR text in non-LTR
- * context; else, the empty string.
- */
- public String dirAttr(boolean isRtl) {
- return (isRtl != mIsRtlContext) ? (isRtl ? DIR_RTL_STRING : DIR_LTR_STRING) : EMPTY_STRING;
- }
-
- /**
* Returns a Unicode bidi mark matching the context directionality (LRM or RLM) if either the
* overall or the exit directionality of a given string is opposite to the context directionality.
* Putting this after the string (including its directionality declaration wrapping) prevents it
* from "sticking" to other opposite-directionality text or a number appearing after it inline
* with only neutral content in between. Otherwise returns the empty string. While the exit
* directionality is determined by scanning the end of the string, the overall directionality is
- * given explicitly in {@code dir}.
- *
- * @param str String after which the mark may need to appear.
- * @return LRM for RTL text in LTR context; RLM for LTR text in RTL context;
- * else, the empty string.
- */
- public String markAfter(String str) {
- return markAfter(str, mDefaultTextDirectionHeuristic);
- }
-
- /**
- * Operates like {@link #markAfter(String)}, but uses a given heuristic to estimate the
- * {@code str}'s directionality.
+ * given explicitly by a heuristic to estimate the {@code str}'s directionality.
*
* @param str String after which the mark may need to appear.
* @param heuristic The text direction heuristic that will be used to estimate the {@code str}'s
* directionality.
* @return LRM for RTL text in LTR context; RLM for LTR text in RTL context;
* else, the empty string.
+ *
+ * @hide
*/
public String markAfter(String str, TextDirectionHeuristic heuristic) {
final boolean isRtl = heuristic.isRtl(str, 0, str.length());
@@ -438,28 +311,18 @@
* Returns a Unicode bidi mark matching the context directionality (LRM or RLM) if either the
* overall or the entry directionality of a given string is opposite to the context
* directionality. Putting this before the string (including its directionality declaration
- * wrapping) prevents it from "sticking" to other opposite-directionality text appearing before it
- * inline with only neutral content in between. Otherwise returns the empty string. While the
+ * wrapping) prevents it from "sticking" to other opposite-directionality text appearing before
+ * it inline with only neutral content in between. Otherwise returns the empty string. While the
* entry directionality is determined by scanning the beginning of the string, the overall
- * directionality is given explicitly in {@code dir}.
- *
- * @param str String before which the mark may need to appear.
- * @return LRM for RTL text in LTR context; RLM for LTR text in RTL context;
- * else, the empty string.
- */
- public String markBefore(String str) {
- return markBefore(str, mDefaultTextDirectionHeuristic);
- }
-
- /**
- * Operates like {@link #markBefore(String)}, but uses a given heuristic to estimate the
- * {@code str}'s directionality.
+ * directionality is given explicitly by a heuristic to estimate the {@code str}'s directionality.
*
* @param str String before which the mark may need to appear.
* @param heuristic The text direction heuristic that will be used to estimate the {@code str}'s
* directionality.
* @return LRM for RTL text in LTR context; RLM for LTR text in RTL context;
* else, the empty string.
+ *
+ * @hide
*/
public String markBefore(String str, TextDirectionHeuristic heuristic) {
final boolean isRtl = heuristic.isRtl(str, 0, str.length());
@@ -474,30 +337,6 @@
}
/**
- * Returns the Unicode bidi mark matching the context directionality (LRM for LTR context
- * directionality, RLM for RTL context directionality).
- */
- public String mark() {
- return mIsRtlContext ? RLM_STRING : LRM_STRING;
- }
-
- /**
- * Returns "right" for RTL context directionality. Otherwise for LTR context directionality
- * returns "left".
- */
- public String startEdge() {
- return mIsRtlContext ? RIGHT : LEFT;
- }
-
- /**
- * Returns "left" for RTL context directionality. Otherwise for LTR context directionality
- * returns "right".
- */
- public String endEdge() {
- return mIsRtlContext ? LEFT : RIGHT;
- }
-
- /**
* Estimates the directionality of a string using the default text direction heuristic.
*
* @param str String whose directionality is to be estimated.
@@ -509,95 +348,9 @@
}
/**
- * Formats a given string of unknown directionality for use in HTML output of the context
- * directionality, so an opposite-directionality string is neither garbled nor garbles its
- * surroundings.
- * <p>
- * The algorithm: estimates the directionality of the given string using the given heuristic.
- * If the directionality is known, pass TextDirectionHeuristics.LTR or RTL for heuristic.
- * In case its directionality doesn't match the context directionality, wraps it with a 'span'
- * element and adds a "dir" attribute (either 'dir=\"rtl\"' or 'dir=\"ltr\"').
- * <p>
- * If {@code isolate}, directionally isolates the string so that it does not garble its
- * surroundings. Currently, this is done by "resetting" the directionality after the string by
- * appending a trailing Unicode bidi mark matching the context directionality (LRM or RLM) when
- * either the overall directionality or the exit directionality of the string is opposite to that
- * of the context. If the formatter was built using {@link Builder#stereoReset(boolean)} and
- * passing "true" as an argument, also prepends a Unicode bidi mark matching the context
- * directionality when either the overall directionality or the entry directionality of the
- * string is opposite to that of the context.
- * <p>
- *
- * @param str The input string.
- * @param heuristic The algorithm to be used to estimate the string's overall direction.
- * @param isolate Whether to directionally isolate the string to prevent it from garbling the
- * content around it.
- * @return Input string after applying the above processing.
- */
- public String spanWrap(String str, TextDirectionHeuristic heuristic, boolean isolate) {
- final boolean isRtl = heuristic.isRtl(str, 0, str.length());
- String origStr = str;
- str = TextUtils.htmlEncode(str);
-
- StringBuilder result = new StringBuilder();
- if (getStereoReset() && isolate) {
- result.append(markBefore(origStr,
- isRtl ? TextDirectionHeuristics.RTL : TextDirectionHeuristics.LTR));
- }
- if (isRtl != mIsRtlContext) {
- result.append("<span ").append(dirAttr(isRtl)).append('>').append(str).append("</span>");
- } else {
- result.append(str);
- }
- if (isolate) {
- result.append(markAfter(origStr,
- isRtl ? TextDirectionHeuristics.RTL : TextDirectionHeuristics.LTR));
- }
- return result.toString();
- }
-
- /**
- * Operates like {@link #spanWrap(String, TextDirectionHeuristic, boolean)}, but assumes
- * {@code isolate} is true.
- *
- * @param str The input string.
- * @param heuristic The algorithm to be used to estimate the string's overall direction.
- * @return Input string after applying the above processing.
- */
- public String spanWrap(String str, TextDirectionHeuristic heuristic) {
- return spanWrap(str, heuristic, true /* isolate */);
- }
-
- /**
- * Operates like {@link #spanWrap(String, TextDirectionHeuristic, boolean)}, but uses the
- * formatter's default direction estimation algorithm.
- *
- * @param str The input string.
- * @param isolate Whether to directionally isolate the string to prevent it from garbling the
- * content around it
- * @return Input string after applying the above processing.
- */
- public String spanWrap(String str, boolean isolate) {
- return spanWrap(str, mDefaultTextDirectionHeuristic, isolate);
- }
-
- /**
- * Operates like {@link #spanWrap(String, TextDirectionHeuristic, boolean)}, but uses the
- * formatter's default direction estimation algorithm and assumes {@code isolate} is true.
- *
- * @param str The input string.
- * @return Input string after applying the above processing.
- */
- public String spanWrap(String str) {
- return spanWrap(str, mDefaultTextDirectionHeuristic, true /* isolate */);
- }
-
- /**
* Formats a string of given directionality for use in plain-text output of the context
* directionality, so an opposite-directionality string is neither garbled nor garbles its
- * surroundings. As opposed to {@link #spanWrap}, this makes use of Unicode bidi
- * formatting characters. In HTML, its *only* valid use is inside of elements that do not allow
- * markup, e.g. the 'option' and 'title' elements.
+ * surroundings. This makes use of Unicode bidi formatting characters.
* <p>
* The algorithm: In case the given directionality doesn't match the context directionality, wraps
* the string with Unicode bidi formatting characters: RLE+{@code str}+PDF for RTL text, or