src/ui/gfx/text_elider.h

   1 // Copyright (c) 2012 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 // This file defines utility functions for eliding and formatting UI text.
   6
   7 #ifndef UI_GFX_TEXT_ELIDER_H_
   8 #define UI_GFX_TEXT_ELIDER_H_
   9
  10 #include <string>
  11 #include <vector>
  12
  13 #include "base/basictypes.h"
  14 #include "base/strings/string16.h"
  15 #include "third_party/icu/source/common/unicode/uchar.h"
  16 #include "third_party/icu/source/i18n/unicode/coll.h"
  17 #include "ui/gfx/gfx_export.h"
  18
  19 class GURL;
  20
  21 namespace base {
  22 class FilePath;
  23 }
  24
  25 namespace gfx {
  26 class Font;
  27 class FontList;
  28
  29 GFX_EXPORT extern const char kEllipsis[];
  30 GFX_EXPORT extern const char16 kEllipsisUTF16[];
  31
  32 // Elides a well-formed email address (e.g. username@domain.com) to fit into
  33 // |available_pixel_width| using the specified |font_list|.
  34 // This function guarantees that the string returned will contain at least one
  35 // character, other than the ellipses, on either side of the '@'. If it is
  36 // impossible to achieve these requirements: only an ellipsis will be returned.
  37 // If possible: this elides only the username portion of the |email|. Otherwise,
  38 // the domain is elided in the middle so that it splits the available width
  39 // equally with the elided username (should the username be short enough that it
  40 // doesn't need half the available width: the elided domain will occupy that
  41 // extra width).
  42 GFX_EXPORT string16 ElideEmail(const string16& email,
  43                                const gfx::FontList& font_list,
  44                                float available_pixel_width);
  45 // Obsolete version.  Use the above version which takes gfx::FontList.
  46 GFX_EXPORT string16 ElideEmail(const string16& email,
  47                                const gfx::Font& font,
  48                                float available_pixel_width);
  49
  50 // This function takes a GURL object and elides it. It returns a string
  51 // which composed of parts from subdomain, domain, path, filename and query.
  52 // A "..." is added automatically at the end if the elided string is bigger
  53 // than the |available_pixel_width|. For |available_pixel_width| == 0, a
  54 // formatted, but un-elided, string is returned. |languages| is a comma
  55 // separated list of ISO 639 language codes and is used to determine what
  56 // characters are understood by a user. It should come from
  57 // |prefs::kAcceptLanguages|.
  58 //
  59 // Note: in RTL locales, if the URL returned by this function is going to be
  60 // displayed in the UI, then it is likely that the string needs to be marked
  61 // as an LTR string (using base::i18n::WrapStringWithLTRFormatting()) so that it
  62 // is displayed properly in an RTL context. Please refer to
  63 // http://crbug.com/6487 for more information.
  64 GFX_EXPORT string16 ElideUrl(const GURL& url,
  65                              const gfx::FontList& font_list,
  66                              float available_pixel_width,
  67                              const std::string& languages);
  68 // Obsolete version.  Use the above version which takes gfx::FontList.
  69 GFX_EXPORT string16 ElideUrl(const GURL& url,
  70                              const gfx::Font& font,
  71                              float available_pixel_width,
  72                              const std::string& languages);
  73
  74 enum ElideBehavior {
  75   // Add ellipsis at the end of the string.
  76   ELIDE_AT_END,
  77   // Add ellipsis in the middle of the string.
  78   ELIDE_IN_MIDDLE,
  79   // Truncate the end of the string.
  80   TRUNCATE_AT_END
  81 };
  82
  83 // Elides |text| to fit in |available_pixel_width| according to the specified
  84 // |elide_behavior|.
  85 GFX_EXPORT string16 ElideText(const string16& text,
  86                               const gfx::FontList& font_list,
  87                               float available_pixel_width,
  88                               ElideBehavior elide_behavior);
  89 // Obsolete version.  Use the above version which takes gfx::FontList.
  90 GFX_EXPORT string16 ElideText(const string16& text,
  91                               const gfx::Font& font,
  92                               float available_pixel_width,
  93                               ElideBehavior elide_behavior);
  94
  95 // Elide a filename to fit a given pixel width, with an emphasis on not hiding
  96 // the extension unless we have to. If filename contains a path, the path will
  97 // be removed if filename doesn't fit into available_pixel_width. The elided
  98 // filename is forced to have LTR directionality, which means that in RTL UI
  99 // the elided filename is wrapped with LRE (Left-To-Right Embedding) mark and
 100 // PDF (Pop Directional Formatting) mark.
 101 GFX_EXPORT string16 ElideFilename(const base::FilePath& filename,
 102                                   const gfx::FontList& font_list,
 103                                   float available_pixel_width);
 104 // Obsolete version.  Use the above version which takes gfx::FontList.
 105 GFX_EXPORT string16 ElideFilename(const base::FilePath& filename,
 106                                   const gfx::Font& font,
 107                                   float available_pixel_width);
 108
 109 // SortedDisplayURL maintains a string from a URL suitable for display to the
 110 // use. SortedDisplayURL also provides a function used for comparing two
 111 // SortedDisplayURLs for use in visually ordering the SortedDisplayURLs.
 112 //
 113 // SortedDisplayURL is relatively cheap and supports value semantics.
 114 class GFX_EXPORT SortedDisplayURL {
 115  public:
 116   SortedDisplayURL(const GURL& url, const std::string& languages);
 117   SortedDisplayURL();
 118   ~SortedDisplayURL();
 119
 120   // Compares this SortedDisplayURL to |url| using |collator|. Returns a value
 121   // < 0, = 1 or > 0 as to whether this url is less then, equal to or greater
 122   // than the supplied url.
 123   int Compare(const SortedDisplayURL& other, icu::Collator* collator) const;
 124
 125   // Returns the display string for the URL.
 126   const string16& display_url() const { return display_url_; }
 127
 128  private:
 129   // Returns everything after the host. This is used by Compare if the hosts
 130   // match.
 131   string16 AfterHost() const;
 132
 133   // Host name minus 'www.'. Used by Compare.
 134   string16 sort_host_;
 135
 136   // End of the prefix (spec and separator) in display_url_.
 137   size_t prefix_end_;
 138
 139   string16 display_url_;
 140
 141   DISALLOW_COPY_AND_ASSIGN(SortedDisplayURL);
 142 };
 143
 144 // Functions to elide strings when the font information is unknown.  As
 145 // opposed to the above functions, the ElideString() and
 146 // ElideRectangleString() functions operate in terms of character units,
 147 // not pixels.
 148
 149 // If the size of |input| is more than |max_len|, this function returns
 150 // true and |input| is shortened into |output| by removing chars in the
 151 // middle (they are replaced with up to 3 dots, as size permits).
 152 // Ex: ElideString(ASCIIToUTF16("Hello"), 10, &str) puts Hello in str and
 153 // returns false.  ElideString(ASCIIToUTF16("Hello my name is Tom"), 10, &str)
 154 // puts "Hell...Tom" in str and returns true.
 155 // TODO(tsepez): Doesn't handle UTF-16 surrogate pairs properly.
 156 // TODO(tsepez): Doesn't handle bidi properly.
 157 GFX_EXPORT bool ElideString(const string16& input, int max_len,
 158                             string16* output);
 159
 160 // Reformat |input| into |output| so that it fits into a |max_rows| by
 161 // |max_cols| rectangle of characters.  Input newlines are respected, but
 162 // lines that are too long are broken into pieces.  If |strict| is true,
 163 // we break first at naturally occuring whitespace boundaries, otherwise
 164 // we assume some other mechanism will do this in approximately the same
 165 // spot after the fact.  If the word itself is too long, we always break
 166 // intra-word (respecting UTF-16 surrogate pairs) as necssary. Truncation
 167 // (indicated by an added 3 dots) occurs if the result is still too long.
 168 //  Returns true if the input had to be truncated (and not just reformatted).
 169 GFX_EXPORT bool ElideRectangleString(const string16& input, size_t max_rows,
 170                                      size_t max_cols, bool strict,
 171                                      string16* output);
 172
 173 // Specifies the word wrapping behavior of |ElideRectangleText()| when a word
 174 // would exceed the available width.
 175 enum WordWrapBehavior {
 176   // Words that are too wide will be put on a new line, but will not be
 177   // truncated or elided.
 178   IGNORE_LONG_WORDS,
 179
 180   // Words that are too wide will be put on a new line and will be truncated to
 181   // the available width.
 182   TRUNCATE_LONG_WORDS,
 183
 184   // Words that are too wide will be put on a new line and will be elided to the
 185   // available width.
 186   ELIDE_LONG_WORDS,
 187
 188   // Words that are too wide will be put on a new line and will be wrapped over
 189   // multiple lines.
 190   WRAP_LONG_WORDS,
 191 };
 192
 193 // Indicates whether the |available_pixel_width| by |available_pixel_height|
 194 // rectangle passed to |ElideRectangleText()| had insufficient space to
 195 // accommodate the given |text|, leading to elision or truncation.
 196 enum ReformattingResultFlags {
 197   INSUFFICIENT_SPACE_HORIZONTAL = 1 << 0,
 198   INSUFFICIENT_SPACE_VERTICAL = 1 << 1,
 199 };
 200
 201 // Reformats |text| into output vector |lines| so that the resulting text fits
 202 // into an |available_pixel_width| by |available_pixel_height| rectangle with
 203 // the specified |font_list|. Input newlines are respected, but lines that are
 204 // too long are broken into pieces. For words that are too wide to fit on a
 205 // single line, the wrapping behavior can be specified with the |wrap_behavior|
 206 // param. Returns a combination of |ReformattingResultFlags| that indicate
 207 // whether the given rectangle had insufficient space to accommodate |texŧ|,
 208 // leading to elision or truncation (and not just reformatting).
 209 GFX_EXPORT int ElideRectangleText(const string16& text,
 210                                   const gfx::FontList& font_list,
 211                                   float available_pixel_width,
 212                                   int available_pixel_height,
 213                                   WordWrapBehavior wrap_behavior,
 214                                   std::vector<string16>* lines);
 215 // Obsolete version.  Use the above version which takes gfx::FontList.
 216 GFX_EXPORT int ElideRectangleText(const string16& text,
 217                                   const gfx::Font& font,
 218                                   float available_pixel_width,
 219                                   int available_pixel_height,
 220                                   WordWrapBehavior wrap_behavior,
 221                                   std::vector<string16>* lines);
 222
 223 // Truncates the string to length characters. This breaks the string at
 224 // the first word break before length, adding the horizontal ellipsis
 225 // character (unicode character 0x2026) to render ...
 226 // The supplied string is returned if the string has length characters or
 227 // less.
 228 GFX_EXPORT string16 TruncateString(const string16& string, size_t length);
 229
 230 }  // namespace gfx
 231
 232 #endif  // UI_GFX_TEXT_ELIDER_H_