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 #ifndef UI_VIEWS_CONTROLS_LABEL_H_ 6 #define UI_VIEWS_CONTROLS_LABEL_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/compiler_specific.h" 12 #include "base/gtest_prod_util.h" 13 #include "base/strings/string16.h" 14 #include "third_party/skia/include/core/SkColor.h" 15 #include "ui/gfx/font_list.h" 16 #include "ui/gfx/text_constants.h" 17 #include "ui/views/view.h" 18 19 namespace views { 20 21 ///////////////////////////////////////////////////////////////////////////// 22 // 23 // Label class 24 // 25 // A label is a view subclass that can display a string. 26 // 27 ///////////////////////////////////////////////////////////////////////////// 28 class VIEWS_EXPORT Label : public View { 29 public: 30 // Internal class name. 31 static const char kViewClassName[]; 32 33 // The following enum is used to indicate whether using the Chrome UI's 34 // directionality as the label's directionality, or auto-detecting the label's 35 // directionality. 36 // 37 // If the label text originates from the Chrome UI, we should use the Chrome 38 // UI's directionality as the label's directionality. 39 // 40 // If the text originates from a web page, its directionality is determined 41 // based on its first character with strong directionality, disregarding what 42 // directionality the Chrome UI is. 43 enum DirectionalityMode { 44 USE_UI_DIRECTIONALITY = 0, 45 AUTO_DETECT_DIRECTIONALITY 46 }; 47 48 enum ElideBehavior { 49 NO_ELIDE, // Do not elide the label text; truncate as needed. 50 ELIDE_IN_MIDDLE, // Add ellipsis in the middle of the string as needed. 51 ELIDE_AT_END, // Add ellipsis at the end of the string as needed. 52 ELIDE_AS_EMAIL, // Elide while retaining username/domain chars as needed. 53 }; 54 55 Label(); 56 explicit Label(const string16& text); 57 Label(const string16& text, const gfx::FontList& font_list); 58 Label(const string16& text, const gfx::Font& font); // OBSOLETE 59 virtual ~Label(); 60 61 // Gets or sets the fonts used by this label. font_list()62 const gfx::FontList& font_list() const { return font_list_; } 63 virtual void SetFontList(const gfx::FontList& font_list); 64 // Obsolete gfx::Font version. Should use gfx::FontList version instead. 65 const gfx::Font& font() const; // OBSOLETE 66 virtual void SetFont(const gfx::Font& font); // OBSOLETE 67 68 // Get or set the label text. text()69 const string16& text() const { return text_; } 70 void SetText(const string16& text); 71 72 // Enables or disables auto-color-readability (enabled by default). If this 73 // is enabled, then calls to set any foreground or background color will 74 // trigger an automatic mapper that uses color_utils::GetReadableColor() to 75 // ensure that the foreground colors are readable over the background color. 76 void SetAutoColorReadabilityEnabled(bool enabled); 77 78 // Sets the color. This will automatically force the color to be readable 79 // over the current background color. 80 virtual void SetEnabledColor(SkColor color); 81 void SetDisabledColor(SkColor color); 82 enabled_color()83 SkColor enabled_color() const { return actual_enabled_color_; } 84 85 // Sets the background color. This won't be explicitly drawn, but the label 86 // will force the text color to be readable over it. 87 void SetBackgroundColor(SkColor color); background_color()88 SkColor background_color() const { return background_color_; } 89 90 // Enables a drop shadow underneath the text. 91 void SetShadowColors(SkColor enabled_color, SkColor disabled_color); 92 93 // Sets the drop shadow's offset from the text. 94 void SetShadowOffset(int x, int y); 95 96 // Disables shadows. 97 void ClearEmbellishing(); 98 99 // Sets horizontal alignment. If the locale is RTL, and the directionality 100 // mode is USE_UI_DIRECTIONALITY, the alignment is flipped around. 101 // 102 // Caveat: for labels originating from a web page, the directionality mode 103 // should be reset to AUTO_DETECT_DIRECTIONALITY before the horizontal 104 // alignment is set. Otherwise, the label's alignment specified as a parameter 105 // will be flipped in RTL locales. 106 void SetHorizontalAlignment(gfx::HorizontalAlignment alignment); 107 horizontal_alignment()108 gfx::HorizontalAlignment horizontal_alignment() const { 109 return horizontal_alignment_; 110 } 111 112 // Sets the directionality mode. The directionality mode is initialized to 113 // USE_UI_DIRECTIONALITY when the label is constructed. USE_UI_DIRECTIONALITY 114 // applies to every label that originates from the Chrome UI. However, if the 115 // label originates from a web page, its directionality is auto-detected. set_directionality_mode(DirectionalityMode mode)116 void set_directionality_mode(DirectionalityMode mode) { 117 directionality_mode_ = mode; 118 } 119 directionality_mode()120 DirectionalityMode directionality_mode() const { 121 return directionality_mode_; 122 } 123 124 // Get or set the distance in pixels between baselines of multi-line text. 125 // Default is 0, indicating the distance between lines should be the standard 126 // one for the label's text, font list, and platform. line_height()127 int line_height() const { return line_height_; } 128 void SetLineHeight(int height); 129 130 // Get or set if the label text can wrap on multiple lines; default is false. is_multi_line()131 bool is_multi_line() const { return is_multi_line_; } 132 void SetMultiLine(bool multi_line); 133 134 // Sets whether the label text can be split on words. 135 // Default is false. This only works when is_multi_line is true. 136 void SetAllowCharacterBreak(bool allow_character_break); 137 138 // Sets whether the label text should be elided in the middle or end (if 139 // necessary). The default is to elide at the end. 140 // NOTE: Eliding in the middle is not supported for multi-line strings. 141 void SetElideBehavior(ElideBehavior elide_behavior); 142 143 // Sets the tooltip text. Default behavior for a label (single-line) is to 144 // show the full text if it is wider than its bounds. Calling this overrides 145 // the default behavior and lets you set a custom tooltip. To revert to 146 // default behavior, call this with an empty string. 147 void SetTooltipText(const string16& tooltip_text); 148 149 // Resizes the label so its width is set to the width of the longest line and 150 // its height deduced accordingly. 151 // This is only intended for multi-line labels and is useful when the label's 152 // text contains several lines separated with \n. 153 // |max_width| is the maximum width that will be used (longer lines will be 154 // wrapped). If 0, no maximum width is enforced. 155 void SizeToFit(int max_width); 156 157 // Gets/sets the flag to determine whether the label should be collapsed when 158 // it's hidden (not visible). If this flag is true, the label will return a 159 // preferred size of (0, 0) when it's not visible. set_collapse_when_hidden(bool value)160 void set_collapse_when_hidden(bool value) { collapse_when_hidden_ = value; } collapse_when_hidden()161 bool collapse_when_hidden() const { return collapse_when_hidden_; } 162 163 void SetHasFocusBorder(bool has_focus_border); 164 165 // Overridden from View: 166 virtual gfx::Insets GetInsets() const OVERRIDE; 167 virtual int GetBaseline() const OVERRIDE; 168 // Overridden to compute the size required to display this label. 169 virtual gfx::Size GetPreferredSize() OVERRIDE; 170 // Returns the height necessary to display this label with the provided width. 171 // This method is used to layout multi-line labels. It is equivalent to 172 // GetPreferredSize().height() if the receiver is not multi-line. 173 virtual int GetHeightForWidth(int w) OVERRIDE; 174 virtual const char* GetClassName() const OVERRIDE; 175 virtual View* GetTooltipHandlerForPoint(const gfx::Point& point) OVERRIDE; 176 virtual bool HitTestRect(const gfx::Rect& rect) const OVERRIDE; 177 virtual void GetAccessibleState(ui::AccessibleViewState* state) OVERRIDE; 178 // Gets the tooltip text for labels that are wider than their bounds, except 179 // when the label is multiline, in which case it just returns false (no 180 // tooltip). If a custom tooltip has been specified with SetTooltipText() 181 // it is returned instead. 182 virtual bool GetTooltipText(const gfx::Point& p, 183 string16* tooltip) const OVERRIDE; 184 185 protected: 186 // Called by Paint to paint the text. Override this to change how 187 // text is painted. 188 virtual void PaintText(gfx::Canvas* canvas, 189 const string16& text, 190 const gfx::Rect& text_bounds, 191 int flags); 192 193 virtual gfx::Size GetTextSize() const; 194 disabled_color()195 SkColor disabled_color() const { return actual_disabled_color_; } 196 197 // Overridden from View: 198 // Overridden to dirty our text bounds if we're multi-line. 199 virtual void OnBoundsChanged(const gfx::Rect& previous_bounds) OVERRIDE; 200 virtual void OnPaint(gfx::Canvas* canvas) OVERRIDE; 201 virtual void OnNativeThemeChanged(const ui::NativeTheme* theme) OVERRIDE; 202 203 private: 204 // These tests call CalculateDrawStringParams in order to verify the 205 // calculations done for drawing text. 206 FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawSingleLineString); 207 FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawMultiLineString); 208 FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawSingleLineStringInRTL); 209 FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawMultiLineStringInRTL); 210 FRIEND_TEST_ALL_PREFIXES(LabelTest, AutoDetectDirectionality); 211 212 // Calls ComputeDrawStringFlags(). 213 FRIEND_TEST_ALL_PREFIXES(LabelTest, DisableSubpixelRendering); 214 215 void Init(const string16& text, const gfx::FontList& font_list); 216 217 void RecalculateColors(); 218 219 // Returns where the text is drawn, in the receivers coordinate system. 220 gfx::Rect GetTextBounds() const; 221 222 int ComputeDrawStringFlags() const; 223 224 gfx::Rect GetAvailableRect() const; 225 226 // Returns parameters to be used for the DrawString call. 227 void CalculateDrawStringParams(string16* paint_text, 228 gfx::Rect* text_bounds, 229 int* flags) const; 230 231 // Updates any colors that have not been explicitly set from the theme. 232 void UpdateColorsFromTheme(const ui::NativeTheme* theme); 233 234 // Resets |cached_heights_| and |cached_heights_cursor_| and mark 235 // |text_size_valid_| as false. 236 void ResetCachedSize(); 237 238 bool ShouldShowDefaultTooltip() const; 239 240 string16 text_; 241 gfx::FontList font_list_; 242 SkColor requested_enabled_color_; 243 SkColor actual_enabled_color_; 244 SkColor requested_disabled_color_; 245 SkColor actual_disabled_color_; 246 SkColor background_color_; 247 248 // Set to true once the corresponding setter is invoked. 249 bool enabled_color_set_; 250 bool disabled_color_set_; 251 bool background_color_set_; 252 253 bool auto_color_readability_; 254 mutable gfx::Size text_size_; 255 mutable bool text_size_valid_; 256 int line_height_; 257 bool is_multi_line_; 258 bool allow_character_break_; 259 ElideBehavior elide_behavior_; 260 gfx::HorizontalAlignment horizontal_alignment_; 261 string16 tooltip_text_; 262 // Whether to collapse the label when it's not visible. 263 bool collapse_when_hidden_; 264 // The following member variable is used to control whether the 265 // directionality is auto-detected based on first strong directionality 266 // character or is determined by chrome UI's locale. 267 DirectionalityMode directionality_mode_; 268 // When embedded in a larger control that is focusable, setting this flag 269 // allows this view to reserve space for a focus border that it otherwise 270 // might not have because it is not itself focusable. 271 bool has_focus_border_; 272 273 // Colors for shadow. 274 SkColor enabled_shadow_color_; 275 SkColor disabled_shadow_color_; 276 277 // Space between text and shadow. 278 gfx::Point shadow_offset_; 279 280 // Should a shadow be drawn behind the text? 281 bool has_shadow_; 282 283 // The cached heights to avoid recalculation in GetHeightForWidth(). 284 std::vector<gfx::Size> cached_heights_; 285 int cached_heights_cursor_; 286 287 DISALLOW_COPY_AND_ASSIGN(Label); 288 }; 289 290 } // namespace views 291 292 #endif // UI_VIEWS_CONTROLS_LABEL_H_ 293