Home | History | Annotate | Download | only in views
      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_VIEW_H_
      6 #define UI_VIEWS_VIEW_H_
      7 
      8 #include <algorithm>
      9 #include <map>
     10 #include <set>
     11 #include <string>
     12 #include <vector>
     13 
     14 #include "base/compiler_specific.h"
     15 #include "base/i18n/rtl.h"
     16 #include "base/logging.h"
     17 #include "base/memory/scoped_ptr.h"
     18 #include "build/build_config.h"
     19 #include "ui/accessibility/ax_enums.h"
     20 #include "ui/base/accelerators/accelerator.h"
     21 #include "ui/base/dragdrop/drag_drop_types.h"
     22 #include "ui/base/dragdrop/drop_target_event.h"
     23 #include "ui/base/dragdrop/os_exchange_data.h"
     24 #include "ui/base/ui_base_types.h"
     25 #include "ui/compositor/layer_delegate.h"
     26 #include "ui/compositor/layer_owner.h"
     27 #include "ui/events/event.h"
     28 #include "ui/events/event_target.h"
     29 #include "ui/events/event_targeter.h"
     30 #include "ui/gfx/geometry/r_tree.h"
     31 #include "ui/gfx/insets.h"
     32 #include "ui/gfx/native_widget_types.h"
     33 #include "ui/gfx/rect.h"
     34 #include "ui/gfx/vector2d.h"
     35 #include "ui/views/cull_set.h"
     36 #include "ui/views/views_export.h"
     37 
     38 #if defined(OS_WIN)
     39 #include "base/win/scoped_comptr.h"
     40 #endif
     41 
     42 using ui::OSExchangeData;
     43 
     44 namespace gfx {
     45 class Canvas;
     46 class Insets;
     47 class Path;
     48 class Transform;
     49 }
     50 
     51 namespace ui {
     52 struct AXViewState;
     53 class Compositor;
     54 class Layer;
     55 class NativeTheme;
     56 class TextInputClient;
     57 class Texture;
     58 class ThemeProvider;
     59 }
     60 
     61 namespace views {
     62 
     63 class Background;
     64 class Border;
     65 class ContextMenuController;
     66 class DragController;
     67 class FocusManager;
     68 class FocusTraversable;
     69 class InputMethod;
     70 class LayoutManager;
     71 class NativeViewAccessibility;
     72 class ScrollView;
     73 class Widget;
     74 
     75 namespace internal {
     76 class PreEventDispatchHandler;
     77 class PostEventDispatchHandler;
     78 class RootView;
     79 }
     80 
     81 /////////////////////////////////////////////////////////////////////////////
     82 //
     83 // View class
     84 //
     85 //   A View is a rectangle within the views View hierarchy. It is the base
     86 //   class for all Views.
     87 //
     88 //   A View is a container of other Views (there is no such thing as a Leaf
     89 //   View - makes code simpler, reduces type conversion headaches, design
     90 //   mistakes etc)
     91 //
     92 //   The View contains basic properties for sizing (bounds), layout (flex,
     93 //   orientation, etc), painting of children and event dispatch.
     94 //
     95 //   The View also uses a simple Box Layout Manager similar to XUL's
     96 //   SprocketLayout system. Alternative Layout Managers implementing the
     97 //   LayoutManager interface can be used to lay out children if required.
     98 //
     99 //   It is up to the subclass to implement Painting and storage of subclass -
    100 //   specific properties and functionality.
    101 //
    102 //   Unless otherwise documented, views is not thread safe and should only be
    103 //   accessed from the main thread.
    104 //
    105 /////////////////////////////////////////////////////////////////////////////
    106 class VIEWS_EXPORT View : public ui::LayerDelegate,
    107                           public ui::LayerOwner,
    108                           public ui::AcceleratorTarget,
    109                           public ui::EventTarget {
    110  public:
    111   typedef std::vector<View*> Views;
    112 
    113   // TODO(tdanderson): Becomes obsolete with the refactoring of the event
    114   //                   targeting logic for views and windows. See
    115   //                   crbug.com/355425.
    116   // Specifies the source of the region used in a hit test.
    117   // HIT_TEST_SOURCE_MOUSE indicates the hit test is being performed with a
    118   // single point and HIT_TEST_SOURCE_TOUCH indicates the hit test is being
    119   // performed with a rect larger than a single point. This value can be used,
    120   // for example, to add extra padding or change the shape of the hit test mask.
    121   enum HitTestSource {
    122     HIT_TEST_SOURCE_MOUSE,
    123     HIT_TEST_SOURCE_TOUCH
    124   };
    125 
    126   struct ViewHierarchyChangedDetails {
    127     ViewHierarchyChangedDetails()
    128         : is_add(false),
    129           parent(NULL),
    130           child(NULL),
    131           move_view(NULL) {}
    132 
    133     ViewHierarchyChangedDetails(bool is_add,
    134                                 View* parent,
    135                                 View* child,
    136                                 View* move_view)
    137         : is_add(is_add),
    138           parent(parent),
    139           child(child),
    140           move_view(move_view) {}
    141 
    142     bool is_add;
    143     // New parent if |is_add| is true, old parent if |is_add| is false.
    144     View* parent;
    145     // The view being added or removed.
    146     View* child;
    147     // If this is a move (reparent), meaning AddChildViewAt() is invoked with an
    148     // existing parent, then a notification for the remove is sent first,
    149     // followed by one for the add.  This case can be distinguished by a
    150     // non-NULL |move_view|.
    151     // For the remove part of move, |move_view| is the new parent of the View
    152     // being removed.
    153     // For the add part of move, |move_view| is the old parent of the View being
    154     // added.
    155     View* move_view;
    156   };
    157 
    158   // Creation and lifetime -----------------------------------------------------
    159 
    160   View();
    161   virtual ~View();
    162 
    163   // By default a View is owned by its parent unless specified otherwise here.
    164   void set_owned_by_client() { owned_by_client_ = true; }
    165 
    166   // Tree operations -----------------------------------------------------------
    167 
    168   // Get the Widget that hosts this View, if any.
    169   virtual const Widget* GetWidget() const;
    170   virtual Widget* GetWidget();
    171 
    172   // Adds |view| as a child of this view, optionally at |index|.
    173   void AddChildView(View* view);
    174   void AddChildViewAt(View* view, int index);
    175 
    176   // Moves |view| to the specified |index|. A negative value for |index| moves
    177   // the view at the end.
    178   void ReorderChildView(View* view, int index);
    179 
    180   // Removes |view| from this view. The view's parent will change to NULL.
    181   void RemoveChildView(View* view);
    182 
    183   // Removes all the children from this view. If |delete_children| is true,
    184   // the views are deleted, unless marked as not parent owned.
    185   void RemoveAllChildViews(bool delete_children);
    186 
    187   int child_count() const { return static_cast<int>(children_.size()); }
    188   bool has_children() const { return !children_.empty(); }
    189 
    190   // Returns the child view at |index|.
    191   const View* child_at(int index) const {
    192     DCHECK_GE(index, 0);
    193     DCHECK_LT(index, child_count());
    194     return children_[index];
    195   }
    196   View* child_at(int index) {
    197     return const_cast<View*>(const_cast<const View*>(this)->child_at(index));
    198   }
    199 
    200   // Returns the parent view.
    201   const View* parent() const { return parent_; }
    202   View* parent() { return parent_; }
    203 
    204   // Returns true if |view| is contained within this View's hierarchy, even as
    205   // an indirect descendant. Will return true if child is also this view.
    206   bool Contains(const View* view) const;
    207 
    208   // Returns the index of |view|, or -1 if |view| is not a child of this view.
    209   int GetIndexOf(const View* view) const;
    210 
    211   // Size and disposition ------------------------------------------------------
    212   // Methods for obtaining and modifying the position and size of the view.
    213   // Position is in the coordinate system of the view's parent.
    214   // Position is NOT flipped for RTL. See "RTL positioning" for RTL-sensitive
    215   // position accessors.
    216   // Transformations are not applied on the size/position. For example, if
    217   // bounds is (0, 0, 100, 100) and it is scaled by 0.5 along the X axis, the
    218   // width will still be 100 (although when painted, it will be 50x50, painted
    219   // at location (0, 0)).
    220 
    221   void SetBounds(int x, int y, int width, int height);
    222   void SetBoundsRect(const gfx::Rect& bounds);
    223   void SetSize(const gfx::Size& size);
    224   void SetPosition(const gfx::Point& position);
    225   void SetX(int x);
    226   void SetY(int y);
    227 
    228   // No transformation is applied on the size or the locations.
    229   const gfx::Rect& bounds() const { return bounds_; }
    230   int x() const { return bounds_.x(); }
    231   int y() const { return bounds_.y(); }
    232   int width() const { return bounds_.width(); }
    233   int height() const { return bounds_.height(); }
    234   const gfx::Size& size() const { return bounds_.size(); }
    235 
    236   // Returns the bounds of the content area of the view, i.e. the rectangle
    237   // enclosed by the view's border.
    238   gfx::Rect GetContentsBounds() const;
    239 
    240   // Returns the bounds of the view in its own coordinates (i.e. position is
    241   // 0, 0).
    242   gfx::Rect GetLocalBounds() const;
    243 
    244   // Returns the bounds of the layer in its own pixel coordinates.
    245   gfx::Rect GetLayerBoundsInPixel() const;
    246 
    247   // Returns the insets of the current border. If there is no border an empty
    248   // insets is returned.
    249   virtual gfx::Insets GetInsets() const;
    250 
    251   // Returns the visible bounds of the receiver in the receivers coordinate
    252   // system.
    253   //
    254   // When traversing the View hierarchy in order to compute the bounds, the
    255   // function takes into account the mirroring setting and transformation for
    256   // each View and therefore it will return the mirrored and transformed version
    257   // of the visible bounds if need be.
    258   gfx::Rect GetVisibleBounds() const;
    259 
    260   // Return the bounds of the View in screen coordinate system.
    261   gfx::Rect GetBoundsInScreen() const;
    262 
    263   // Returns the baseline of this view, or -1 if this view has no baseline. The
    264   // return value is relative to the preferred height.
    265   virtual int GetBaseline() const;
    266 
    267   // Get the size the View would like to be, if enough space were available.
    268   virtual gfx::Size GetPreferredSize() const;
    269 
    270   // Convenience method that sizes this view to its preferred size.
    271   void SizeToPreferredSize();
    272 
    273   // Gets the minimum size of the view. View's implementation invokes
    274   // GetPreferredSize.
    275   virtual gfx::Size GetMinimumSize() const;
    276 
    277   // Gets the maximum size of the view. Currently only used for sizing shell
    278   // windows.
    279   virtual gfx::Size GetMaximumSize() const;
    280 
    281   // Return the height necessary to display this view with the provided width.
    282   // View's implementation returns the value from getPreferredSize.cy.
    283   // Override if your View's preferred height depends upon the width (such
    284   // as with Labels).
    285   virtual int GetHeightForWidth(int w) const;
    286 
    287   // Set whether this view is visible. Painting is scheduled as needed.
    288   virtual void SetVisible(bool visible);
    289 
    290   // Return whether a view is visible
    291   bool visible() const { return visible_; }
    292 
    293   // Returns true if this view is drawn on screen.
    294   virtual bool IsDrawn() const;
    295 
    296   // Set whether this view is enabled. A disabled view does not receive keyboard
    297   // or mouse inputs. If |enabled| differs from the current value, SchedulePaint
    298   // is invoked.
    299   void SetEnabled(bool enabled);
    300 
    301   // Returns whether the view is enabled.
    302   bool enabled() const { return enabled_; }
    303 
    304   // This indicates that the view completely fills its bounds in an opaque
    305   // color. This doesn't affect compositing but is a hint to the compositor to
    306   // optimize painting.
    307   // Note that this method does not implicitly create a layer if one does not
    308   // already exist for the View, but is a no-op in that case.
    309   void SetFillsBoundsOpaquely(bool fills_bounds_opaquely);
    310 
    311   // Transformations -----------------------------------------------------------
    312 
    313   // Methods for setting transformations for a view (e.g. rotation, scaling).
    314 
    315   gfx::Transform GetTransform() const;
    316 
    317   // Clipping parameters. Clipping is done relative to the view bounds.
    318   void set_clip_insets(gfx::Insets clip_insets) { clip_insets_ = clip_insets; }
    319 
    320   // Sets the transform to the supplied transform.
    321   void SetTransform(const gfx::Transform& transform);
    322 
    323   // Sets whether this view paints to a layer. A view paints to a layer if
    324   // either of the following are true:
    325   // . the view has a non-identity transform.
    326   // . SetPaintToLayer(true) has been invoked.
    327   // View creates the Layer only when it exists in a Widget with a non-NULL
    328   // Compositor.
    329   void SetPaintToLayer(bool paint_to_layer);
    330 
    331   // RTL positioning -----------------------------------------------------------
    332 
    333   // Methods for accessing the bounds and position of the view, relative to its
    334   // parent. The position returned is mirrored if the parent view is using a RTL
    335   // layout.
    336   //
    337   // NOTE: in the vast majority of the cases, the mirroring implementation is
    338   //       transparent to the View subclasses and therefore you should use the
    339   //       bounds() accessor instead.
    340   gfx::Rect GetMirroredBounds() const;
    341   gfx::Point GetMirroredPosition() const;
    342   int GetMirroredX() const;
    343 
    344   // Given a rectangle specified in this View's coordinate system, the function
    345   // computes the 'left' value for the mirrored rectangle within this View. If
    346   // the View's UI layout is not right-to-left, then bounds.x() is returned.
    347   //
    348   // UI mirroring is transparent to most View subclasses and therefore there is
    349   // no need to call this routine from anywhere within your subclass
    350   // implementation.
    351   int GetMirroredXForRect(const gfx::Rect& rect) const;
    352 
    353   // Given the X coordinate of a point inside the View, this function returns
    354   // the mirrored X coordinate of the point if the View's UI layout is
    355   // right-to-left. If the layout is left-to-right, the same X coordinate is
    356   // returned.
    357   //
    358   // Following are a few examples of the values returned by this function for
    359   // a View with the bounds {0, 0, 100, 100} and a right-to-left layout:
    360   //
    361   // GetMirroredXCoordinateInView(0) -> 100
    362   // GetMirroredXCoordinateInView(20) -> 80
    363   // GetMirroredXCoordinateInView(99) -> 1
    364   int GetMirroredXInView(int x) const;
    365 
    366   // Given a X coordinate and a width inside the View, this function returns
    367   // the mirrored X coordinate if the View's UI layout is right-to-left. If the
    368   // layout is left-to-right, the same X coordinate is returned.
    369   //
    370   // Following are a few examples of the values returned by this function for
    371   // a View with the bounds {0, 0, 100, 100} and a right-to-left layout:
    372   //
    373   // GetMirroredXCoordinateInView(0, 10) -> 90
    374   // GetMirroredXCoordinateInView(20, 20) -> 60
    375   int GetMirroredXWithWidthInView(int x, int w) const;
    376 
    377   // Layout --------------------------------------------------------------------
    378 
    379   // Lay out the child Views (set their bounds based on sizing heuristics
    380   // specific to the current Layout Manager)
    381   virtual void Layout();
    382 
    383   // TODO(beng): I think we should remove this.
    384   // Mark this view and all parents to require a relayout. This ensures the
    385   // next call to Layout() will propagate to this view, even if the bounds of
    386   // parent views do not change.
    387   void InvalidateLayout();
    388 
    389   // Gets/Sets the Layout Manager used by this view to size and place its
    390   // children.
    391   // The LayoutManager is owned by the View and is deleted when the view is
    392   // deleted, or when a new LayoutManager is installed.
    393   LayoutManager* GetLayoutManager() const;
    394   void SetLayoutManager(LayoutManager* layout);
    395 
    396   // Attributes ----------------------------------------------------------------
    397 
    398   // The view class name.
    399   static const char kViewClassName[];
    400 
    401   // Return the receiving view's class name. A view class is a string which
    402   // uniquely identifies the view class. It is intended to be used as a way to
    403   // find out during run time if a view can be safely casted to a specific view
    404   // subclass. The default implementation returns kViewClassName.
    405   virtual const char* GetClassName() const;
    406 
    407   // Returns the first ancestor, starting at this, whose class name is |name|.
    408   // Returns null if no ancestor has the class name |name|.
    409   const View* GetAncestorWithClassName(const std::string& name) const;
    410   View* GetAncestorWithClassName(const std::string& name);
    411 
    412   // Recursively descends the view tree starting at this view, and returns
    413   // the first child that it encounters that has the given ID.
    414   // Returns NULL if no matching child view is found.
    415   virtual const View* GetViewByID(int id) const;
    416   virtual View* GetViewByID(int id);
    417 
    418   // Gets and sets the ID for this view. ID should be unique within the subtree
    419   // that you intend to search for it. 0 is the default ID for views.
    420   int id() const { return id_; }
    421   void set_id(int id) { id_ = id; }
    422 
    423   // A group id is used to tag views which are part of the same logical group.
    424   // Focus can be moved between views with the same group using the arrow keys.
    425   // Groups are currently used to implement radio button mutual exclusion.
    426   // The group id is immutable once it's set.
    427   void SetGroup(int gid);
    428   // Returns the group id of the view, or -1 if the id is not set yet.
    429   int GetGroup() const;
    430 
    431   // If this returns true, the views from the same group can each be focused
    432   // when moving focus with the Tab/Shift-Tab key.  If this returns false,
    433   // only the selected view from the group (obtained with
    434   // GetSelectedViewForGroup()) is focused.
    435   virtual bool IsGroupFocusTraversable() const;
    436 
    437   // Fills |views| with all the available views which belong to the provided
    438   // |group|.
    439   void GetViewsInGroup(int group, Views* views);
    440 
    441   // Returns the View that is currently selected in |group|.
    442   // The default implementation simply returns the first View found for that
    443   // group.
    444   virtual View* GetSelectedViewForGroup(int group);
    445 
    446   // Coordinate conversion -----------------------------------------------------
    447 
    448   // Note that the utility coordinate conversions functions always operate on
    449   // the mirrored position of the child Views if the parent View uses a
    450   // right-to-left UI layout.
    451 
    452   // Convert a point from the coordinate system of one View to another.
    453   //
    454   // |source| and |target| must be in the same widget, but doesn't need to be in
    455   // the same view hierarchy.
    456   // Neither |source| nor |target| can be NULL.
    457   static void ConvertPointToTarget(const View* source,
    458                                    const View* target,
    459                                    gfx::Point* point);
    460 
    461   // Convert |rect| from the coordinate system of |source| to the coordinate
    462   // system of |target|.
    463   //
    464   // |source| and |target| must be in the same widget, but doesn't need to be in
    465   // the same view hierarchy.
    466   // Neither |source| nor |target| can be NULL.
    467   static void ConvertRectToTarget(const View* source,
    468                                   const View* target,
    469                                   gfx::RectF* rect);
    470 
    471   // Convert a point from a View's coordinate system to that of its Widget.
    472   static void ConvertPointToWidget(const View* src, gfx::Point* point);
    473 
    474   // Convert a point from the coordinate system of a View's Widget to that
    475   // View's coordinate system.
    476   static void ConvertPointFromWidget(const View* dest, gfx::Point* p);
    477 
    478   // Convert a point from a View's coordinate system to that of the screen.
    479   static void ConvertPointToScreen(const View* src, gfx::Point* point);
    480 
    481   // Convert a point from a View's coordinate system to that of the screen.
    482   static void ConvertPointFromScreen(const View* dst, gfx::Point* point);
    483 
    484   // Applies transformation on the rectangle, which is in the view's coordinate
    485   // system, to convert it into the parent's coordinate system.
    486   gfx::Rect ConvertRectToParent(const gfx::Rect& rect) const;
    487 
    488   // Converts a rectangle from this views coordinate system to its widget
    489   // coordinate system.
    490   gfx::Rect ConvertRectToWidget(const gfx::Rect& rect) const;
    491 
    492   // Painting ------------------------------------------------------------------
    493 
    494   // Mark all or part of the View's bounds as dirty (needing repaint).
    495   // |r| is in the View's coordinates.
    496   // Rectangle |r| should be in the view's coordinate system. The
    497   // transformations are applied to it to convert it into the parent coordinate
    498   // system before propagating SchedulePaint up the view hierarchy.
    499   // TODO(beng): Make protected.
    500   virtual void SchedulePaint();
    501   virtual void SchedulePaintInRect(const gfx::Rect& r);
    502 
    503   // Called by the framework to paint a View. Performs translation and clipping
    504   // for View coordinates and language direction as required, allows the View
    505   // to paint itself via the various OnPaint*() event handlers and then paints
    506   // the hierarchy beneath it.
    507   virtual void Paint(gfx::Canvas* canvas, const CullSet& cull_set);
    508 
    509   // The background object is owned by this object and may be NULL.
    510   void set_background(Background* b);
    511   const Background* background() const { return background_.get(); }
    512   Background* background() { return background_.get(); }
    513 
    514   // The border object is owned by this object and may be NULL.
    515   virtual void SetBorder(scoped_ptr<Border> b);
    516   const Border* border() const { return border_.get(); }
    517   Border* border() { return border_.get(); }
    518 
    519   // Get the theme provider from the parent widget.
    520   ui::ThemeProvider* GetThemeProvider() const;
    521 
    522   // Returns the NativeTheme to use for this View. This calls through to
    523   // GetNativeTheme() on the Widget this View is in. If this View is not in a
    524   // Widget this returns ui::NativeTheme::instance().
    525   ui::NativeTheme* GetNativeTheme() {
    526     return const_cast<ui::NativeTheme*>(
    527         const_cast<const View*>(this)->GetNativeTheme());
    528   }
    529   const ui::NativeTheme* GetNativeTheme() const;
    530 
    531   // RTL painting --------------------------------------------------------------
    532 
    533   // This method determines whether the gfx::Canvas object passed to
    534   // View::Paint() needs to be transformed such that anything drawn on the
    535   // canvas object during View::Paint() is flipped horizontally.
    536   //
    537   // By default, this function returns false (which is the initial value of
    538   // |flip_canvas_on_paint_for_rtl_ui_|). View subclasses that need to paint on
    539   // a flipped gfx::Canvas when the UI layout is right-to-left need to call
    540   // EnableCanvasFlippingForRTLUI().
    541   bool FlipCanvasOnPaintForRTLUI() const {
    542     return flip_canvas_on_paint_for_rtl_ui_ ? base::i18n::IsRTL() : false;
    543   }
    544 
    545   // Enables or disables flipping of the gfx::Canvas during View::Paint().
    546   // Note that if canvas flipping is enabled, the canvas will be flipped only
    547   // if the UI layout is right-to-left; that is, the canvas will be flipped
    548   // only if base::i18n::IsRTL() returns true.
    549   //
    550   // Enabling canvas flipping is useful for leaf views that draw an image that
    551   // needs to be flipped horizontally when the UI layout is right-to-left
    552   // (views::Button, for example). This method is helpful for such classes
    553   // because their drawing logic stays the same and they can become agnostic to
    554   // the UI directionality.
    555   void EnableCanvasFlippingForRTLUI(bool enable) {
    556     flip_canvas_on_paint_for_rtl_ui_ = enable;
    557   }
    558 
    559   // Input ---------------------------------------------------------------------
    560   // The points, rects, mouse locations, and touch locations in the following
    561   // functions are in the view's coordinates, except for a RootView.
    562 
    563   // TODO(tdanderson): GetEventHandlerForPoint() and GetEventHandlerForRect()
    564   //                   will be removed once their logic is moved into
    565   //                   ViewTargeter and its derived classes. See
    566   //                   crbug.com/355425.
    567 
    568   // Convenience functions which calls into GetEventHandler() with
    569   // a 1x1 rect centered at |point|.
    570   View* GetEventHandlerForPoint(const gfx::Point& point);
    571 
    572   // If point-based targeting should be used, return the deepest visible
    573   // descendant that contains the center point of |rect|.
    574   // If rect-based targeting (i.e., fuzzing) should be used, return the
    575   // closest visible descendant having at least kRectTargetOverlap of
    576   // its area covered by |rect|. If no such descendant exists, return the
    577   // deepest visible descendant that contains the center point of |rect|.
    578   // See http://goo.gl/3Jp2BD for more information about rect-based targeting.
    579   virtual View* GetEventHandlerForRect(const gfx::Rect& rect);
    580 
    581   // Returns the deepest visible descendant that contains the specified point
    582   // and supports tooltips. If the view does not contain the point, returns
    583   // NULL.
    584   virtual View* GetTooltipHandlerForPoint(const gfx::Point& point);
    585 
    586   // Return the cursor that should be used for this view or the default cursor.
    587   // The event location is in the receiver's coordinate system. The caller is
    588   // responsible for managing the lifetime of the returned object, though that
    589   // lifetime may vary from platform to platform. On Windows and Aura,
    590   // the cursor is a shared resource.
    591   virtual gfx::NativeCursor GetCursor(const ui::MouseEvent& event);
    592 
    593   // TODO(tdanderson): HitTestPoint() and HitTestRect() will be removed once
    594   //                   their logic is moved into ViewTargeter and its
    595   //                   derived classes. See crbug.com/355425.
    596 
    597   // A convenience function which calls HitTestRect() with a rect of size
    598   // 1x1 and an origin of |point|.
    599   bool HitTestPoint(const gfx::Point& point) const;
    600 
    601   // Tests whether |rect| intersects this view's bounds.
    602   virtual bool HitTestRect(const gfx::Rect& rect) const;
    603 
    604   // Returns true if this view or any of its descendants are permitted to
    605   // be the target of an event.
    606   virtual bool CanProcessEventsWithinSubtree() const;
    607 
    608   // Returns true if the mouse cursor is over |view| and mouse events are
    609   // enabled.
    610   bool IsMouseHovered();
    611 
    612   // This method is invoked when the user clicks on this view.
    613   // The provided event is in the receiver's coordinate system.
    614   //
    615   // Return true if you processed the event and want to receive subsequent
    616   // MouseDraggged and MouseReleased events.  This also stops the event from
    617   // bubbling.  If you return false, the event will bubble through parent
    618   // views.
    619   //
    620   // If you remove yourself from the tree while processing this, event bubbling
    621   // stops as if you returned true, but you will not receive future events.
    622   // The return value is ignored in this case.
    623   //
    624   // Default implementation returns true if a ContextMenuController has been
    625   // set, false otherwise. Override as needed.
    626   //
    627   virtual bool OnMousePressed(const ui::MouseEvent& event);
    628 
    629   // This method is invoked when the user clicked on this control.
    630   // and is still moving the mouse with a button pressed.
    631   // The provided event is in the receiver's coordinate system.
    632   //
    633   // Return true if you processed the event and want to receive
    634   // subsequent MouseDragged and MouseReleased events.
    635   //
    636   // Default implementation returns true if a ContextMenuController has been
    637   // set, false otherwise. Override as needed.
    638   //
    639   virtual bool OnMouseDragged(const ui::MouseEvent& event);
    640 
    641   // This method is invoked when the user releases the mouse
    642   // button. The event is in the receiver's coordinate system.
    643   //
    644   // Default implementation notifies the ContextMenuController is appropriate.
    645   // Subclasses that wish to honor the ContextMenuController should invoke
    646   // super.
    647   virtual void OnMouseReleased(const ui::MouseEvent& event);
    648 
    649   // This method is invoked when the mouse press/drag was canceled by a
    650   // system/user gesture.
    651   virtual void OnMouseCaptureLost();
    652 
    653   // This method is invoked when the mouse is above this control
    654   // The event is in the receiver's coordinate system.
    655   //
    656   // Default implementation does nothing. Override as needed.
    657   virtual void OnMouseMoved(const ui::MouseEvent& event);
    658 
    659   // This method is invoked when the mouse enters this control.
    660   //
    661   // Default implementation does nothing. Override as needed.
    662   virtual void OnMouseEntered(const ui::MouseEvent& event);
    663 
    664   // This method is invoked when the mouse exits this control
    665   // The provided event location is always (0, 0)
    666   // Default implementation does nothing. Override as needed.
    667   virtual void OnMouseExited(const ui::MouseEvent& event);
    668 
    669   // Set the MouseHandler for a drag session.
    670   //
    671   // A drag session is a stream of mouse events starting
    672   // with a MousePressed event, followed by several MouseDragged
    673   // events and finishing with a MouseReleased event.
    674   //
    675   // This method should be only invoked while processing a
    676   // MouseDragged or MousePressed event.
    677   //
    678   // All further mouse dragged and mouse up events will be sent
    679   // the MouseHandler, even if it is reparented to another window.
    680   //
    681   // The MouseHandler is automatically cleared when the control
    682   // comes back from processing the MouseReleased event.
    683   //
    684   // Note: if the mouse handler is no longer connected to a
    685   // view hierarchy, events won't be sent.
    686   //
    687   // TODO(sky): rename this.
    688   virtual void SetMouseHandler(View* new_mouse_handler);
    689 
    690   // Invoked when a key is pressed or released.
    691   // Subclasser should return true if the event has been processed and false
    692   // otherwise. If the event has not been processed, the parent will be given a
    693   // chance.
    694   virtual bool OnKeyPressed(const ui::KeyEvent& event);
    695   virtual bool OnKeyReleased(const ui::KeyEvent& event);
    696 
    697   // Invoked when the user uses the mousewheel. Implementors should return true
    698   // if the event has been processed and false otherwise. This message is sent
    699   // if the view is focused. If the event has not been processed, the parent
    700   // will be given a chance.
    701   virtual bool OnMouseWheel(const ui::MouseWheelEvent& event);
    702 
    703 
    704   // See field for description.
    705   void set_notify_enter_exit_on_child(bool notify) {
    706     notify_enter_exit_on_child_ = notify;
    707   }
    708   bool notify_enter_exit_on_child() const {
    709     return notify_enter_exit_on_child_;
    710   }
    711 
    712   // Returns the View's TextInputClient instance or NULL if the View doesn't
    713   // support text input.
    714   virtual ui::TextInputClient* GetTextInputClient();
    715 
    716   // Convenience method to retrieve the InputMethod associated with the
    717   // Widget that contains this view. Returns NULL if this view is not part of a
    718   // view hierarchy with a Widget.
    719   virtual InputMethod* GetInputMethod();
    720   virtual const InputMethod* GetInputMethod() const;
    721 
    722   // Sets a new event-targeter for the view, and returns the previous
    723   // event-targeter.
    724   scoped_ptr<ui::EventTargeter> SetEventTargeter(
    725       scoped_ptr<ui::EventTargeter> targeter);
    726 
    727   // Overridden from ui::EventTarget:
    728   virtual bool CanAcceptEvent(const ui::Event& event) OVERRIDE;
    729   virtual ui::EventTarget* GetParentTarget() OVERRIDE;
    730   virtual scoped_ptr<ui::EventTargetIterator> GetChildIterator() const OVERRIDE;
    731   virtual ui::EventTargeter* GetEventTargeter() OVERRIDE;
    732   virtual void ConvertEventToTarget(ui::EventTarget* target,
    733                                     ui::LocatedEvent* event) OVERRIDE;
    734 
    735   const ui::EventTargeter* GetEventTargeter() const;
    736 
    737   // Overridden from ui::EventHandler:
    738   virtual void OnKeyEvent(ui::KeyEvent* event) OVERRIDE;
    739   virtual void OnMouseEvent(ui::MouseEvent* event) OVERRIDE;
    740   virtual void OnScrollEvent(ui::ScrollEvent* event) OVERRIDE;
    741   virtual void OnTouchEvent(ui::TouchEvent* event) OVERRIDE FINAL;
    742   virtual void OnGestureEvent(ui::GestureEvent* event) OVERRIDE;
    743 
    744   // Accelerators --------------------------------------------------------------
    745 
    746   // Sets a keyboard accelerator for that view. When the user presses the
    747   // accelerator key combination, the AcceleratorPressed method is invoked.
    748   // Note that you can set multiple accelerators for a view by invoking this
    749   // method several times. Note also that AcceleratorPressed is invoked only
    750   // when CanHandleAccelerators() is true.
    751   virtual void AddAccelerator(const ui::Accelerator& accelerator);
    752 
    753   // Removes the specified accelerator for this view.
    754   virtual void RemoveAccelerator(const ui::Accelerator& accelerator);
    755 
    756   // Removes all the keyboard accelerators for this view.
    757   virtual void ResetAccelerators();
    758 
    759   // Overridden from AcceleratorTarget:
    760   virtual bool AcceleratorPressed(const ui::Accelerator& accelerator) OVERRIDE;
    761 
    762   // Returns whether accelerators are enabled for this view. Accelerators are
    763   // enabled if the containing widget is visible and the view is enabled() and
    764   // IsDrawn()
    765   virtual bool CanHandleAccelerators() const OVERRIDE;
    766 
    767   // Focus ---------------------------------------------------------------------
    768 
    769   // Returns whether this view currently has the focus.
    770   virtual bool HasFocus() const;
    771 
    772   // Returns the view that should be selected next when pressing Tab.
    773   View* GetNextFocusableView();
    774   const View* GetNextFocusableView() const;
    775 
    776   // Returns the view that should be selected next when pressing Shift-Tab.
    777   View* GetPreviousFocusableView();
    778 
    779   // Sets the component that should be selected next when pressing Tab, and
    780   // makes the current view the precedent view of the specified one.
    781   // Note that by default views are linked in the order they have been added to
    782   // their container. Use this method if you want to modify the order.
    783   // IMPORTANT NOTE: loops in the focus hierarchy are not supported.
    784   void SetNextFocusableView(View* view);
    785 
    786   // Sets whether this view is capable of taking focus.
    787   // Note that this is false by default so that a view used as a container does
    788   // not get the focus.
    789   void SetFocusable(bool focusable);
    790 
    791   // Returns true if this view is |focusable_|, |enabled_| and drawn.
    792   virtual bool IsFocusable() const;
    793 
    794   // Return whether this view is focusable when the user requires full keyboard
    795   // access, even though it may not be normally focusable.
    796   bool IsAccessibilityFocusable() const;
    797 
    798   // Set whether this view can be made focusable if the user requires
    799   // full keyboard access, even though it's not normally focusable.
    800   // Note that this is false by default.
    801   void SetAccessibilityFocusable(bool accessibility_focusable);
    802 
    803   // Convenience method to retrieve the FocusManager associated with the
    804   // Widget that contains this view.  This can return NULL if this view is not
    805   // part of a view hierarchy with a Widget.
    806   virtual FocusManager* GetFocusManager();
    807   virtual const FocusManager* GetFocusManager() const;
    808 
    809   // Request keyboard focus. The receiving view will become the focused view.
    810   virtual void RequestFocus();
    811 
    812   // Invoked when a view is about to be requested for focus due to the focus
    813   // traversal. Reverse is this request was generated going backward
    814   // (Shift-Tab).
    815   virtual void AboutToRequestFocusFromTabTraversal(bool reverse) {}
    816 
    817   // Invoked when a key is pressed before the key event is processed (and
    818   // potentially eaten) by the focus manager for tab traversal, accelerators and
    819   // other focus related actions.
    820   // The default implementation returns false, ensuring that tab traversal and
    821   // accelerators processing is performed.
    822   // Subclasses should return true if they want to process the key event and not
    823   // have it processed as an accelerator (if any) or as a tab traversal (if the
    824   // key event is for the TAB key).  In that case, OnKeyPressed will
    825   // subsequently be invoked for that event.
    826   virtual bool SkipDefaultKeyEventProcessing(const ui::KeyEvent& event);
    827 
    828   // Subclasses that contain traversable children that are not directly
    829   // accessible through the children hierarchy should return the associated
    830   // FocusTraversable for the focus traversal to work properly.
    831   virtual FocusTraversable* GetFocusTraversable();
    832 
    833   // Subclasses that can act as a "pane" must implement their own
    834   // FocusTraversable to keep the focus trapped within the pane.
    835   // If this method returns an object, any view that's a direct or
    836   // indirect child of this view will always use this FocusTraversable
    837   // rather than the one from the widget.
    838   virtual FocusTraversable* GetPaneFocusTraversable();
    839 
    840   // Tooltips ------------------------------------------------------------------
    841 
    842   // Gets the tooltip for this View. If the View does not have a tooltip,
    843   // return false. If the View does have a tooltip, copy the tooltip into
    844   // the supplied string and return true.
    845   // Any time the tooltip text that a View is displaying changes, it must
    846   // invoke TooltipTextChanged.
    847   // |p| provides the coordinates of the mouse (relative to this view).
    848   virtual bool GetTooltipText(const gfx::Point& p,
    849                               base::string16* tooltip) const;
    850 
    851   // Returns the location (relative to this View) for the text on the tooltip
    852   // to display. If false is returned (the default), the tooltip is placed at
    853   // a default position.
    854   virtual bool GetTooltipTextOrigin(const gfx::Point& p, gfx::Point* loc) const;
    855 
    856   // Context menus -------------------------------------------------------------
    857 
    858   // Sets the ContextMenuController. Setting this to non-null makes the View
    859   // process mouse events.
    860   ContextMenuController* context_menu_controller() {
    861     return context_menu_controller_;
    862   }
    863   void set_context_menu_controller(ContextMenuController* menu_controller) {
    864     context_menu_controller_ = menu_controller;
    865   }
    866 
    867   // Provides default implementation for context menu handling. The default
    868   // implementation calls the ShowContextMenu of the current
    869   // ContextMenuController (if it is not NULL). Overridden in subclassed views
    870   // to provide right-click menu display triggerd by the keyboard (i.e. for the
    871   // Chrome toolbar Back and Forward buttons). No source needs to be specified,
    872   // as it is always equal to the current View.
    873   virtual void ShowContextMenu(const gfx::Point& p,
    874                                ui::MenuSourceType source_type);
    875 
    876   // On some platforms, we show context menu on mouse press instead of release.
    877   // This method returns true for those platforms.
    878   static bool ShouldShowContextMenuOnMousePress();
    879 
    880   // Drag and drop -------------------------------------------------------------
    881 
    882   DragController* drag_controller() { return drag_controller_; }
    883   void set_drag_controller(DragController* drag_controller) {
    884     drag_controller_ = drag_controller;
    885   }
    886 
    887   // During a drag and drop session when the mouse moves the view under the
    888   // mouse is queried for the drop types it supports by way of the
    889   // GetDropFormats methods. If the view returns true and the drag site can
    890   // provide data in one of the formats, the view is asked if the drop data
    891   // is required before any other drop events are sent. Once the
    892   // data is available the view is asked if it supports the drop (by way of
    893   // the CanDrop method). If a view returns true from CanDrop,
    894   // OnDragEntered is sent to the view when the mouse first enters the view,
    895   // as the mouse moves around within the view OnDragUpdated is invoked.
    896   // If the user releases the mouse over the view and OnDragUpdated returns a
    897   // valid drop, then OnPerformDrop is invoked. If the mouse moves outside the
    898   // view or over another view that wants the drag, OnDragExited is invoked.
    899   //
    900   // Similar to mouse events, the deepest view under the mouse is first checked
    901   // if it supports the drop (Drop). If the deepest view under
    902   // the mouse does not support the drop, the ancestors are walked until one
    903   // is found that supports the drop.
    904 
    905   // Override and return the set of formats that can be dropped on this view.
    906   // |formats| is a bitmask of the formats defined bye OSExchangeData::Format.
    907   // The default implementation returns false, which means the view doesn't
    908   // support dropping.
    909   virtual bool GetDropFormats(
    910       int* formats,
    911       std::set<OSExchangeData::CustomFormat>* custom_formats);
    912 
    913   // Override and return true if the data must be available before any drop
    914   // methods should be invoked. The default is false.
    915   virtual bool AreDropTypesRequired();
    916 
    917   // A view that supports drag and drop must override this and return true if
    918   // data contains a type that may be dropped on this view.
    919   virtual bool CanDrop(const OSExchangeData& data);
    920 
    921   // OnDragEntered is invoked when the mouse enters this view during a drag and
    922   // drop session and CanDrop returns true. This is immediately
    923   // followed by an invocation of OnDragUpdated, and eventually one of
    924   // OnDragExited or OnPerformDrop.
    925   virtual void OnDragEntered(const ui::DropTargetEvent& event);
    926 
    927   // Invoked during a drag and drop session while the mouse is over the view.
    928   // This should return a bitmask of the DragDropTypes::DragOperation supported
    929   // based on the location of the event. Return 0 to indicate the drop should
    930   // not be accepted.
    931   virtual int OnDragUpdated(const ui::DropTargetEvent& event);
    932 
    933   // Invoked during a drag and drop session when the mouse exits the views, or
    934   // when the drag session was canceled and the mouse was over the view.
    935   virtual void OnDragExited();
    936 
    937   // Invoked during a drag and drop session when OnDragUpdated returns a valid
    938   // operation and the user release the mouse.
    939   virtual int OnPerformDrop(const ui::DropTargetEvent& event);
    940 
    941   // Invoked from DoDrag after the drag completes. This implementation does
    942   // nothing, and is intended for subclasses to do cleanup.
    943   virtual void OnDragDone();
    944 
    945   // Returns true if the mouse was dragged enough to start a drag operation.
    946   // delta_x and y are the distance the mouse was dragged.
    947   static bool ExceededDragThreshold(const gfx::Vector2d& delta);
    948 
    949   // Accessibility -------------------------------------------------------------
    950 
    951   // Modifies |state| to reflect the current accessible state of this view.
    952   virtual void GetAccessibleState(ui::AXViewState* state) { }
    953 
    954   // Returns an instance of the native accessibility interface for this view.
    955   virtual gfx::NativeViewAccessible GetNativeViewAccessible();
    956 
    957   // Notifies assistive technology that an accessibility event has
    958   // occurred on this view, such as when the view is focused or when its
    959   // value changes. Pass true for |send_native_event| except for rare
    960   // cases where the view is a native control that's already sending a
    961   // native accessibility event and the duplicate event would cause
    962   // problems.
    963   void NotifyAccessibilityEvent(ui::AXEvent event_type,
    964                                 bool send_native_event);
    965 
    966   // Scrolling -----------------------------------------------------------------
    967   // TODO(beng): Figure out if this can live somewhere other than View, i.e.
    968   //             closer to ScrollView.
    969 
    970   // Scrolls the specified region, in this View's coordinate system, to be
    971   // visible. View's implementation passes the call onto the parent View (after
    972   // adjusting the coordinates). It is up to views that only show a portion of
    973   // the child view, such as Viewport, to override appropriately.
    974   virtual void ScrollRectToVisible(const gfx::Rect& rect);
    975 
    976   // The following methods are used by ScrollView to determine the amount
    977   // to scroll relative to the visible bounds of the view. For example, a
    978   // return value of 10 indicates the scrollview should scroll 10 pixels in
    979   // the appropriate direction.
    980   //
    981   // Each method takes the following parameters:
    982   //
    983   // is_horizontal: if true, scrolling is along the horizontal axis, otherwise
    984   //                the vertical axis.
    985   // is_positive: if true, scrolling is by a positive amount. Along the
    986   //              vertical axis scrolling by a positive amount equates to
    987   //              scrolling down.
    988   //
    989   // The return value should always be positive and gives the number of pixels
    990   // to scroll. ScrollView interprets a return value of 0 (or negative)
    991   // to scroll by a default amount.
    992   //
    993   // See VariableRowHeightScrollHelper and FixedRowHeightScrollHelper for
    994   // implementations of common cases.
    995   virtual int GetPageScrollIncrement(ScrollView* scroll_view,
    996                                      bool is_horizontal, bool is_positive);
    997   virtual int GetLineScrollIncrement(ScrollView* scroll_view,
    998                                      bool is_horizontal, bool is_positive);
    999 
   1000  protected:
   1001   // Used to track a drag. RootView passes this into
   1002   // ProcessMousePressed/Dragged.
   1003   struct DragInfo {
   1004     // Sets possible_drag to false and start_x/y to 0. This is invoked by
   1005     // RootView prior to invoke ProcessMousePressed.
   1006     void Reset();
   1007 
   1008     // Sets possible_drag to true and start_pt to the specified point.
   1009     // This is invoked by the target view if it detects the press may generate
   1010     // a drag.
   1011     void PossibleDrag(const gfx::Point& p);
   1012 
   1013     // Whether the press may generate a drag.
   1014     bool possible_drag;
   1015 
   1016     // Coordinates of the mouse press.
   1017     gfx::Point start_pt;
   1018   };
   1019 
   1020   // Size and disposition ------------------------------------------------------
   1021 
   1022   // Override to be notified when the bounds of the view have changed.
   1023   virtual void OnBoundsChanged(const gfx::Rect& previous_bounds);
   1024 
   1025   // Called when the preferred size of a child view changed.  This gives the
   1026   // parent an opportunity to do a fresh layout if that makes sense.
   1027   virtual void ChildPreferredSizeChanged(View* child) {}
   1028 
   1029   // Called when the visibility of a child view changed.  This gives the parent
   1030   // an opportunity to do a fresh layout if that makes sense.
   1031   virtual void ChildVisibilityChanged(View* child) {}
   1032 
   1033   // Invalidates the layout and calls ChildPreferredSizeChanged on the parent
   1034   // if there is one. Be sure to call View::PreferredSizeChanged when
   1035   // overriding such that the layout is properly invalidated.
   1036   virtual void PreferredSizeChanged();
   1037 
   1038   // Override returning true when the view needs to be notified when its visible
   1039   // bounds relative to the root view may have changed. Only used by
   1040   // NativeViewHost.
   1041   virtual bool NeedsNotificationWhenVisibleBoundsChange() const;
   1042 
   1043   // Notification that this View's visible bounds relative to the root view may
   1044   // have changed. The visible bounds are the region of the View not clipped by
   1045   // its ancestors. This is used for clipping NativeViewHost.
   1046   virtual void OnVisibleBoundsChanged();
   1047 
   1048   // Override to be notified when the enabled state of this View has
   1049   // changed. The default implementation calls SchedulePaint() on this View.
   1050   virtual void OnEnabledChanged();
   1051 
   1052   bool needs_layout() const { return needs_layout_; }
   1053 
   1054   // Tree operations -----------------------------------------------------------
   1055 
   1056   // This method is invoked when the tree changes.
   1057   //
   1058   // When a view is removed, it is invoked for all children and grand
   1059   // children. For each of these views, a notification is sent to the
   1060   // view and all parents.
   1061   //
   1062   // When a view is added, a notification is sent to the view, all its
   1063   // parents, and all its children (and grand children)
   1064   //
   1065   // Default implementation does nothing. Override to perform operations
   1066   // required when a view is added or removed from a view hierarchy
   1067   //
   1068   // Refer to comments in struct |ViewHierarchyChangedDetails| for |details|.
   1069   virtual void ViewHierarchyChanged(const ViewHierarchyChangedDetails& details);
   1070 
   1071   // When SetVisible() changes the visibility of a view, this method is
   1072   // invoked for that view as well as all the children recursively.
   1073   virtual void VisibilityChanged(View* starting_from, bool is_visible);
   1074 
   1075   // This method is invoked when the parent NativeView of the widget that the
   1076   // view is attached to has changed and the view hierarchy has not changed.
   1077   // ViewHierarchyChanged() is called when the parent NativeView of the widget
   1078   // that the view is attached to is changed as a result of changing the view
   1079   // hierarchy. Overriding this method is useful for tracking which
   1080   // FocusManager manages this view.
   1081   virtual void NativeViewHierarchyChanged();
   1082 
   1083   // Painting ------------------------------------------------------------------
   1084 
   1085   // Responsible for calling Paint() on child Views. Override to control the
   1086   // order child Views are painted.
   1087   virtual void PaintChildren(gfx::Canvas* canvas, const CullSet& cull_set);
   1088 
   1089   // Override to provide rendering in any part of the View's bounds. Typically
   1090   // this is the "contents" of the view. If you override this method you will
   1091   // have to call the subsequent OnPaint*() methods manually.
   1092   virtual void OnPaint(gfx::Canvas* canvas);
   1093 
   1094   // Override to paint a background before any content is drawn. Typically this
   1095   // is done if you are satisfied with a default OnPaint handler but wish to
   1096   // supply a different background.
   1097   virtual void OnPaintBackground(gfx::Canvas* canvas);
   1098 
   1099   // Override to paint a border not specified by SetBorder().
   1100   virtual void OnPaintBorder(gfx::Canvas* canvas);
   1101 
   1102   // Returns true if this View is the root for paint events, and should
   1103   // therefore maintain a |bounds_tree_| member and use it for paint damage rect
   1104   // calculations.
   1105   virtual bool IsPaintRoot();
   1106 
   1107   // Accelerated painting ------------------------------------------------------
   1108 
   1109   // Returns the offset from this view to the nearest ancestor with a layer. If
   1110   // |layer_parent| is non-NULL it is set to the nearest ancestor with a layer.
   1111   virtual gfx::Vector2d CalculateOffsetToAncestorWithLayer(
   1112       ui::Layer** layer_parent);
   1113 
   1114   // Updates the view's layer's parent. Called when a view is added to a view
   1115   // hierarchy, responsible for parenting the view's layer to the enclosing
   1116   // layer in the hierarchy.
   1117   virtual void UpdateParentLayer();
   1118 
   1119   // If this view has a layer, the layer is reparented to |parent_layer| and its
   1120   // bounds is set based on |point|. If this view does not have a layer, then
   1121   // recurses through all children. This is used when adding a layer to an
   1122   // existing view to make sure all descendants that have layers are parented to
   1123   // the right layer.
   1124   void MoveLayerToParent(ui::Layer* parent_layer, const gfx::Point& point);
   1125 
   1126   // Called to update the bounds of any child layers within this View's
   1127   // hierarchy when something happens to the hierarchy.
   1128   void UpdateChildLayerBounds(const gfx::Vector2d& offset);
   1129 
   1130   // Overridden from ui::LayerDelegate:
   1131   virtual void OnPaintLayer(gfx::Canvas* canvas) OVERRIDE;
   1132   virtual void OnDeviceScaleFactorChanged(float device_scale_factor) OVERRIDE;
   1133   virtual base::Closure PrepareForLayerBoundsChange() OVERRIDE;
   1134 
   1135   // Finds the layer that this view paints to (it may belong to an ancestor
   1136   // view), then reorders the immediate children of that layer to match the
   1137   // order of the view tree.
   1138   virtual void ReorderLayers();
   1139 
   1140   // This reorders the immediate children of |*parent_layer| to match the
   1141   // order of the view tree. Child layers which are owned by a view are
   1142   // reordered so that they are below any child layers not owned by a view.
   1143   // Widget::ReorderNativeViews() should be called to reorder any child layers
   1144   // with an associated view. Widget::ReorderNativeViews() may reorder layers
   1145   // below layers owned by a view.
   1146   virtual void ReorderChildLayers(ui::Layer* parent_layer);
   1147 
   1148   // Input ---------------------------------------------------------------------
   1149 
   1150   // Called by HitTestRect() to see if this View has a custom hit test mask. If
   1151   // the return value is true, GetHitTestMask() will be called to obtain the
   1152   // mask. Default value is false, in which case the View will hit-test against
   1153   // its bounds.
   1154   virtual bool HasHitTestMask() const;
   1155 
   1156   // Called by HitTestRect() to retrieve a mask for hit-testing against.
   1157   // Subclasses override to provide custom shaped hit test regions.
   1158   virtual void GetHitTestMask(HitTestSource source, gfx::Path* mask) const;
   1159 
   1160   virtual DragInfo* GetDragInfo();
   1161 
   1162   // Focus ---------------------------------------------------------------------
   1163 
   1164   // Returns last value passed to SetFocusable(). Use IsFocusable() to determine
   1165   // if a view can take focus right now.
   1166   bool focusable() const { return focusable_; }
   1167 
   1168   // Override to be notified when focus has changed either to or from this View.
   1169   virtual void OnFocus();
   1170   virtual void OnBlur();
   1171 
   1172   // Handle view focus/blur events for this view.
   1173   void Focus();
   1174   void Blur();
   1175 
   1176   // System events -------------------------------------------------------------
   1177 
   1178   // Called when the UI theme (not the NativeTheme) has changed, overriding
   1179   // allows individual Views to do special cleanup and processing (such as
   1180   // dropping resource caches).  To dispatch a theme changed notification, call
   1181   // Widget::ThemeChanged().
   1182   virtual void OnThemeChanged() {}
   1183 
   1184   // Called when the locale has changed, overriding allows individual Views to
   1185   // update locale-dependent strings.
   1186   // To dispatch a locale changed notification, call Widget::LocaleChanged().
   1187   virtual void OnLocaleChanged() {}
   1188 
   1189   // Tooltips ------------------------------------------------------------------
   1190 
   1191   // Views must invoke this when the tooltip text they are to display changes.
   1192   void TooltipTextChanged();
   1193 
   1194   // Context menus -------------------------------------------------------------
   1195 
   1196   // Returns the location, in screen coordinates, to show the context menu at
   1197   // when the context menu is shown from the keyboard. This implementation
   1198   // returns the middle of the visible region of this view.
   1199   //
   1200   // This method is invoked when the context menu is shown by way of the
   1201   // keyboard.
   1202   virtual gfx::Point GetKeyboardContextMenuLocation();
   1203 
   1204   // Drag and drop -------------------------------------------------------------
   1205 
   1206   // These are cover methods that invoke the method of the same name on
   1207   // the DragController. Subclasses may wish to override rather than install
   1208   // a DragController.
   1209   // See DragController for a description of these methods.
   1210   virtual int GetDragOperations(const gfx::Point& press_pt);
   1211   virtual void WriteDragData(const gfx::Point& press_pt, OSExchangeData* data);
   1212 
   1213   // Returns whether we're in the middle of a drag session that was initiated
   1214   // by us.
   1215   bool InDrag();
   1216 
   1217   // Returns how much the mouse needs to move in one direction to start a
   1218   // drag. These methods cache in a platform-appropriate way. These values are
   1219   // used by the public static method ExceededDragThreshold().
   1220   static int GetHorizontalDragThreshold();
   1221   static int GetVerticalDragThreshold();
   1222 
   1223   // NativeTheme ---------------------------------------------------------------
   1224 
   1225   // Invoked when the NativeTheme associated with this View changes.
   1226   virtual void OnNativeThemeChanged(const ui::NativeTheme* theme) {}
   1227 
   1228   // Debugging -----------------------------------------------------------------
   1229 
   1230 #if !defined(NDEBUG)
   1231   // Returns string containing a graph of the views hierarchy in graphViz DOT
   1232   // language (http://graphviz.org/). Can be called within debugger and save
   1233   // to a file to compile/view.
   1234   // Note: Assumes initial call made with first = true.
   1235   virtual std::string PrintViewGraph(bool first);
   1236 
   1237   // Some classes may own an object which contains the children to displayed in
   1238   // the views hierarchy. The above function gives the class the flexibility to
   1239   // decide which object should be used to obtain the children, but this
   1240   // function makes the decision explicit.
   1241   std::string DoPrintViewGraph(bool first, View* view_with_children);
   1242 #endif
   1243 
   1244  private:
   1245   friend class internal::PreEventDispatchHandler;
   1246   friend class internal::PostEventDispatchHandler;
   1247   friend class internal::RootView;
   1248   friend class FocusManager;
   1249   friend class Widget;
   1250 
   1251   typedef gfx::RTree<intptr_t> BoundsTree;
   1252 
   1253   // Painting  -----------------------------------------------------------------
   1254 
   1255   enum SchedulePaintType {
   1256     // Indicates the size is the same (only the origin changed).
   1257     SCHEDULE_PAINT_SIZE_SAME,
   1258 
   1259     // Indicates the size changed (and possibly the origin).
   1260     SCHEDULE_PAINT_SIZE_CHANGED
   1261   };
   1262 
   1263   // Invoked before and after the bounds change to schedule painting the old and
   1264   // new bounds.
   1265   void SchedulePaintBoundsChanged(SchedulePaintType type);
   1266 
   1267   // Common Paint() code shared by accelerated and non-accelerated code paths to
   1268   // invoke OnPaint() on the View.
   1269   void PaintCommon(gfx::Canvas* canvas, const CullSet& cull_set);
   1270 
   1271   // Tree operations -----------------------------------------------------------
   1272 
   1273   // Removes |view| from the hierarchy tree.  If |update_focus_cycle| is true,
   1274   // the next and previous focusable views of views pointing to this view are
   1275   // updated.  If |update_tool_tip| is true, the tooltip is updated.  If
   1276   // |delete_removed_view| is true, the view is also deleted (if it is parent
   1277   // owned).  If |new_parent| is not NULL, the remove is the result of
   1278   // AddChildView() to a new parent.  For this case, |new_parent| is the View
   1279   // that |view| is going to be added to after the remove completes.
   1280   void DoRemoveChildView(View* view,
   1281                          bool update_focus_cycle,
   1282                          bool update_tool_tip,
   1283                          bool delete_removed_view,
   1284                          View* new_parent);
   1285 
   1286   // Call ViewHierarchyChanged() for all child views and all parents.
   1287   // |old_parent| is the original parent of the View that was removed.
   1288   // If |new_parent| is not NULL, the View that was removed will be reparented
   1289   // to |new_parent| after the remove operation.
   1290   void PropagateRemoveNotifications(View* old_parent, View* new_parent);
   1291 
   1292   // Call ViewHierarchyChanged() for all children.
   1293   void PropagateAddNotifications(const ViewHierarchyChangedDetails& details);
   1294 
   1295   // Propagates NativeViewHierarchyChanged() notification through all the
   1296   // children.
   1297   void PropagateNativeViewHierarchyChanged();
   1298 
   1299   // Takes care of registering/unregistering accelerators if
   1300   // |register_accelerators| true and calls ViewHierarchyChanged().
   1301   void ViewHierarchyChangedImpl(bool register_accelerators,
   1302                                 const ViewHierarchyChangedDetails& details);
   1303 
   1304   // Invokes OnNativeThemeChanged() on this and all descendants.
   1305   void PropagateNativeThemeChanged(const ui::NativeTheme* theme);
   1306 
   1307   // Size and disposition ------------------------------------------------------
   1308 
   1309   // Call VisibilityChanged() recursively for all children.
   1310   void PropagateVisibilityNotifications(View* from, bool is_visible);
   1311 
   1312   // Registers/unregisters accelerators as necessary and calls
   1313   // VisibilityChanged().
   1314   void VisibilityChangedImpl(View* starting_from, bool is_visible);
   1315 
   1316   // Responsible for propagating bounds change notifications to relevant
   1317   // views.
   1318   void BoundsChanged(const gfx::Rect& previous_bounds);
   1319 
   1320   // Visible bounds notification registration.
   1321   // When a view is added to a hierarchy, it and all its children are asked if
   1322   // they need to be registered for "visible bounds within root" notifications
   1323   // (see comment on OnVisibleBoundsChanged()). If they do, they are registered
   1324   // with every ancestor between them and the root of the hierarchy.
   1325   static void RegisterChildrenForVisibleBoundsNotification(View* view);
   1326   static void UnregisterChildrenForVisibleBoundsNotification(View* view);
   1327   void RegisterForVisibleBoundsNotification();
   1328   void UnregisterForVisibleBoundsNotification();
   1329 
   1330   // Adds/removes view to the list of descendants that are notified any time
   1331   // this views location and possibly size are changed.
   1332   void AddDescendantToNotify(View* view);
   1333   void RemoveDescendantToNotify(View* view);
   1334 
   1335   // Sets the layer's bounds given in DIP coordinates.
   1336   void SetLayerBounds(const gfx::Rect& bounds_in_dip);
   1337 
   1338   // Sets the bit indicating that the cached bounds for this object within the
   1339   // root view bounds tree are no longer valid. If |origin_changed| is true sets
   1340   // the same bit for all of our children as well.
   1341   void SetRootBoundsDirty(bool origin_changed);
   1342 
   1343   // If needed, updates the bounds rectangle in paint root coordinate space
   1344   // in the supplied RTree. Recurses to children for recomputation as well.
   1345   void UpdateRootBounds(BoundsTree* bounds_tree, const gfx::Vector2d& offset);
   1346 
   1347   // Remove self and all children from the supplied bounds tree. This is used,
   1348   // for example, when a view gets a layer and therefore becomes paint root. It
   1349   // needs to remove all references to itself and its children from any previous
   1350   // paint root that may have been tracking it.
   1351   void RemoveRootBounds(BoundsTree* bounds_tree);
   1352 
   1353   // Traverse up the View hierarchy to the first ancestor that is a paint root
   1354   // and return a pointer to its |bounds_tree_| or NULL if no tree is found.
   1355   BoundsTree* GetBoundsTreeFromPaintRoot();
   1356 
   1357   // Transformations -----------------------------------------------------------
   1358 
   1359   // Returns in |transform| the transform to get from coordinates of |ancestor|
   1360   // to this. Returns true if |ancestor| is found. If |ancestor| is not found,
   1361   // or NULL, |transform| is set to convert from root view coordinates to this.
   1362   bool GetTransformRelativeTo(const View* ancestor,
   1363                               gfx::Transform* transform) const;
   1364 
   1365   // Coordinate conversion -----------------------------------------------------
   1366 
   1367   // Convert a point in the view's coordinate to an ancestor view's coordinate
   1368   // system using necessary transformations. Returns whether the point was
   1369   // successfully converted to the ancestor's coordinate system.
   1370   bool ConvertPointForAncestor(const View* ancestor, gfx::Point* point) const;
   1371 
   1372   // Convert a point in the ancestor's coordinate system to the view's
   1373   // coordinate system using necessary transformations. Returns whether the
   1374   // point was successfully converted from the ancestor's coordinate system
   1375   // to the view's coordinate system.
   1376   bool ConvertPointFromAncestor(const View* ancestor, gfx::Point* point) const;
   1377 
   1378   // Convert a rect in the view's coordinate to an ancestor view's coordinate
   1379   // system using necessary transformations. Returns whether the rect was
   1380   // successfully converted to the ancestor's coordinate system.
   1381   bool ConvertRectForAncestor(const View* ancestor, gfx::RectF* rect) const;
   1382 
   1383   // Convert a rect in the ancestor's coordinate system to the view's
   1384   // coordinate system using necessary transformations. Returns whether the
   1385   // rect was successfully converted from the ancestor's coordinate system
   1386   // to the view's coordinate system.
   1387   bool ConvertRectFromAncestor(const View* ancestor, gfx::RectF* rect) const;
   1388 
   1389   // Accelerated painting ------------------------------------------------------
   1390 
   1391   // Creates the layer and related fields for this view.
   1392   void CreateLayer();
   1393 
   1394   // Parents all un-parented layers within this view's hierarchy to this view's
   1395   // layer.
   1396   void UpdateParentLayers();
   1397 
   1398   // Parents this view's layer to |parent_layer|, and sets its bounds and other
   1399   // properties in accordance to |offset|, the view's offset from the
   1400   // |parent_layer|.
   1401   void ReparentLayer(const gfx::Vector2d& offset, ui::Layer* parent_layer);
   1402 
   1403   // Called to update the layer visibility. The layer will be visible if the
   1404   // View itself, and all its parent Views are visible. This also updates
   1405   // visibility of the child layers.
   1406   void UpdateLayerVisibility();
   1407   void UpdateChildLayerVisibility(bool visible);
   1408 
   1409   // Orphans the layers in this subtree that are parented to layers outside of
   1410   // this subtree.
   1411   void OrphanLayers();
   1412 
   1413   // Destroys the layer associated with this view, and reparents any descendants
   1414   // to the destroyed layer's parent.
   1415   void DestroyLayer();
   1416 
   1417   // Input ---------------------------------------------------------------------
   1418 
   1419   bool ProcessMousePressed(const ui::MouseEvent& event);
   1420   bool ProcessMouseDragged(const ui::MouseEvent& event);
   1421   void ProcessMouseReleased(const ui::MouseEvent& event);
   1422 
   1423   // Accelerators --------------------------------------------------------------
   1424 
   1425   // Registers this view's keyboard accelerators that are not registered to
   1426   // FocusManager yet, if possible.
   1427   void RegisterPendingAccelerators();
   1428 
   1429   // Unregisters all the keyboard accelerators associated with this view.
   1430   // |leave_data_intact| if true does not remove data from accelerators_ array,
   1431   // so it could be re-registered with other focus manager
   1432   void UnregisterAccelerators(bool leave_data_intact);
   1433 
   1434   // Focus ---------------------------------------------------------------------
   1435 
   1436   // Initialize the previous/next focusable views of the specified view relative
   1437   // to the view at the specified index.
   1438   void InitFocusSiblings(View* view, int index);
   1439 
   1440   // System events -------------------------------------------------------------
   1441 
   1442   // Used to propagate theme changed notifications from the root view to all
   1443   // views in the hierarchy.
   1444   virtual void PropagateThemeChanged();
   1445 
   1446   // Used to propagate locale changed notifications from the root view to all
   1447   // views in the hierarchy.
   1448   virtual void PropagateLocaleChanged();
   1449 
   1450   // Tooltips ------------------------------------------------------------------
   1451 
   1452   // Propagates UpdateTooltip() to the TooltipManager for the Widget.
   1453   // This must be invoked any time the View hierarchy changes in such a way
   1454   // the view under the mouse differs. For example, if the bounds of a View is
   1455   // changed, this is invoked. Similarly, as Views are added/removed, this
   1456   // is invoked.
   1457   void UpdateTooltip();
   1458 
   1459   // Drag and drop -------------------------------------------------------------
   1460 
   1461   // Starts a drag and drop operation originating from this view. This invokes
   1462   // WriteDragData to write the data and GetDragOperations to determine the
   1463   // supported drag operations. When done, OnDragDone is invoked. |press_pt| is
   1464   // in the view's coordinate system.
   1465   // Returns true if a drag was started.
   1466   bool DoDrag(const ui::LocatedEvent& event,
   1467               const gfx::Point& press_pt,
   1468               ui::DragDropTypes::DragEventSource source);
   1469 
   1470   //////////////////////////////////////////////////////////////////////////////
   1471 
   1472   // Creation and lifetime -----------------------------------------------------
   1473 
   1474   // False if this View is owned by its parent - i.e. it will be deleted by its
   1475   // parent during its parents destruction. False is the default.
   1476   bool owned_by_client_;
   1477 
   1478   // Attributes ----------------------------------------------------------------
   1479 
   1480   // The id of this View. Used to find this View.
   1481   int id_;
   1482 
   1483   // The group of this view. Some view subclasses use this id to find other
   1484   // views of the same group. For example radio button uses this information
   1485   // to find other radio buttons.
   1486   int group_;
   1487 
   1488   // Tree operations -----------------------------------------------------------
   1489 
   1490   // This view's parent.
   1491   View* parent_;
   1492 
   1493   // This view's children.
   1494   Views children_;
   1495 
   1496   // Size and disposition ------------------------------------------------------
   1497 
   1498   // This View's bounds in the parent coordinate system.
   1499   gfx::Rect bounds_;
   1500 
   1501   // Whether this view is visible.
   1502   bool visible_;
   1503 
   1504   // Whether this view is enabled.
   1505   bool enabled_;
   1506 
   1507   // When this flag is on, a View receives a mouse-enter and mouse-leave event
   1508   // even if a descendant View is the event-recipient for the real mouse
   1509   // events. When this flag is turned on, and mouse moves from outside of the
   1510   // view into a child view, both the child view and this view receives
   1511   // mouse-enter event. Similarly, if the mouse moves from inside a child view
   1512   // and out of this view, then both views receive a mouse-leave event.
   1513   // When this flag is turned off, if the mouse moves from inside this view into
   1514   // a child view, then this view receives a mouse-leave event. When this flag
   1515   // is turned on, it does not receive the mouse-leave event in this case.
   1516   // When the mouse moves from inside the child view out of the child view but
   1517   // still into this view, this view receives a mouse-enter event if this flag
   1518   // is turned off, but doesn't if this flag is turned on.
   1519   // This flag is initialized to false.
   1520   bool notify_enter_exit_on_child_;
   1521 
   1522   // Whether or not RegisterViewForVisibleBoundsNotification on the RootView
   1523   // has been invoked.
   1524   bool registered_for_visible_bounds_notification_;
   1525 
   1526   // List of descendants wanting notification when their visible bounds change.
   1527   scoped_ptr<Views> descendants_to_notify_;
   1528 
   1529   // True if the bounds on this object have changed since the last time the
   1530   // paint root view constructed the spatial database.
   1531   bool root_bounds_dirty_;
   1532 
   1533   // If this View IsPaintRoot() then this will be a pointer to a spatial data
   1534   // structure where we will keep the bounding boxes of all our children, for
   1535   // efficient paint damage rectangle intersection.
   1536   scoped_ptr<BoundsTree> bounds_tree_;
   1537 
   1538   // Transformations -----------------------------------------------------------
   1539 
   1540   // Clipping parameters. skia transformation matrix does not give us clipping.
   1541   // So we do it ourselves.
   1542   gfx::Insets clip_insets_;
   1543 
   1544   // Layout --------------------------------------------------------------------
   1545 
   1546   // Whether the view needs to be laid out.
   1547   bool needs_layout_;
   1548 
   1549   // The View's LayoutManager defines the sizing heuristics applied to child
   1550   // Views. The default is absolute positioning according to bounds_.
   1551   scoped_ptr<LayoutManager> layout_manager_;
   1552 
   1553   // Painting ------------------------------------------------------------------
   1554 
   1555   // Background
   1556   scoped_ptr<Background> background_;
   1557 
   1558   // Border.
   1559   scoped_ptr<Border> border_;
   1560 
   1561   // RTL painting --------------------------------------------------------------
   1562 
   1563   // Indicates whether or not the gfx::Canvas object passed to View::Paint()
   1564   // is going to be flipped horizontally (using the appropriate transform) on
   1565   // right-to-left locales for this View.
   1566   bool flip_canvas_on_paint_for_rtl_ui_;
   1567 
   1568   // Accelerated painting ------------------------------------------------------
   1569 
   1570   bool paint_to_layer_;
   1571 
   1572   // Accelerators --------------------------------------------------------------
   1573 
   1574   // Focus manager accelerators registered on.
   1575   FocusManager* accelerator_focus_manager_;
   1576 
   1577   // The list of accelerators. List elements in the range
   1578   // [0, registered_accelerator_count_) are already registered to FocusManager,
   1579   // and the rest are not yet.
   1580   scoped_ptr<std::vector<ui::Accelerator> > accelerators_;
   1581   size_t registered_accelerator_count_;
   1582 
   1583   // Focus ---------------------------------------------------------------------
   1584 
   1585   // Next view to be focused when the Tab key is pressed.
   1586   View* next_focusable_view_;
   1587 
   1588   // Next view to be focused when the Shift-Tab key combination is pressed.
   1589   View* previous_focusable_view_;
   1590 
   1591   // Whether this view can be focused.
   1592   bool focusable_;
   1593 
   1594   // Whether this view is focusable if the user requires full keyboard access,
   1595   // even though it may not be normally focusable.
   1596   bool accessibility_focusable_;
   1597 
   1598   // Context menus -------------------------------------------------------------
   1599 
   1600   // The menu controller.
   1601   ContextMenuController* context_menu_controller_;
   1602 
   1603   // Drag and drop -------------------------------------------------------------
   1604 
   1605   DragController* drag_controller_;
   1606 
   1607   // Input  --------------------------------------------------------------------
   1608 
   1609   scoped_ptr<ui::EventTargeter> targeter_;
   1610 
   1611   // Accessibility -------------------------------------------------------------
   1612 
   1613   // Belongs to this view, but it's reference-counted on some platforms
   1614   // so we can't use a scoped_ptr. It's dereferenced in the destructor.
   1615   NativeViewAccessibility* native_view_accessibility_;
   1616 
   1617   DISALLOW_COPY_AND_ASSIGN(View);
   1618 };
   1619 
   1620 }  // namespace views
   1621 
   1622 #endif  // UI_VIEWS_VIEW_H_
   1623