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