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/shadow_value.h"
  17 #include "ui/gfx/text_constants.h"
  18 #include "ui/views/view.h"
  19
  20 namespace views {
  21
  22 // A view subclass that can display a string.
  23 class VIEWS_EXPORT Label : public View {
  24  public:
  25   // Internal class name.
  26   static const char kViewClassName[];
  27
  28   // The padding for the focus border when rendering focused text.
  29   static const int kFocusBorderPadding;
  30
  31   Label();
  32   explicit Label(const base::string16& text);
  33   Label(const base::string16& text, const gfx::FontList& font_list);
  34   ~Label() override;
  35
  36   // Gets or sets the fonts used by this label.
  37   const gfx::FontList& font_list() const { return font_list_; }
  38   virtual void SetFontList(const gfx::FontList& font_list);
  39
  40   // Get or set the label text.
  41   const base::string16& text() const { return text_; }
  42   virtual void SetText(const base::string16& text);
  43
  44   // Enables or disables auto-color-readability (enabled by default).  If this
  45   // is enabled, then calls to set any foreground or background color will
  46   // trigger an automatic mapper that uses color_utils::GetReadableColor() to
  47   // ensure that the foreground colors are readable over the background color.
  48   void SetAutoColorReadabilityEnabled(bool enabled);
  49
  50   // Sets the color.  This will automatically force the color to be readable
  51   // over the current background color, if auto color readability is enabled.
  52   virtual void SetEnabledColor(SkColor color);
  53   void SetDisabledColor(SkColor color);
  54
  55   SkColor enabled_color() const { return actual_enabled_color_; }
  56
  57   // Sets the background color.  This won't be explicitly drawn, but the label
  58   // will force the text color to be readable over it.
  59   void SetBackgroundColor(SkColor color);
  60   SkColor background_color() const { return background_color_; }
  61
  62   // Set drop shadows underneath the text.
  63   void SetShadows(const gfx::ShadowValues& shadows);
  64   const gfx::ShadowValues& shadows() const { return shadows_; }
  65
  66   // Sets whether subpixel rendering is used; the default is true, but this
  67   // feature also requires an opaque background color.
  68   void SetSubpixelRenderingEnabled(bool subpixel_rendering_enabled);
  69
  70   // Sets the horizontal alignment; the argument value is mirrored in RTL UI.
  71   void SetHorizontalAlignment(gfx::HorizontalAlignment alignment);
  72   gfx::HorizontalAlignment GetHorizontalAlignment() const;
  73
  74   // Get or set the distance in pixels between baselines of multi-line text.
  75   // Default is 0, indicating the distance between lines should be the standard
  76   // one for the label's text, font list, and platform.
  77   int line_height() const { return line_height_; }
  78   void SetLineHeight(int height);
  79
  80   // Get or set if the label text can wrap on multiple lines; default is false.
  81   bool multi_line() const { return multi_line_; }
  82   void SetMultiLine(bool multi_line);
  83
  84   // Get or set if the label text should be obscured before rendering (e.g.
  85   // should "Password!" display as "*********"); default is false.
  86   bool obscured() const { return obscured_; }
  87   void SetObscured(bool obscured);
  88
  89   // Sets whether multi-line text can wrap mid-word; the default is false.
  90   void SetAllowCharacterBreak(bool allow_character_break);
  91
  92   // Sets the eliding or fading behavior, applied as necessary. The default is
  93   // to elide at the end. Eliding is not well supported for multi-line labels.
  94   void SetElideBehavior(gfx::ElideBehavior elide_behavior);
  95
  96   // Sets the tooltip text.  Default behavior for a label (single-line) is to
  97   // show the full text if it is wider than its bounds.  Calling this overrides
  98   // the default behavior and lets you set a custom tooltip.  To revert to
  99   // default behavior, call this with an empty string.
 100   void SetTooltipText(const base::string16& tooltip_text);
 101
 102   // Get or set whether this label can act as a tooltip handler; the default is
 103   // true.  Set to false whenever an ancestor view should handle tooltips
 104   // instead.
 105   bool handles_tooltips() const { return handles_tooltips_; }
 106   void SetHandlesTooltips(bool enabled);
 107
 108   // Resizes the label so its width is set to the width of the longest line and
 109   // its height deduced accordingly.
 110   // This is only intended for multi-line labels and is useful when the label's
 111   // text contains several lines separated with \n.
 112   // |max_width| is the maximum width that will be used (longer lines will be
 113   // wrapped).  If 0, no maximum width is enforced.
 114   void SizeToFit(int max_width);
 115
 116   // Sets whether the preferred size is empty when the label is not visible.
 117   void set_collapse_when_hidden(bool value) { collapse_when_hidden_ = value; }
 118
 119   // Get the text as displayed to the user, respecting the obscured flag.
 120   const base::string16& GetLayoutTextForTesting() const;
 121
 122   // View:
 123   gfx::Insets GetInsets() const override;
 124   int GetBaseline() const override;
 125   gfx::Size GetPreferredSize() const override;
 126   gfx::Size GetMinimumSize() const override;
 127   int GetHeightForWidth(int w) const override;
 128   const char* GetClassName() const override;
 129   View* GetTooltipHandlerForPoint(const gfx::Point& point) override;
 130   bool CanProcessEventsWithinSubtree() const override;
 131   void GetAccessibleState(ui::AXViewState* state) override;
 132   bool GetTooltipText(const gfx::Point& p,
 133                       base::string16* tooltip) const override;
 134
 135  protected:
 136   // Called by Paint to paint the text.
 137   void PaintText(gfx::Canvas* canvas,
 138                  const base::string16& text,
 139                  const gfx::Rect& text_bounds,
 140                  int flags);
 141
 142   virtual gfx::Size GetTextSize() const;
 143
 144   SkColor disabled_color() const { return actual_disabled_color_; }
 145
 146   // View:
 147   void OnBoundsChanged(const gfx::Rect& previous_bounds) override;
 148   void OnPaint(gfx::Canvas* canvas) override;
 149   void OnNativeThemeChanged(const ui::NativeTheme* theme) override;
 150   void OnDeviceScaleFactorChanged(float device_scale_factor) override;
 151
 152  private:
 153   struct DrawStringParams {
 154     DrawStringParams() : flags(0) {}
 155
 156     base::string16 text;
 157     gfx::Rect bounds;
 158     int flags;
 159   };
 160
 161   // These tests call CalculateDrawStringParams in order to verify the
 162   // calculations done for drawing text.
 163   FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawSingleLineString);
 164   FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawMultiLineString);
 165   FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawSingleLineStringInRTL);
 166   FRIEND_TEST_ALL_PREFIXES(LabelTest, DrawMultiLineStringInRTL);
 167   FRIEND_TEST_ALL_PREFIXES(LabelTest, DirectionalityFromText);
 168   FRIEND_TEST_ALL_PREFIXES(LabelTest, DisableSubpixelRendering);
 169
 170   // Sets both |text_| and |layout_text_| to appropriate values, taking
 171   // the label's 'obscured' status into account.
 172   void SetTextInternal(const base::string16& text);
 173
 174   void Init(const base::string16& text, const gfx::FontList& font_list);
 175
 176   void RecalculateColors();
 177
 178   // Returns where the text is drawn, in the receivers coordinate system.
 179   gfx::Rect GetTextBounds() const;
 180
 181   int ComputeDrawStringFlags() const;
 182
 183   gfx::Rect GetAvailableRect() const;
 184
 185   // Returns parameters to be used for the DrawString call. Returned value is a
 186   // weak pointer, owned by and scoped to the label.
 187   const DrawStringParams* CalculateDrawStringParams() const;
 188
 189   // Updates any colors that have not been explicitly set from the theme.
 190   void UpdateColorsFromTheme(const ui::NativeTheme* theme);
 191
 192   // Resets |cached_heights_|, |cached_heights_cursor_|, |cached_draw_params_|
 193   // and mark |text_size_valid_| as false.
 194   void ResetLayoutCache();
 195
 196   bool ShouldShowDefaultTooltip() const;
 197
 198   base::string16 text_;
 199   base::string16 layout_text_;
 200   gfx::FontList font_list_;
 201   SkColor requested_enabled_color_;
 202   SkColor actual_enabled_color_;
 203   SkColor requested_disabled_color_;
 204   SkColor actual_disabled_color_;
 205   SkColor background_color_;
 206
 207   // Set to true once the corresponding setter is invoked.
 208   bool enabled_color_set_;
 209   bool disabled_color_set_;
 210   bool background_color_set_;
 211
 212   bool subpixel_rendering_enabled_;
 213   bool auto_color_readability_;
 214   mutable gfx::Size text_size_;
 215   mutable bool text_size_valid_;
 216   int line_height_;
 217   bool multi_line_;
 218   bool obscured_;
 219   bool allow_character_break_;
 220   gfx::ElideBehavior elide_behavior_;
 221   gfx::HorizontalAlignment horizontal_alignment_;
 222   base::string16 tooltip_text_;
 223   bool handles_tooltips_;
 224   // Whether to collapse the label when it's not visible.
 225   bool collapse_when_hidden_;
 226   gfx::ShadowValues shadows_;
 227
 228   // The cached heights to avoid recalculation in GetHeightForWidth().
 229   mutable std::vector<gfx::Size> cached_heights_;
 230   mutable int cached_heights_cursor_;
 231
 232   // The cached results of CalculateDrawStringParams().
 233   mutable DrawStringParams cached_draw_params_;
 234
 235   // TODO(vadimt): Remove is_first_paint_text_ before crbug.com/431326 is
 236   // closed.
 237   bool is_first_paint_text_;
 238
 239   DISALLOW_COPY_AND_ASSIGN(Label);
 240 };
 241
 242 }  // namespace views
 243
 244 #endif  // UI_VIEWS_CONTROLS_LABEL_H_