src/ui/views/controls/label.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 #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.
  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.
  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
  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);
  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
 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.
 116   void set_directionality_mode(DirectionalityMode mode) {
 117     directionality_mode_ = mode;
 118   }
 119
 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.
 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.
 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.
 160   void set_collapse_when_hidden(bool value) { collapse_when_hidden_ = value; }
 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
 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_