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