base/i18n/rtl.h

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