Home | History | Annotate | Download | only in controls 
      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_
    293