Home | History | Annotate | Download | only in i18n 
      1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef BASE_I18N_RTL_H_
      6 #define BASE_I18N_RTL_H_
      7 
      8 #include <string>
      9 
     10 #include "base/compiler_specific.h"
     11 #include "base/i18n/base_i18n_export.h"
     12 #include "base/strings/string16.h"
     13 #include "build/build_config.h"
     14 
     15 namespace base {
     16 
     17 class FilePath;
     18 
     19 namespace i18n {
     20 
     21 const char16 kRightToLeftMark = 0x200F;
     22 const char16 kLeftToRightMark = 0x200E;
     23 const char16 kLeftToRightEmbeddingMark = 0x202A;
     24 const char16 kRightToLeftEmbeddingMark = 0x202B;
     25 const char16 kPopDirectionalFormatting = 0x202C;
     26 const char16 kLeftToRightOverride = 0x202D;
     27 const char16 kRightToLeftOverride = 0x202E;
     28 
     29 // Locale.java mirrored this enum TextDirection. Please keep in sync.
     30 enum TextDirection {
     31   UNKNOWN_DIRECTION = 0,
     32   RIGHT_TO_LEFT = 1,
     33   LEFT_TO_RIGHT = 2,
     34   TEXT_DIRECTION_MAX = LEFT_TO_RIGHT,
     35 };
     36 
     37 // Get the locale that the currently running process has been configured to use.
     38 // The return value is of the form language[-country] (e.g., en-US) where the
     39 // language is the 2 or 3 letter code from ISO-639.
     40 BASE_I18N_EXPORT std::string GetConfiguredLocale();
     41 
     42 // Canonicalize a string (eg. a POSIX locale string) to a Chrome locale name.
     43 BASE_I18N_EXPORT std::string GetCanonicalLocale(const std::string& locale);
     44 
     45 // Sets the default locale of ICU.
     46 // Once the application locale of Chrome in GetApplicationLocale is determined,
     47 // the default locale of ICU need to be changed to match the application locale
     48 // so that ICU functions work correctly in a locale-dependent manner.
     49 // This is handy in that we don't have to call GetApplicationLocale()
     50 // everytime we call locale-dependent ICU APIs as long as we make sure
     51 // that this is called before any locale-dependent API is called.
     52 BASE_I18N_EXPORT void SetICUDefaultLocale(const std::string& locale_string);
     53 
     54 // Returns true if the application text direction is right-to-left.
     55 BASE_I18N_EXPORT bool IsRTL();
     56 
     57 // A test utility function to set the application default text direction.
     58 BASE_I18N_EXPORT void SetRTLForTesting(bool rtl);
     59 
     60 // Returns whether the text direction for the default ICU locale is RTL.  This
     61 // assumes that SetICUDefaultLocale has been called to set the default locale to
     62 // the UI locale of Chrome.
     63 // NOTE: Generally, you should call IsRTL() instead of this.
     64 BASE_I18N_EXPORT bool ICUIsRTL();
     65 
     66 // Gets the explicitly forced text direction for debugging. If no forcing is
     67 // applied, returns UNKNOWN_DIRECTION.
     68 BASE_I18N_EXPORT TextDirection GetForcedTextDirection();
     69 
     70 // Returns the text direction for |locale_name|.
     71 // As a startup optimization, this method checks the locale against a list of
     72 // Chrome-supported RTL locales.
     73 BASE_I18N_EXPORT TextDirection
     74 GetTextDirectionForLocaleInStartUp(const char* locale_name);
     75 
     76 // Returns the text direction for |locale_name|.
     77 BASE_I18N_EXPORT TextDirection GetTextDirectionForLocale(
     78     const char* locale_name);
     79 
     80 // Given the string in |text|, returns the directionality of the first or last
     81 // character with strong directionality in the string. If no character in the
     82 // text has strong directionality, LEFT_TO_RIGHT is returned. The Bidi
     83 // character types L, LRE, LRO, R, AL, RLE, and RLO are considered as strong
     84 // directionality characters. Please refer to http://unicode.org/reports/tr9/
     85 // for more information.
     86 BASE_I18N_EXPORT TextDirection GetFirstStrongCharacterDirection(
     87     const string16& text);
     88 BASE_I18N_EXPORT TextDirection GetLastStrongCharacterDirection(
     89     const string16& text);
     90 
     91 // Given the string in |text|, returns LEFT_TO_RIGHT or RIGHT_TO_LEFT if all the
     92 // strong directionality characters in the string are of the same
     93 // directionality. It returns UNKNOWN_DIRECTION if the string contains a mix of
     94 // LTR and RTL strong directionality characters. Defaults to LEFT_TO_RIGHT if
     95 // the string does not contain directionality characters. Please refer to
     96 // http://unicode.org/reports/tr9/ for more information.
     97 BASE_I18N_EXPORT TextDirection GetStringDirection(const string16& text);
     98 
     99 // Given the string in |text|, this function modifies the string in place with
    100 // the appropriate Unicode formatting marks that mark the string direction
    101 // (either left-to-right or right-to-left). The function checks both the current
    102 // locale and the contents of the string in order to determine the direction of
    103 // the returned string. The function returns true if the string in |text| was
    104 // properly adjusted.
    105 //
    106 // Certain LTR strings are not rendered correctly when the context is RTL. For
    107 // example, the string "Foo!" will appear as "!Foo" if it is rendered as is in
    108 // an RTL context. Calling this function will make sure the returned localized
    109 // string is always treated as a right-to-left string. This is done by
    110 // inserting certain Unicode formatting marks into the returned string.
    111 //
    112 // ** Notes about the Windows version of this function:
    113 // TODO(idana) bug 6806: this function adjusts the string in question only
    114 // if the current locale is right-to-left. The function does not take care of
    115 // the opposite case (an RTL string displayed in an LTR context) since
    116 // adjusting the string involves inserting Unicode formatting characters that
    117 // Windows does not handle well unless right-to-left language support is
    118 // installed. Since the English version of Windows doesn't have right-to-left
    119 // language support installed by default, inserting the direction Unicode mark
    120 // results in Windows displaying squares.
    121 BASE_I18N_EXPORT bool AdjustStringForLocaleDirection(string16* text);
    122 
    123 // Undoes the actions of the above function (AdjustStringForLocaleDirection).
    124 BASE_I18N_EXPORT bool UnadjustStringForLocaleDirection(string16* text);
    125 
    126 // Ensures |text| contains no unterminated directional formatting characters, by
    127 // appending the appropriate pop-directional-formatting characters to the end of
    128 // |text|.
    129 BASE_I18N_EXPORT void EnsureTerminatedDirectionalFormatting(string16* text);
    130 
    131 // Sanitizes the |text| by terminating any directional override/embedding
    132 // characters and then adjusting the string for locale direction.
    133 BASE_I18N_EXPORT void SanitizeUserSuppliedString(string16* text);
    134 
    135 // Returns true if the string contains at least one character with strong right
    136 // to left directionality; that is, a character with either R or AL Unicode
    137 // BiDi character type.
    138 BASE_I18N_EXPORT bool StringContainsStrongRTLChars(const string16& text);
    139 
    140 // Wraps a string with an LRE-PDF pair which essentialy marks the string as a
    141 // Left-To-Right string. Doing this is useful in order to make sure LTR
    142 // strings are rendered properly in an RTL context.
    143 BASE_I18N_EXPORT void WrapStringWithLTRFormatting(string16* text);
    144 
    145 // Wraps a string with an RLE-PDF pair which essentialy marks the string as a
    146 // Right-To-Left string. Doing this is useful in order to make sure RTL
    147 // strings are rendered properly in an LTR context.
    148 BASE_I18N_EXPORT void WrapStringWithRTLFormatting(string16* text);
    149 
    150 // Wraps file path to get it to display correctly in RTL UI. All filepaths
    151 // should be passed through this function before display in UI for RTL locales.
    152 BASE_I18N_EXPORT void WrapPathWithLTRFormatting(const FilePath& path,
    153                                                 string16* rtl_safe_path);
    154 
    155 // Return the string in |text| wrapped with LRE (Left-To-Right Embedding) and
    156 // PDF (Pop Directional Formatting) marks, if needed for UI display purposes.
    157 BASE_I18N_EXPORT string16 GetDisplayStringInLTRDirectionality(
    158     const string16& text) WARN_UNUSED_RESULT;
    159 
    160 // Strip the beginning (U+202A..U+202B, U+202D..U+202E) and/or ending (U+202C)
    161 // explicit bidi control characters from |text|, if there are any. Otherwise,
    162 // return the text itself. Explicit bidi control characters display and have
    163 // semantic effect. They can be deleted so they might not always appear in a
    164 // pair.
    165 BASE_I18N_EXPORT string16 StripWrappingBidiControlCharacters(
    166     const string16& text) WARN_UNUSED_RESULT;
    167 
    168 }  // namespace i18n
    169 }  // namespace base
    170 
    171 #endif  // BASE_I18N_RTL_H_
    172