OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2011 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 <vector> |
| 9 |
| 10 #include "base/logging.h" |
| 11 #include "base/scoped_ptr.h" |
| 12 #include "gfx/rect.h" |
| 13 #include "ui/views/events/event.h" |
| 14 |
| 15 namespace gfx { |
| 16 class Canvas; |
| 17 class Point; |
| 18 class Rect; |
| 19 class Size; |
| 20 } |
| 21 |
| 22 namespace ui { |
| 23 namespace internal { |
| 24 class RootView; |
| 25 } |
| 26 class Accelerator; |
| 27 class Border; |
| 28 class ContextMenuController; |
| 29 class DragController; |
| 30 class FocusManager; |
| 31 class FocusTraversable; |
| 32 class LayoutManager; |
| 33 class ThemeProvider; |
| 34 class Widget; |
| 35 |
| 36 //////////////////////////////////////////////////////////////////////////////// |
| 37 // View class |
| 38 // |
| 39 // View encapsulates rendering, layout and event handling for rectangles within |
| 40 // a view hierarchy. |
| 41 // |
| 42 // Client code typically subclasses View and overrides virtual methods to |
| 43 // handle painting, child view positioning and handle certain types of events. |
| 44 // |
| 45 // Views are owned by their parent View unless specified otherwise. This means |
| 46 // that in most cases Views are automatically destroyed when the window that |
| 47 // contains them is destroyed. |
| 48 // |
| 49 // TODO(beng): consider the visibility of many of these methods. |
| 50 // consider making RootView a friend and making many private or |
| 51 // protected. |
| 52 class View { |
| 53 public: |
| 54 typedef std::vector<View*> ViewVector; |
| 55 |
| 56 // Creation and lifetime ----------------------------------------------------- |
| 57 View(); |
| 58 virtual ~View(); |
| 59 |
| 60 // By default a View is owned by its parent unless specified otherwise here. |
| 61 bool parent_owned() const { return parent_owned_; } |
| 62 void set_parent_owned(bool parent_owned) { parent_owned_ = parent_owned; } |
| 63 |
| 64 void set_drag_controller(DragController* drag_controller) { |
| 65 drag_controller_ = drag_controller; |
| 66 } |
| 67 |
| 68 // Size and disposition ------------------------------------------------------ |
| 69 |
| 70 void SetBounds(int x, int y, int width, int height); |
| 71 void SetBoundsRect(const gfx::Rect& bounds); |
| 72 void SetSize(const gfx::Size& size); |
| 73 void SetPosition(const gfx::Point& position); |
| 74 gfx::Rect bounds() const { return bounds_; } |
| 75 gfx::Rect GetVisibleBounds() const; |
| 76 int x() const { return bounds_.x(); } |
| 77 int y() const { return bounds_.y(); } |
| 78 int width() const { return bounds_.width(); } |
| 79 int height() const { return bounds_.height(); } |
| 80 |
| 81 // Owned by the view. |
| 82 void SetBorder(Border* border); |
| 83 Border* border() { return border_.get(); } |
| 84 |
| 85 // Returns the bounds of the content area of the view, i.e. the rectangle |
| 86 // enclosed by the view's border. |
| 87 gfx::Rect GetContentsBounds() const; |
| 88 |
| 89 // Override to be notified when the bounds of a view have changed. |
| 90 virtual void OnBoundsChanged(); |
| 91 |
| 92 virtual gfx::Size GetPreferredSize() const; |
| 93 virtual gfx::Size GetMinimumSize() const; |
| 94 |
| 95 void SetLayoutManager(LayoutManager* layout_manager); |
| 96 virtual void Layout(); |
| 97 |
| 98 // If a View is not visible, it will not be rendered, focused, etc. |
| 99 bool visible() const { return visible_; } |
| 100 void SetVisible(bool visible); |
| 101 |
| 102 // Disabled Views will not receive mouse press/release events, nor can they be |
| 103 // focused. |
| 104 bool enabled() const { return enabled_; } |
| 105 void SetEnabled(bool enabled); |
| 106 |
| 107 // Coordinate conversion ----------------------------------------------------- |
| 108 |
| 109 // Converts a point from the coordinate system of |source| to |target|. |
| 110 static void ConvertPointToView(View* source, View* target, gfx::Point* point); |
| 111 |
| 112 // Converts a point from the coordinate system of |source| to the screen. |
| 113 // If |source| is not attached to a Widget that is in screen space, |point| is |
| 114 // not modified. |
| 115 static void ConvertPointToScreen(View* source, gfx::Point* point); |
| 116 |
| 117 // Converts a point from the coordinate system of |source| to the Widget that |
| 118 // most closely contains it. |
| 119 static void ConvertPointToWidget(View* source, gfx::Point* point); |
| 120 |
| 121 // Tree operations ----------------------------------------------------------- |
| 122 |
| 123 // Returns the Widget that contains this View, or NULL if it is not contained |
| 124 // within a Widget. |
| 125 virtual Widget* GetWidget() const; |
| 126 |
| 127 // Adds a View as a child of this one, optionally at |index|. |
| 128 void AddChildView(View* view); |
| 129 void AddChildViewAt(View* view, size_t index); |
| 130 |
| 131 // Removes a View as a child of this View. Does not delete the child. |
| 132 View* RemoveChildView(View* view); |
| 133 |
| 134 // Removes all View children of this View. Deletes the children if |
| 135 // |delete_children| is true. |
| 136 void RemoveAllChildViews(bool delete_children); |
| 137 |
| 138 // Returns the View at the specified |index|. |
| 139 View* GetChildViewAt(size_t index); |
| 140 |
| 141 // Returns the number of child views. |
| 142 size_t child_count() const { return children_.size(); } |
| 143 |
| 144 // Returns the parent View, or NULL if this View has no parent. |
| 145 View* parent() const { return parent_; } |
| 146 |
| 147 // Returns true if |child| is contained within this View's hierarchy, even as |
| 148 // an indirect descendant. Will return true if child is also this View. |
| 149 bool Contains(View* child); |
| 150 |
| 151 // Returns the visible View that most closely contains the specified point. |
| 152 // |point| is in this View's coordinates. |
| 153 // This function is used by the event processing system in the Widget to |
| 154 // locate views for event targeting. Override this function if you wish to |
| 155 // specify a view other than the one most closely enclosing |point| to receive |
| 156 // notifications for events within it. |
| 157 // TODO(beng): This is [ab]used primarily for event handling. Should be |
| 158 // renamed to something like GetViewForEvent(). |
| 159 virtual View* GetViewForPoint(const gfx::Point& point) const; |
| 160 |
| 161 // Returns true if the specified point is contained within this View or its |
| 162 // hit test mask. |point| is in this View's coordinates. |
| 163 bool HitTest(const gfx::Point& point) const; |
| 164 |
| 165 int id() const { return id_; } |
| 166 void set_id(int id) { id_ = id; } |
| 167 int group() const { return group_; } |
| 168 void set_group(int group) { group_ = group; } |
| 169 |
| 170 // Returns the View within this View's hierarchy whose id matches that |
| 171 // specified. |
| 172 View* GetViewById(int id) const; |
| 173 |
| 174 // Populates a ViewVector with the Views within this View's hierarchy that |
| 175 // match the specified group id. |
| 176 void GetViewsWithGroup(int group, ViewVector* vec) const; |
| 177 |
| 178 // Called on every view in the hierarchy when a view is added or removed. |
| 179 virtual void OnViewAdded(View* parent, View* child); |
| 180 virtual void OnViewRemoved(View* parent, View* child); |
| 181 |
| 182 // Called on a View when it is added or removed from a Widget. |
| 183 virtual void OnViewAddedToWidget(); |
| 184 virtual void OnViewRemovedFromWidget(); |
| 185 |
| 186 // Accelerators -------------------------------------------------------------- |
| 187 |
| 188 // Accelerator Registration. |
| 189 void AddAccelerator(const Accelerator& accelerator); |
| 190 void RemoveAccelerator(const Accelerator& accelerator); |
| 191 void RemoveAllAccelerators(); |
| 192 |
| 193 virtual bool OnAcceleratorPressed(const Accelerator& accelerator); |
| 194 |
| 195 // Focus --------------------------------------------------------------------- |
| 196 |
| 197 // Manager. |
| 198 FocusManager* GetFocusManager() const; |
| 199 |
| 200 // Traversal. |
| 201 virtual FocusTraversable* GetFocusTraversable() const; |
| 202 View* GetNextFocusableView() const; |
| 203 View* GetPreviousFocusableView() const; |
| 204 |
| 205 // Attributes. |
| 206 virtual bool SkipDefaultKeyEventProcessing(const KeyEvent& event) const; |
| 207 void set_focusable(bool focusable) { focusable_ = focusable; } |
| 208 bool IsFocusable() const; |
| 209 |
| 210 bool HasFocus() const; |
| 211 void RequestFocus(); |
| 212 |
| 213 virtual void OnFocus(/* const FocusEvent& event */); |
| 214 virtual void OnBlur(); |
| 215 |
| 216 // Input --------------------------------------------------------------------- |
| 217 |
| 218 virtual bool OnKeyPressed(const KeyEvent& event); |
| 219 virtual bool OnKeyReleased(const KeyEvent& event); |
| 220 virtual bool OnMouseWheel(const MouseWheelEvent& event); |
| 221 // To receive OnMouseDragged() or OnMouseReleased() events, overriding classes |
| 222 // must return true from this function. |
| 223 virtual bool OnMousePressed(const MouseEvent& event); |
| 224 virtual bool OnMouseDragged(const MouseEvent& event); |
| 225 virtual void OnMouseReleased(const MouseEvent& event); |
| 226 virtual void OnMouseCaptureLost(); |
| 227 virtual void OnMouseMoved(const MouseEvent& event); |
| 228 virtual void OnMouseEntered(const MouseEvent& event); |
| 229 virtual void OnMouseExited(const MouseEvent& event); |
| 230 |
| 231 virtual gfx::NativeCursor GetCursorForPoint(const gfx::Point& point); |
| 232 |
| 233 // Painting ------------------------------------------------------------------ |
| 234 |
| 235 // Add all or part of a View's bounds to the enclosing Widget's invalid |
| 236 // rectangle. This will result in those areas being re-painted on the next |
| 237 // update. |
| 238 void Invalidate(); |
| 239 virtual void InvalidateRect(const gfx::Rect& invalid_rect); |
| 240 |
| 241 // Called by the framework to paint a View. Performs translation and clipping |
| 242 // for View coordinates and language direction as required, allows the View |
| 243 // to paint itself via the various OnPaint*() event handlers and then paints |
| 244 // the hierarchy beneath it. |
| 245 // TODO(beng): Make private? |
| 246 void Paint(gfx::Canvas* canvas); |
| 247 |
| 248 // Responsible for calling Paint() on child Views. Override to control the |
| 249 // order child Views are painted. |
| 250 virtual void PaintChildren(gfx::Canvas* canvas); |
| 251 |
| 252 // Override to provide rendering in any part of the View's bounds. Typically |
| 253 // this is the "contents" of the view. If you override this method you will |
| 254 // have to call the subsequent OnPaint*() methods manually. |
| 255 virtual void OnPaint(gfx::Canvas* canvas); |
| 256 |
| 257 // Override to paint a background before any content is drawn. Typically this |
| 258 // is done if you are satisfied with a default OnPaint handler but wish to |
| 259 // supply a different background. |
| 260 virtual void OnPaintBackground(gfx::Canvas* canvas); |
| 261 |
| 262 // Override to paint a border not specified by SetBorder(). |
| 263 virtual void OnPaintBorder(gfx::Canvas* canvas); |
| 264 |
| 265 // Override to paint a focus border (usually a dotted rectangle) around |
| 266 // relevant contents. |
| 267 virtual void OnPaintFocusBorder(gfx::Canvas* canvas); |
| 268 |
| 269 // Context menus ------------------------------------------------------------- |
| 270 |
| 271 void set_context_menu_controller( |
| 272 ContextMenuController* context_menu_controller) { |
| 273 context_menu_controller_ = context_menu_controller; |
| 274 } |
| 275 |
| 276 // Resources ----------------------------------------------------------------- |
| 277 |
| 278 ThemeProvider* GetThemeProvider() const; |
| 279 |
| 280 private: |
| 281 friend internal::RootView; |
| 282 |
| 283 // State collected during a MousePressed event to detect possible drag |
| 284 // operations. |
| 285 struct DragInfo { |
| 286 // Sets possible_drag to false and start_x/y to 0. This is invoked by |
| 287 // RootView prior to invoke MousePressed(). |
| 288 void Reset(); |
| 289 |
| 290 // Sets possible_drag to true and start_pt to the specified point. |
| 291 // This is invoked by the target view if it detects the press may generate |
| 292 // a drag. |
| 293 void PossibleDrag(const gfx::Point& point); |
| 294 |
| 295 // Whether the press may generate a drag. |
| 296 bool possible_drag; |
| 297 |
| 298 // Position of the mouse press in screen coordinates. |
| 299 gfx::Point press_point; |
| 300 }; |
| 301 |
| 302 // Drag & Drop --------------------------------------------------------------- |
| 303 int GetDragOperations(const gfx::Point& point); |
| 304 void WriteDragData(const gfx::Point& point, OSExchangeData* data); |
| 305 void StartShellDrag(const MouseEvent& event, const gfx::Point& press_point); |
| 306 |
| 307 // RootView API -------------------------------------------------------------- |
| 308 // These methods are designed to be called by the RootView. The RootView |
| 309 // should limit its interaction with the View to these methods and the public |
| 310 // API. |
| 311 bool MousePressed(const MouseEvent& event, DragInfo* drag_info); |
| 312 bool MouseDragged(const MouseEvent& event, DragInfo* drag_info); |
| 313 void MouseReleased(const MouseEvent& event); |
| 314 |
| 315 // Tree operations ----------------------------------------------------------- |
| 316 void NotifyHierarchyChanged(View* parent, View* child, bool is_add); |
| 317 void NotifyHierarchyChangedUp(View* parent, View* child, bool is_add); |
| 318 void NotifyHierarchyChangedDown(View* parent, View* child, bool is_add, |
| 319 bool has_widget); |
| 320 void CallViewNotification(View* target, |
| 321 View* parent, |
| 322 View* child, |
| 323 bool is_add, |
| 324 bool has_widget); |
| 325 |
| 326 // The View's parent view. This is set and reset when the View is added and |
| 327 // removed from a hierarchy. |
| 328 View* parent_; |
| 329 |
| 330 // The View's children. |
| 331 ViewVector children_; |
| 332 |
| 333 // True if the hierarchy (i.e. the parent View) is responsible for deleting |
| 334 // this View. Default is true. |
| 335 bool parent_owned_; |
| 336 |
| 337 // The bounds of the View, in its parent's coordinates. |
| 338 gfx::Rect bounds_; |
| 339 |
| 340 scoped_ptr<Border> border_; |
| 341 |
| 342 // Whether or not this View is visible. The view still participates in layout |
| 343 // but will not be painted. |
| 344 bool visible_; |
| 345 |
| 346 // Whether or not this View is enabled. When disabled, the event system will |
| 347 // not propagate un-handled events beyond the View in the hierarchy. |
| 348 bool enabled_; |
| 349 |
| 350 // An identifier for this View. Caller must guarantee uniqueness. |
| 351 int id_; |
| 352 |
| 353 // An identifier for a group of potentially related Views. |
| 354 int group_; |
| 355 |
| 356 // True if this View is focusable by the FocusManager. |
| 357 bool focusable_; |
| 358 |
| 359 // An optional helper that handles layout for child views. |
| 360 scoped_ptr<LayoutManager> layout_manager_; |
| 361 |
| 362 // Shows the context menu. |
| 363 ContextMenuController* context_menu_controller_; |
| 364 |
| 365 // Delegate for drag and drop related functionality. |
| 366 DragController* drag_controller_; |
| 367 |
| 368 DISALLOW_COPY_AND_ASSIGN(View); |
| 369 }; |
| 370 |
| 371 } // namespace ui |
| 372 |
| 373 #endif // UI_VIEWS_VIEW_H_ |
| 374 |
| 375 /* |
| 376 |
| 377 TODO(beng): |
| 378 - focus |
| 379 - accessibility |
| 380 - scrolling |
| 381 - cursors |
| 382 - tooltips |
| 383 - rtl |
| 384 - l10n |
| 385 - mousewheel |
| 386 - more on painting |
| 387 - layer stuff |
| 388 - investigate why assorted notifications are necessary |
| 389 - native_widget_views |
| 390 - native_widget_gtk |
| 391 - pick a name |
| 392 |
| 393 */ |
OLD | NEW |