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
18class GURL;
19
20namespace base {
21class FilePath;
22}
23
24namespace gfx {
25class FontList;
26
27GFX_EXPORT extern const char kEllipsis[];
28GFX_EXPORT extern const base::char16 kEllipsisUTF16[];
29GFX_EXPORT extern const base::char16 kForwardSlash;
30
31// Helper class to split + elide text, while respecting UTF16 surrogate pairs.
32class 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.
67GFX_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.
78GFX_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.
94GFX_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).
106GFX_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.
114enum 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.
135enum 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).
148GFX_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.
160GFX_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_
167