V2

ui/views/view.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef UI_VIEWS_VIEW_H_
+#define UI_VIEWS_VIEW_H_
+
+#include <vector>
+
+#include "base/logging.h"
+#include "base/scoped_ptr.h"
+#include "gfx/rect.h"
+#include "ui/views/events/event.h"
+
+namespace gfx {
+class Canvas;
+class Point;
+class Rect;
+class Size;
+}
+
+namespace ui {
+namespace internal {
+class RootView;
+class ViewLayer;

[sky, 2011/02/01 18:56:22]

Nuke ViewLayer.

+}
+class Accelerator;
+class Border;
+class ContextMenuController;
+class DragController;
+class FocusManager;
+class FocusTraversable;
+class LayoutManager;
+class ThemeProvider;
+class Widget;
+
+////////////////////////////////////////////////////////////////////////////////
+// View class
+//
+//  View encapsulates rendering, layout and event handling for rectangles within
+//  a view hierarchy.
+//
+//  Client code typically subclasses View and overrides virtual methods to
+//  handle painting, child view positioning and handle certain types of events.
+//
+//  Views are owned by their parent View unless specified otherwise. This means
+//  that in most cases Views are automatically destroyed when the window that
+//  contains them is destroyed.
+//
+// TODO(beng): consider the visibility of many of these methods.
+//             consider making RootView a friend and making many private or
+//             protected.
+class View {
+ public:
+  typedef std::vector<View*> ViewVector;
+
+  // Creation and lifetime -----------------------------------------------------
+  View();
+  virtual ~View();
+
+  // By default a View is owned by its parent unless specified otherwise here.
+  bool parent_owned() const { return parent_owned_; }
+  void set_parent_owned(bool parent_owned) { parent_owned_ = parent_owned; }
+
+  void set_drag_controller(DragController* drag_controller) {
+    drag_controller_ = drag_controller;
+  }
+
+  // Size and disposition ------------------------------------------------------
+
+  void SetBounds(int x, int y, int width, int height);
+  void SetBoundsRect(const gfx::Rect& bounds);
+  void SetSize(const gfx::Size& size);
+  void SetPosition(const gfx::Point& position);
+  gfx::Rect bounds() const { return bounds_; }
+  gfx::Rect GetVisibleBounds() const;
+  int x() const { return bounds_.x(); }
+  int y() const { return bounds_.y(); }
+  int width() const { return bounds_.width(); }
+  int height() const { return bounds_.height(); }
+
+  // Owned by the view.
+  void SetBorder(Border* border);
+  Border* border() { return border_.get(); }
+
+  // Returns the bounds of the content area of the view, i.e. the rectangle
+  // enclosed by the view's border.
+  gfx::Rect GetContentsBounds() const;
+
+  virtual gfx::Size GetPreferredSize() const;
+  virtual gfx::Size GetMinimumSize() const;
+
+  void SetLayoutManager(LayoutManager* layout_manager);
+  virtual void Layout();
+
+  // If a View is not visible, it will not be rendered, focused, etc.
+  bool visible() const { return visible_; }
+  void SetVisible(bool visible);
+
+  // Disabled Views will not receive mouse press/release events, nor can they be
+  // focused.
+  bool enabled() const { return enabled_; }
+  void SetEnabled(bool enabled);
+
+  virtual void OnBoundsChanged();
+
+  // Coordinate conversion -----------------------------------------------------
+
+  // Converts a point from the coordinate system of |source| to |target|.
+  static void ConvertPointToView(View* source, View* target, gfx::Point* point);
+
+  // Converts a point from the coordinate system of |source| to the screen.
+  // If |source| is not attached to a Widget that is in screen space, |point| is
+  // not modified.
+  static void ConvertPointToScreen(View* source, gfx::Point* point);
+
+  // Converts a point from the coordinate system of |source| to the Widget that
+  // most closely contains it.
+  static void ConvertPointToWidget(View* source, gfx::Point* point);
+
+  // Tree operations -----------------------------------------------------------
+
+  // Returns the Widget that contains this View, or NULL if it is not contained
+  // within a Widget.
+  virtual Widget* GetWidget() const;
+
+  // Adds a View as a child of this one, optionally at |index|.
+  void AddChildView(View* view);
+  void AddChildViewAt(View* view, size_t index);
+
+  // Removes a View as a child of this View. Does not delete the child.
+  View* RemoveChildView(View* view);
+
+  // Removes all View children of this View. Deletes the children if
+  // |delete_children| is true.
+  void RemoveAllChildViews(bool delete_children);
+
+  // Returns the View at the specified |index|.
+  View* GetChildViewAt(size_t index);
+
+  // Returns the number of child views.
+  size_t child_count() const { return children_.size(); }
+
+  // Returns the parent View, or NULL if this View has no parent.
+  View* parent() const { return parent_; }
+
+  // Returns true if |child| is contained within this View's hierarchy, even as
+  // an indirect descendant. Will return true if child is also this View.
+  bool Contains(View* child);
+
+  // Returns the visible View that most closely contains the specified point.
+  // |point| is in this View's coordinates.
+  // This function is used by the event processing system in the Widget to
+  // locate views for event targeting. Override this function if you wish to
+  // specify a view other than the one most closely enclosing |point| to receive
+  // notifications for events within it.
+  // TODO(beng): This is [ab]used primarily for event handling. Should be
+  //             renamed to something like GetViewForEvent().
+  virtual View* GetViewForPoint(const gfx::Point& point) const;
+
+  // Returns true if the specified point is contained within this View or its
+  // hit test mask. |point| is in this View's coordinates.
+  bool HitTest(const gfx::Point& point) const;
+
+  int id() const { return id_; }
+  void set_id(int id) { id_ = id; }
+  int group() const { return group_; }
+  void set_group(int group) { group_ = group; }
+
+  // Returns the View within this View's hierarchy whose id matches that
+  // specified.
+  View* GetViewById(int id) const;
+
+  // Populates a ViewVector with the Views within this View's hierarchy that
+  // match the specified group id.
+  void GetViewsWithGroup(int group, ViewVector* vec) const;
+
+  // Called on every view in the hierarchy when a view is added or removed.
+  virtual void OnViewAdded(View* parent, View* child);
+  virtual void OnViewRemoved(View* parent, View* child);
+
+  // Called on a View when it is added or removed from a Widget.
+  virtual void OnViewAddedToWidget();
+  virtual void OnViewRemovedFromWidget();
+
+  // Accelerators --------------------------------------------------------------
+
+  // Accelerator Registration.
+  void AddAccelerator(const Accelerator& accelerator);
+  void RemoveAccelerator(const Accelerator& accelerator);
+  void RemoveAllAccelerators();
+
+  virtual bool OnAcceleratorPressed(const Accelerator& accelerator);
+
+  // Focus ---------------------------------------------------------------------
+
+  // Manager.
+  FocusManager* GetFocusManager() const;
+
+  // Traversal.
+  virtual FocusTraversable* GetFocusTraversable() const;
+  View* GetNextFocusableView() const;
+  View* GetPreviousFocusableView() const;
+
+  // Attributes.
+  virtual bool SkipDefaultKeyEventProcessing(const KeyEvent& event) const;
+  void set_focusable(bool focusable) { focusable_ = focusable; }
+  bool IsFocusable() const;
+
+  bool HasFocus() const;
+  void RequestFocus();
+
+  virtual void OnFocus(/* const FocusEvent& event */);
+  virtual void OnBlur();
+
+  // Input ---------------------------------------------------------------------
+
+  virtual bool OnKeyPressed(const KeyEvent& event);
+  virtual bool OnKeyReleased(const KeyEvent& event);
+  virtual bool OnMouseWheel(const MouseWheelEvent& event);
+  // To receive OnMouseDragged() or OnMouseReleased() events, overriding classes
+  // must return true from this function.
+  virtual bool OnMousePressed(const MouseEvent& event);
+  virtual bool OnMouseDragged(const MouseEvent& event);
+  virtual void OnMouseReleased(const MouseEvent& event);
+  virtual void OnMouseCaptureLost();
+  virtual void OnMouseMoved(const MouseEvent& event);
+  virtual void OnMouseEntered(const MouseEvent& event);
+  virtual void OnMouseExited(const MouseEvent& event);
+
+  virtual gfx::NativeCursor GetCursorForPoint(const gfx::Point& point);
+
+  // Painting ------------------------------------------------------------------
+
+  void Invalidate();
+  virtual void InvalidateRect(const gfx::Rect& invalid_rect);
+  virtual void Paint(gfx::Canvas* canvas);
+  virtual void PaintChildren(gfx::Canvas* canvas);
+
+  virtual void OnPaint(gfx::Canvas* canvas);

[sky, 2011/02/01 18:56:22]

I think it's worth documenting these so that folks know which one to override
and why.

+  virtual void OnPaintBackground(gfx::Canvas* canvas);
+  virtual void OnPaintBorder(gfx::Canvas* canvas);
+  virtual void OnPaintFocusBorder(gfx::Canvas* canvas);
+
+  // Context menus -------------------------------------------------------------
+
+  void set_context_menu_controller(
+    ContextMenuController* context_menu_controller) {

[sky, 2011/02/01 18:56:22]

indent this two more spaces and bring in line 249 two spaces.

+      context_menu_controller_ = context_menu_controller;
+  }
+
+  // Resources -----------------------------------------------------------------
+
+  ThemeProvider* GetThemeProvider() const;
+
+ private:
+  friend internal::RootView;
+
+  // State collected during a MousePressed event to detect possible drag
+  // operations.
+  struct DragInfo {
+    // Sets possible_drag to false and start_x/y to 0. This is invoked by
+    // RootView prior to invoke MousePressed().
+    void Reset();
+
+    // Sets possible_drag to true and start_pt to the specified point.
+    // This is invoked by the target view if it detects the press may generate
+    // a drag.
+    void PossibleDrag(const gfx::Point& point);
+
+    // Whether the press may generate a drag.
+    bool possible_drag;
+
+    // Position of the mouse press in screen coordinates.
+    gfx::Point press_point;
+  };
+
+  // Drag & Drop ---------------------------------------------------------------
+  int GetDragOperations(const gfx::Point& point);
+  void WriteDragData(const gfx::Point& point, OSExchangeData* data);
+  void StartShellDrag(const MouseEvent& event, const gfx::Point& press_point);
+
+  // RootView API --------------------------------------------------------------
+  //  These methods are designed to be called by the RootView. The RootView
+  //  should limit its interaction with the View to these methods and the public
+  //  API.
+  bool MousePressed(const MouseEvent& event, DragInfo* drag_info);
+  bool MouseDragged(const MouseEvent& event, DragInfo* drag_info);
+  void MouseReleased(const MouseEvent& event);
+
+  // Tree operations -----------------------------------------------------------
+  void NotifyHierarchyChanged(View* parent, View* child, bool is_add);
+  void NotifyHierarchyChangedUp(View* parent, View* child, bool is_add);
+  void NotifyHierarchyChangedDown(View* parent, View* child, bool is_add,
+                                   bool has_widget);
+  void CallViewNotification(View* target,
+                            View* parent,
+                            View* child,
+                            bool is_add,
+                            bool has_widget);
+
+  // The View's parent view. This is set and reset when the View is added and
+  // removed from a hierarchy.
+  View* parent_;
+
+  // The View's children.
+  ViewVector children_;
+
+  // True if the hierarchy (i.e. the parent View) is responsible for deleting
+  // this View. Default is true.
+  bool parent_owned_;
+
+  // The bounds of the View, in its parent's coordinates.
+  gfx::Rect bounds_;
+
+  scoped_ptr<Border> border_;
+
+  // Whether or not this View is visible. The view still participates in layout
+  // but will not be painted.
+  bool visible_;
+
+  // Whether or not this View is enabled. When disabled, the event system will
+  // not propagate un-handled events beyond the View in the hierarchy.
+  bool enabled_;
+
+  // An identifier for this View. Caller must guarantee uniqueness.
+  int id_;
+
+  // An identifier for a group of potentially related Views.
+  int group_;
+
+  // True if this View is focusable by the FocusManager.
+  bool focusable_;
+
+  // An optional helper that handles layout for child views.
+  scoped_ptr<LayoutManager> layout_manager_;
+
+  // Shows the context menu.
+  ContextMenuController* context_menu_controller_;
+
+  // Delegate for drag and drop related functionality.
+  DragController* drag_controller_;
+
+  DISALLOW_COPY_AND_ASSIGN(View);
+};
+
+}  // namespace ui
+
+#endif  // UI_VIEWS_VIEW_H_
+
+/*
+
+TODO(beng):
+- focus
+- accessibility
+- scrolling
+- cursors
+- tooltips
+- rtl
+- l10n
+- mousewheel
+- more on painting
+- layer stuff
+- investigate why assorted notifications are necessary
+- native_widget_views
+- native_widget_gtk
+- pick a name
+
+*/