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