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 FontList;
  27
  28 GFX_EXPORT extern const char kEllipsis[];
  29 GFX_EXPORT extern const base::char16 kEllipsisUTF16[];
  30 GFX_EXPORT extern const base::char16 kForwardSlash;
  31
  32 // Helper class to split + elide text, while respecting UTF16 surrogate pairs.
  33 class StringSlicer {
  34  public:
  35   StringSlicer(const base::string16& text,
  36                const base::string16& ellipsis,
  37                bool elide_in_middle,
  38                bool elide_at_beginning);
  39
  40   // Cuts |text_| to be |length| characters long. If |elide_in_middle_| is true,
  41   // the middle of the string is removed to leave equal-length pieces from the
  42   // beginning and end of the string; otherwise, the end of the string is
  43   // removed and only the beginning remains. If |insert_ellipsis| is true,
  44   // then an ellipsis character will be inserted at the cut point.
  45   base::string16 CutString(size_t length, bool insert_ellipsis);
  46
  47  private:
  48   // Returns a valid cut boundary at or before/after |index|.
  49   size_t FindValidBoundaryBefore(size_t index) const;
  50   size_t FindValidBoundaryAfter(size_t index) const;
  51
  52   // The text to be sliced.
  53   const base::string16& text_;
  54
  55   // Ellipsis string to use.
  56   const base::string16& ellipsis_;
  57
  58   // If true, the middle of the string will be elided.
  59   bool elide_in_middle_;
  60
  61   // If true, the beginning of the string will be elided.
  62   bool elide_at_beginning_;
  63
  64   DISALLOW_COPY_AND_ASSIGN(StringSlicer);
  65 };
  66
  67 // Elides a well-formed email address (e.g. username@domain.com) to fit into
  68 // |available_pixel_width| using the specified |font_list|.
  69 // This function guarantees that the string returned will contain at least one
  70 // character, other than the ellipses, on either side of the '@'. If it is
  71 // impossible to achieve these requirements: only an ellipsis will be returned.
  72 // If possible: this elides only the username portion of the |email|. Otherwise,
  73 // the domain is elided in the middle so that it splits the available width
  74 // equally with the elided username (should the username be short enough that it
  75 // doesn't need half the available width: the elided domain will occupy that
  76 // extra width).
  77 GFX_EXPORT base::string16 ElideEmail(const base::string16& email,
  78                                      const gfx::FontList& font_list,
  79                                      float available_pixel_width);
  80
  81 enum ElideBehavior {
  82   // Add ellipsis at the beginning of the string.
  83   ELIDE_AT_BEGINNING,
  84   // Add ellipsis at the end of the string.
  85   ELIDE_AT_END,
  86   // Add ellipsis in the middle of the string.
  87   ELIDE_IN_MIDDLE,
  88   // Truncate the end of the string.
  89   TRUNCATE_AT_END,
  90   // No eliding of the string.
  91   NO_ELIDE,
  92 };
  93
  94 // Elides |text| to fit in |available_pixel_width| according to the specified
  95 // |elide_behavior|.
  96 GFX_EXPORT base::string16 ElideText(const base::string16& text,
  97                                     const gfx::FontList& font_list,
  98                                     float available_pixel_width,
  99                                     ElideBehavior elide_behavior);
 100
 101 // Elide a filename to fit a given pixel width, with an emphasis on not hiding
 102 // the extension unless we have to. If filename contains a path, the path will
 103 // be removed if filename doesn't fit into available_pixel_width. The elided
 104 // filename is forced to have LTR directionality, which means that in RTL UI
 105 // the elided filename is wrapped with LRE (Left-To-Right Embedding) mark and
 106 // PDF (Pop Directional Formatting) mark.
 107 GFX_EXPORT base::string16 ElideFilename(const base::FilePath& filename,
 108                                         const gfx::FontList& font_list,
 109                                         float available_pixel_width);
 110
 111 // Functions to elide strings when the font information is unknown.  As
 112 // opposed to the above functions, the ElideString() and
 113 // ElideRectangleString() functions operate in terms of character units,
 114 // not pixels.
 115
 116 // If the size of |input| is more than |max_len|, this function returns
 117 // true and |input| is shortened into |output| by removing chars in the
 118 // middle (they are replaced with up to 3 dots, as size permits).
 119 // Ex: ElideString(ASCIIToUTF16("Hello"), 10, &str) puts Hello in str and
 120 // returns false.  ElideString(ASCIIToUTF16("Hello my name is Tom"), 10, &str)
 121 // puts "Hell...Tom" in str and returns true.
 122 // TODO(tsepez): Doesn't handle UTF-16 surrogate pairs properly.
 123 // TODO(tsepez): Doesn't handle bidi properly.
 124 GFX_EXPORT bool ElideString(const base::string16& input, int max_len,
 125                             base::string16* output);
 126
 127 // Reformat |input| into |output| so that it fits into a |max_rows| by
 128 // |max_cols| rectangle of characters.  Input newlines are respected, but
 129 // lines that are too long are broken into pieces.  If |strict| is true,
 130 // we break first at naturally occuring whitespace boundaries, otherwise
 131 // we assume some other mechanism will do this in approximately the same
 132 // spot after the fact.  If the word itself is too long, we always break
 133 // intra-word (respecting UTF-16 surrogate pairs) as necssary. Truncation
 134 // (indicated by an added 3 dots) occurs if the result is still too long.
 135 //  Returns true if the input had to be truncated (and not just reformatted).
 136 GFX_EXPORT bool ElideRectangleString(const base::string16& input,
 137                                      size_t max_rows,
 138                                      size_t max_cols,
 139                                      bool strict,
 140                                      base::string16* output);
 141
 142 // Specifies the word wrapping behavior of |ElideRectangleText()| when a word
 143 // would exceed the available width.
 144 enum WordWrapBehavior {
 145   // Words that are too wide will be put on a new line, but will not be
 146   // truncated or elided.
 147   IGNORE_LONG_WORDS,
 148
 149   // Words that are too wide will be put on a new line and will be truncated to
 150   // the available width.
 151   TRUNCATE_LONG_WORDS,
 152
 153   // Words that are too wide will be put on a new line and will be elided to the
 154   // available width.
 155   ELIDE_LONG_WORDS,
 156
 157   // Words that are too wide will be put on a new line and will be wrapped over
 158   // multiple lines.
 159   WRAP_LONG_WORDS,
 160 };
 161
 162 // Indicates whether the |available_pixel_width| by |available_pixel_height|
 163 // rectangle passed to |ElideRectangleText()| had insufficient space to
 164 // accommodate the given |text|, leading to elision or truncation.
 165 enum ReformattingResultFlags {
 166   INSUFFICIENT_SPACE_HORIZONTAL = 1 << 0,
 167   INSUFFICIENT_SPACE_VERTICAL = 1 << 1,
 168 };
 169
 170 // Reformats |text| into output vector |lines| so that the resulting text fits
 171 // into an |available_pixel_width| by |available_pixel_height| rectangle with
 172 // the specified |font_list|. Input newlines are respected, but lines that are
 173 // too long are broken into pieces. For words that are too wide to fit on a
 174 // single line, the wrapping behavior can be specified with the |wrap_behavior|
 175 // param. Returns a combination of |ReformattingResultFlags| that indicate
 176 // whether the given rectangle had insufficient space to accommodate |texŧ|,
 177 // leading to elision or truncation (and not just reformatting).
 178 GFX_EXPORT int ElideRectangleText(const base::string16& text,
 179                                   const gfx::FontList& font_list,
 180                                   float available_pixel_width,
 181                                   int available_pixel_height,
 182                                   WordWrapBehavior wrap_behavior,
 183                                   std::vector<base::string16>* lines);
 184
 185 // Truncates the string to length characters. This breaks the string at
 186 // the first word break before length, adding the horizontal ellipsis
 187 // character (unicode character 0x2026) to render ...
 188 // The supplied string is returned if the string has length characters or
 189 // less.
 190 GFX_EXPORT base::string16 TruncateString(const base::string16& string,
 191                                          size_t length);
 192
 193 }  // namespace gfx
 194
 195 #endif  // UI_GFX_TEXT_ELIDER_H_