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.
5 #ifndef UI_AURA_WINDOW_H_
6 #define UI_AURA_WINDOW_H_
12 #include "base/basictypes.h"
13 #include "base/compiler_specific.h"
14 #include "base/memory/scoped_ptr.h"
15 #include "base/observer_list.h"
16 #include "base/strings/string16.h"
17 #include "ui/aura/aura_export.h"
18 #include "ui/aura/window_layer_type.h"
19 #include "ui/aura/window_observer.h"
20 #include "ui/compositor/layer_animator.h"
21 #include "ui/compositor/layer_delegate.h"
22 #include "ui/compositor/layer_owner.h"
23 #include "ui/events/event_constants.h"
24 #include "ui/events/event_target.h"
25 #include "ui/events/event_targeter.h"
26 #include "ui/events/gestures/gesture_types.h"
27 #include "ui/gfx/insets.h"
28 #include "ui/gfx/native_widget_types.h"
29 #include "ui/gfx/rect.h"
30 #include "ui/wm/public/window_types.h"
51 // TODO(beng): remove once RootWindow is renamed.
52 typedef RootWindow WindowEventDispatcher;
54 // Defined in window_property.h (which we do not include)
56 struct WindowProperty;
62 // Aura window implementation. Interesting events are sent to the
64 // TODO(beng): resolve ownership.
65 class AURA_EXPORT Window : public ui::LayerDelegate,
66 public ui::LayerOwner,
67 public ui::EventTarget,
68 public ui::GestureConsumer {
70 // Used when stacking windows.
76 typedef std::vector<Window*> Windows;
78 explicit Window(WindowDelegate* delegate);
81 // Initializes the window. This creates the window's layer.
82 void Init(WindowLayerType layer_type);
84 // Creates a new layer for the window. Erases the layer-owned bounds, so the
85 // caller may wish to set new bounds and other state on the window/layer.
86 // Returns the old layer, which can be used for animations. Caller owns the
87 // memory for the returned layer and must delete it when animation completes.
88 // Returns NULL and does not recreate layer if window does not own its layer.
89 ui::Layer* RecreateLayer() WARN_UNUSED_RESULT;
91 void set_owned_by_parent(bool owned_by_parent) {
92 owned_by_parent_ = owned_by_parent;
94 bool owned_by_parent() const { return owned_by_parent_; }
96 // A type is used to identify a class of Windows and customize behavior such
97 // as event handling and parenting. This field should only be consumed by the
98 // shell -- Aura itself shouldn't contain type-specific logic.
99 ui::wm::WindowType type() const { return type_; }
100 void SetType(ui::wm::WindowType type);
102 int id() const { return id_; }
103 void set_id(int id) { id_ = id; }
105 const std::string& name() const { return name_; }
106 void SetName(const std::string& name);
108 const base::string16 title() const { return title_; }
109 void set_title(const base::string16& title) { title_ = title; }
111 bool transparent() const { return transparent_; }
112 void SetTransparent(bool transparent);
114 WindowDelegate* delegate() { return delegate_; }
115 const WindowDelegate* delegate() const { return delegate_; }
117 const gfx::Rect& bounds() const { return bounds_; }
119 Window* parent() { return parent_; }
120 const Window* parent() const { return parent_; }
122 // Returns the root Window that contains this Window. The root Window is
123 // defined as the Window that has a dispatcher. These functions return NULL if
124 // the Window is contained in a hierarchy that does not have a dispatcher at
126 virtual Window* GetRootWindow();
127 virtual const Window* GetRootWindow() const;
129 WindowEventDispatcher* GetDispatcher();
130 const WindowEventDispatcher* GetDispatcher() const;
131 void set_dispatcher(WindowEventDispatcher* dispatcher) {
132 dispatcher_ = dispatcher;
134 bool HasDispatcher() const { return !!dispatcher_; }
136 // The Window does not own this object.
137 void set_user_data(void* user_data) { user_data_ = user_data; }
138 void* user_data() const { return user_data_; }
140 // Changes the visibility of the window.
143 // Returns true if this window and all its ancestors are visible.
144 bool IsVisible() const;
145 // Returns the visibility requested by this window. IsVisible() takes into
146 // account the visibility of the layer and ancestors, where as this tracks
147 // whether Show() without a Hide() has been invoked.
148 bool TargetVisibility() const { return visible_; }
150 // Returns the window's bounds in root window's coordinates.
151 gfx::Rect GetBoundsInRootWindow() const;
153 // Returns the window's bounds in screen coordinates.
154 // How the root window's coordinates is mapped to screen's coordinates
155 // is platform dependent and defined in the implementation of the
156 // |aura::client::ScreenPositionClient| interface.
157 gfx::Rect GetBoundsInScreen() const;
159 virtual void SetTransform(const gfx::Transform& transform);
161 // Assigns a LayoutManager to size and place child windows.
162 // The Window takes ownership of the LayoutManager.
163 void SetLayoutManager(LayoutManager* layout_manager);
164 LayoutManager* layout_manager() { return layout_manager_.get(); }
166 // Sets a new event-targeter for the window, and returns the previous
168 scoped_ptr<ui::EventTargeter> SetEventTargeter(
169 scoped_ptr<ui::EventTargeter> targeter);
171 // Changes the bounds of the window. If present, the window's parent's
172 // LayoutManager may adjust the bounds.
173 void SetBounds(const gfx::Rect& new_bounds);
175 // Changes the bounds of the window in the screen coordintates.
176 // If present, the window's parent's LayoutManager may adjust the bounds.
177 void SetBoundsInScreen(const gfx::Rect& new_bounds_in_screen_coords,
178 const gfx::Display& dst_display);
180 // Returns the target bounds of the window. If the window's layer is
181 // not animating, it simply returns the current bounds.
182 gfx::Rect GetTargetBounds() const;
184 // Marks the a portion of window as needing to be painted.
185 void SchedulePaintInRect(const gfx::Rect& rect);
187 // Stacks the specified child of this Window at the front of the z-order.
188 void StackChildAtTop(Window* child);
190 // Stacks |child| above |target|. Does nothing if |child| is already above
191 // |target|. Does not stack on top of windows with NULL layer delegates,
192 // see WindowTest.StackingMadrigal for details.
193 void StackChildAbove(Window* child, Window* target);
195 // Stacks the specified child of this window at the bottom of the z-order.
196 void StackChildAtBottom(Window* child);
198 // Stacks |child| below |target|. Does nothing if |child| is already below
200 void StackChildBelow(Window* child, Window* target);
203 void AddChild(Window* child);
204 void RemoveChild(Window* child);
206 const Windows& children() const { return children_; }
208 // Returns true if this Window contains |other| somewhere in its children.
209 bool Contains(const Window* other) const;
211 // Retrieves the first-level child with the specified id, or NULL if no first-
212 // level child is found matching |id|.
213 Window* GetChildById(int id);
214 const Window* GetChildById(int id) const;
216 // Converts |point| from |source|'s coordinates to |target|'s. If |source| is
217 // NULL, the function returns without modifying |point|. |target| cannot be
219 static void ConvertPointToTarget(const Window* source,
220 const Window* target,
223 // Moves the cursor to the specified location relative to the window.
224 virtual void MoveCursorTo(const gfx::Point& point_in_window);
226 // Returns the cursor for the specified point, in window coordinates.
227 gfx::NativeCursor GetCursor(const gfx::Point& point) const;
229 // Sets an 'event filter' for the window. An 'event filter' for a Window is
230 // a pre-target event handler, where the window owns the handler. A window
231 // can have only one such event filter. Setting a new filter removes and
232 // destroys any previously installed filter.
233 void SetEventFilter(ui::EventHandler* event_filter);
235 // Add/remove observer.
236 void AddObserver(WindowObserver* observer);
237 void RemoveObserver(WindowObserver* observer);
238 bool HasObserver(WindowObserver* observer);
240 void set_ignore_events(bool ignore_events) { ignore_events_ = ignore_events; }
241 bool ignore_events() const { return ignore_events_; }
243 // Sets the window to grab hits for an area extending |insets| pixels inside
244 // its bounds (even if that inner region overlaps a child window). This can be
245 // used to create an invisible non-client area that overlaps the client area.
246 void set_hit_test_bounds_override_inner(const gfx::Insets& insets) {
247 hit_test_bounds_override_inner_ = insets;
249 gfx::Insets hit_test_bounds_override_inner() const {
250 return hit_test_bounds_override_inner_;
253 // Returns true if the |point_in_root| in root window's coordinate falls
254 // within this window's bounds. Returns false if the window is detached
256 bool ContainsPointInRoot(const gfx::Point& point_in_root) const;
258 // Returns true if relative-to-this-Window's-origin |local_point| falls
259 // within this Window's bounds.
260 bool ContainsPoint(const gfx::Point& local_point) const;
262 // Returns true if the mouse pointer at relative-to-this-Window's-origin
263 // |local_point| can trigger an event for this Window.
264 // TODO(beng): A Window can supply a hit-test mask to cause some portions of
265 // itself to not trigger events, causing the events to fall through to the
267 bool HitTest(const gfx::Point& local_point);
269 // Returns the Window that most closely encloses |local_point| for the
270 // purposes of event targeting.
271 Window* GetEventHandlerForPoint(const gfx::Point& local_point);
273 // Returns the topmost Window with a delegate containing |local_point|.
274 Window* GetTopWindowContainingPoint(const gfx::Point& local_point);
276 // Returns this window's toplevel window (the highest-up-the-tree anscestor
277 // that has a delegate set). The toplevel window may be |this|.
278 Window* GetToplevelWindow();
280 // Claims or relinquishes the claim to focus.
284 // Returns true if the Window is currently the focused window.
285 bool HasFocus() const;
287 // Returns true if the Window can be focused.
288 virtual bool CanFocus() const;
290 // Returns true if the Window can receive events.
291 virtual bool CanReceiveEvents() const;
293 // Does a capture on the window. This does nothing if the window isn't showing
294 // (VISIBILITY_SHOWN) or isn't contained in a valid window hierarchy.
297 // Releases a capture.
298 void ReleaseCapture();
300 // Returns true if this window has capture.
303 // Suppresses painting window content by disgarding damaged rect and ignoring
304 // new paint requests. This is a one way operation and there is no way to
305 // reenable painting.
306 void SuppressPaint();
308 // Sets the |value| of the given window |property|. Setting to the default
309 // value (e.g., NULL) removes the property. The caller is responsible for the
310 // lifetime of any object set as a property on the Window.
312 void SetProperty(const WindowProperty<T>* property, T value);
314 // Returns the value of the given window |property|. Returns the
315 // property-specific default value if the property was not previously set.
317 T GetProperty(const WindowProperty<T>* property) const;
319 // Sets the |property| to its default value. Useful for avoiding a cast when
322 void ClearProperty(const WindowProperty<T>* property);
324 // NativeWidget::[GS]etNativeWindowProperty use strings as keys, and this is
325 // difficult to change while retaining compatibility with other platforms.
326 // TODO(benrg): Find a better solution.
327 void SetNativeWindowProperty(const char* key, void* value);
328 void* GetNativeWindowProperty(const char* key) const;
330 // Type of a function to delete a property that this window owns.
331 typedef void (*PropertyDeallocator)(int64 value);
333 // Overridden from ui::LayerDelegate:
334 virtual void OnDeviceScaleFactorChanged(float device_scale_factor) OVERRIDE;
337 // These methods are useful when debugging.
338 std::string GetDebugInfo() const;
339 void PrintWindowHierarchy(int depth) const;
343 // Deletes (or removes if not owned by parent) all child windows. Intended for
344 // use from the destructor.
345 void RemoveOrDestroyChildren();
348 friend class test::WindowTestApi;
349 friend class LayoutManager;
350 friend class RootWindow;
351 friend class WindowTargeter;
353 // Called by the public {Set,Get,Clear}Property functions.
354 int64 SetPropertyInternal(const void* key,
356 PropertyDeallocator deallocator,
358 int64 default_value);
359 int64 GetPropertyInternal(const void* key, int64 default_value) const;
361 // Changes the bounds of the window without condition.
362 void SetBoundsInternal(const gfx::Rect& new_bounds);
364 // Updates the visible state of the layer, but does not make visible-state
365 // specific changes. Called from Show()/Hide().
366 void SetVisible(bool visible);
368 // Schedules a paint for the Window's entire bounds.
369 void SchedulePaint();
371 // Asks the delegate to paint the window and invokes PaintLayerlessChildren()
372 // to paint any children with no layers.
373 void Paint(gfx::Canvas* canvas);
375 // Paints any layerless children to |canvas|.
376 void PaintLayerlessChildren(gfx::Canvas* canvas);
378 // Gets a Window (either this one or a subwindow) containing |local_point|.
379 // If |return_tightest| is true, returns the tightest-containing (i.e.
380 // furthest down the hierarchy) Window containing the point; otherwise,
381 // returns the loosest. If |for_event_handling| is true, then hit-test masks
382 // are honored; otherwise, only bounds checks are performed.
383 Window* GetWindowForPoint(const gfx::Point& local_point,
384 bool return_tightest,
385 bool for_event_handling);
387 // Implementation of RemoveChild(). If |child| is being removed as the result
388 // of an add, |new_parent| is the new parent |child| is going to be parented
390 void RemoveChildImpl(Window* child, Window* new_parent);
392 // If this Window has a layer the layer's parent is set to NULL, otherwise
393 // UnparentLayers() is invoked on all the children. |offset| is the offset
394 // relative to the nearest ancestor with a layer.
395 void UnparentLayers(bool has_layerless_ancestor,
396 const gfx::Vector2d& offset);
398 // If this Window has a layer it is added to |parent| and the origin set to
399 // |offset|. Otherwise this recurses through the children invoking
400 // ReparentLayers(). The net effect is both setting the parent of layers to
401 // |parent| as well as updating bounds of windows with a layerless ancestor.
402 void ReparentLayers(ui::Layer* parent, const gfx::Vector2d& offset);
404 // Offsets the first encountered Windows with layers by |offset|. This
405 // recurses through all layerless Windows, stopping at windows with layers.
406 void OffsetLayerBounds(const gfx::Vector2d& offset);
408 // Called when this window's parent has changed.
409 void OnParentChanged();
411 // The various stacking functions call into this to do the actual stacking.
412 void StackChildRelativeTo(Window* child,
414 StackDirection direction);
416 // Invoked from StackChildRelativeTo() to stack the layers appropriately
417 // when stacking |child| relative to |target|.
418 void StackChildLayerRelativeTo(Window* child,
420 StackDirection direction);
422 // Called when this window's stacking order among its siblings is changed.
423 void OnStackingChanged();
425 // Notifies observers registered with this Window (and its subtree) when the
426 // Window has been added or is about to be removed from a RootWindow.
427 void NotifyRemovingFromRootWindow();
428 void NotifyAddedToRootWindow();
430 // Methods implementing hierarchy change notifications. See WindowObserver for
432 void NotifyWindowHierarchyChange(
433 const WindowObserver::HierarchyChangeParams& params);
434 // Notifies this window and its child hierarchy.
435 void NotifyWindowHierarchyChangeDown(
436 const WindowObserver::HierarchyChangeParams& params);
437 // Notifies this window and its parent hierarchy.
438 void NotifyWindowHierarchyChangeUp(
439 const WindowObserver::HierarchyChangeParams& params);
440 // Notifies this window's observers.
441 void NotifyWindowHierarchyChangeAtReceiver(
442 const WindowObserver::HierarchyChangeParams& params);
444 // Methods implementing visibility change notifications. See WindowObserver
446 void NotifyWindowVisibilityChanged(aura::Window* target, bool visible);
447 // Notifies this window's observers. Returns false if |this| was deleted
448 // during the call (by an observer), otherwise true.
449 bool NotifyWindowVisibilityChangedAtReceiver(aura::Window* target,
451 // Notifies this window and its child hierarchy. Returns false if
452 // |this| was deleted during the call (by an observer), otherwise
454 bool NotifyWindowVisibilityChangedDown(aura::Window* target, bool visible);
455 // Notifies this window and its parent hierarchy.
456 void NotifyWindowVisibilityChangedUp(aura::Window* target, bool visible);
458 // Invoked when the bounds of the window changes. This may be invoked directly
459 // by us, or from the closure returned by PrepareForLayerBoundsChange() after
460 // the bounds of the layer has changed. |old_bounds| is the previous bounds,
461 // and |contained_mouse| is true if the mouse was previously within the
463 void OnWindowBoundsChanged(const gfx::Rect& old_bounds, bool contained_mouse);
465 // Overridden from ui::LayerDelegate:
466 virtual void OnPaintLayer(gfx::Canvas* canvas) OVERRIDE;
467 virtual base::Closure PrepareForLayerBoundsChange() OVERRIDE;
469 // Overridden from ui::EventTarget:
470 virtual bool CanAcceptEvent(const ui::Event& event) OVERRIDE;
471 virtual EventTarget* GetParentTarget() OVERRIDE;
472 virtual scoped_ptr<ui::EventTargetIterator> GetChildIterator() const OVERRIDE;
473 virtual ui::EventTargeter* GetEventTargeter() OVERRIDE;
474 virtual void ConvertEventToTarget(ui::EventTarget* target,
475 ui::LocatedEvent* event) OVERRIDE;
477 // Updates the layer name with a name based on the window's name and id.
478 void UpdateLayerName(const std::string& name);
480 // Returns true if the mouse is currently within our bounds.
481 bool ContainsMouse();
483 // Returns the first ancestor (starting at |this|) with a layer. |offset| is
484 // set to the offset from |this| to the first ancestor with a layer. |offset|
486 Window* GetAncestorWithLayer(gfx::Vector2d* offset) {
487 return const_cast<Window*>(
488 const_cast<const Window*>(this)->GetAncestorWithLayer(offset));
490 const Window* GetAncestorWithLayer(gfx::Vector2d* offset) const;
492 // Bounds of this window relative to the parent. This is cached as the bounds
493 // of the Layer and Window are not necessarily the same. In particular bounds
494 // of the Layer are relative to the first ancestor with a Layer, where as this
495 // is relative to the parent Window.
498 WindowEventDispatcher* dispatcher_;
500 ui::wm::WindowType type_;
502 // True if the Window is owned by its parent - i.e. it will be deleted by its
503 // parent during its parents destruction. True is the default.
504 bool owned_by_parent_;
506 WindowDelegate* delegate_;
508 // The Window's parent.
511 // Child windows. Topmost is last.
514 // The visibility state of the window as set by Show()/Hide(). This may differ
515 // from the visibility of the underlying layer, which may remain visible after
516 // the window is hidden (e.g. to animate its disappearance).
522 base::string16 title_;
524 // Whether layer is initialized as non-opaque.
527 scoped_ptr<ui::EventHandler> event_filter_;
528 scoped_ptr<LayoutManager> layout_manager_;
529 scoped_ptr<ui::EventTargeter> targeter_;
533 // Makes the window pass all events through to any windows behind it.
536 // See set_hit_test_bounds_override_inner().
537 gfx::Insets hit_test_bounds_override_inner_;
539 ObserverList<WindowObserver, true> observers_;
541 // Value struct to keep the name and deallocator for this property.
542 // Key cannot be used for this purpose because it can be char* or
547 PropertyDeallocator deallocator;
550 std::map<const void*, Value> prop_map_;
552 DISALLOW_COPY_AND_ASSIGN(Window);
557 #endif // UI_AURA_WINDOW_H_