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/client/window_types.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/compositor/layer_type.h"
24 #include "ui/events/event_constants.h"
25 #include "ui/events/event_target.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"
49 // TODO(beng): remove once RootWindow is renamed.
50 typedef RootWindow WindowEventDispatcher;
52 // Defined in window_property.h (which we do not include)
54 struct WindowProperty;
60 // Aura window implementation. Interesting events are sent to the
62 // TODO(beng): resolve ownership.
63 class AURA_EXPORT Window : public ui::LayerDelegate,
64 public ui::LayerOwner,
65 public ui::EventTarget,
66 public ui::GestureConsumer {
68 typedef std::vector<Window*> Windows;
70 explicit Window(WindowDelegate* delegate);
73 // Initializes the window. This creates the window's layer.
74 void Init(ui::LayerType layer_type);
76 // Creates a new layer for the window. Erases the layer-owned bounds, so the
77 // caller may wish to set new bounds and other state on the window/layer.
78 // Returns the old layer, which can be used for animations. Caller owns the
79 // memory for the returned layer and must delete it when animation completes.
80 // Returns NULL and does not recreate layer if window does not own its layer.
81 ui::Layer* RecreateLayer() WARN_UNUSED_RESULT;
83 void set_owned_by_parent(bool owned_by_parent) {
84 owned_by_parent_ = owned_by_parent;
86 bool owned_by_parent() const { return owned_by_parent_; }
88 // A type is used to identify a class of Windows and customize behavior such
89 // as event handling and parenting. This field should only be consumed by the
90 // shell -- Aura itself shouldn't contain type-specific logic.
91 client::WindowType type() const { return type_; }
92 void SetType(client::WindowType type);
94 int id() const { return id_; }
95 void set_id(int id) { id_ = id; }
97 const std::string& name() const { return name_; }
98 void SetName(const std::string& name);
100 const base::string16 title() const { return title_; }
101 void set_title(const base::string16& title) { title_ = title; }
103 bool transparent() const { return transparent_; }
104 void SetTransparent(bool transparent);
106 WindowDelegate* delegate() { return delegate_; }
107 const WindowDelegate* delegate() const { return delegate_; }
109 const gfx::Rect& bounds() const;
111 Window* parent() { return parent_; }
112 const Window* parent() const { return parent_; }
114 // Returns the root Window that contains this Window. The root Window is
115 // defined as the Window that has a dispatcher. These functions return NULL if
116 // the Window is contained in a hierarchy that does not have a dispatcher at
118 virtual Window* GetRootWindow();
119 virtual const Window* GetRootWindow() const;
121 WindowEventDispatcher* GetDispatcher();
122 const WindowEventDispatcher* GetDispatcher() const;
123 void set_dispatcher(WindowEventDispatcher* dispatcher) {
124 dispatcher_ = dispatcher;
126 bool HasDispatcher() const { return !!dispatcher_; }
128 // The Window does not own this object.
129 void set_user_data(void* user_data) { user_data_ = user_data; }
130 void* user_data() const { return user_data_; }
132 // Changes the visibility of the window.
135 // Returns true if this window and all its ancestors are visible.
136 bool IsVisible() const;
137 // Returns the visibility requested by this window. IsVisible() takes into
138 // account the visibility of the layer and ancestors, where as this tracks
139 // whether Show() without a Hide() has been invoked.
140 bool TargetVisibility() const { return visible_; }
142 // Returns the window's bounds in root window's coordinates.
143 gfx::Rect GetBoundsInRootWindow() const;
145 // Returns the window's bounds in screen coordinates.
146 // How the root window's coordinates is mapped to screen's coordinates
147 // is platform dependent and defined in the implementation of the
148 // |aura::client::ScreenPositionClient| interface.
149 gfx::Rect GetBoundsInScreen() const;
151 virtual void SetTransform(const gfx::Transform& transform);
153 // Assigns a LayoutManager to size and place child windows.
154 // The Window takes ownership of the LayoutManager.
155 void SetLayoutManager(LayoutManager* layout_manager);
156 LayoutManager* layout_manager() { return layout_manager_.get(); }
158 // Changes the bounds of the window. If present, the window's parent's
159 // LayoutManager may adjust the bounds.
160 void SetBounds(const gfx::Rect& new_bounds);
162 // Changes the bounds of the window in the screen coordintates.
163 // If present, the window's parent's LayoutManager may adjust the bounds.
164 void SetBoundsInScreen(const gfx::Rect& new_bounds_in_screen_coords,
165 const gfx::Display& dst_display);
167 // Returns the target bounds of the window. If the window's layer is
168 // not animating, it simply returns the current bounds.
169 gfx::Rect GetTargetBounds() const;
171 // Marks the a portion of window as needing to be painted.
172 void SchedulePaintInRect(const gfx::Rect& rect);
174 // Stacks the specified child of this Window at the front of the z-order.
175 void StackChildAtTop(Window* child);
177 // Stacks |child| above |target|. Does nothing if |child| is already above
178 // |target|. Does not stack on top of windows with NULL layer delegates,
179 // see WindowTest.StackingMadrigal for details.
180 void StackChildAbove(Window* child, Window* target);
182 // Stacks the specified child of this window at the bottom of the z-order.
183 void StackChildAtBottom(Window* child);
185 // Stacks |child| below |target|. Does nothing if |child| is already below
187 void StackChildBelow(Window* child, Window* target);
190 void AddChild(Window* child);
191 void RemoveChild(Window* child);
193 const Windows& children() const { return children_; }
195 // Returns true if this Window contains |other| somewhere in its children.
196 bool Contains(const Window* other) const;
198 // Adds or removes |child| as a transient child of this window. Transient
199 // children get the following behavior:
200 // . The transient parent destroys any transient children when it is
201 // destroyed. This means a transient child is destroyed if either its parent
202 // or transient parent is destroyed.
203 // . If a transient child and its transient parent share the same parent, then
204 // transient children are always ordered above the transient parent.
205 // Transient windows are typically used for popups and menus.
206 void AddTransientChild(Window* child);
207 void RemoveTransientChild(Window* child);
209 const Windows& transient_children() const { return transient_children_; }
211 Window* transient_parent() { return transient_parent_; }
212 const Window* transient_parent() const { return transient_parent_; }
214 // Retrieves the first-level child with the specified id, or NULL if no first-
215 // level child is found matching |id|.
216 Window* GetChildById(int id);
217 const Window* GetChildById(int id) const;
219 // Converts |point| from |source|'s coordinates to |target|'s. If |source| is
220 // NULL, the function returns without modifying |point|. |target| cannot be
222 static void ConvertPointToTarget(const Window* source,
223 const Window* target,
226 // Moves the cursor to the specified location relative to the window.
227 virtual void MoveCursorTo(const gfx::Point& point_in_window);
229 // Returns the cursor for the specified point, in window coordinates.
230 gfx::NativeCursor GetCursor(const gfx::Point& point) const;
232 // Sets an 'event filter' for the window. An 'event filter' for a Window is
233 // a pre-target event handler, where the window owns the handler. A window
234 // can have only one such event filter. Setting a new filter removes and
235 // destroys any previously installed filter.
236 void SetEventFilter(ui::EventHandler* event_filter);
238 // Add/remove observer.
239 void AddObserver(WindowObserver* observer);
240 void RemoveObserver(WindowObserver* observer);
241 bool HasObserver(WindowObserver* observer);
243 void set_ignore_events(bool ignore_events) { ignore_events_ = ignore_events; }
245 // Sets the window to grab hits for mouse and touch to an area extending
246 // -|mouse_insets| and -|touch_insets| pixels outside its bounds. This can be
247 // used to create an invisible non-client area, for example if your windows
248 // have no visible frames but still need to have resize edges.
249 void SetHitTestBoundsOverrideOuter(const gfx::Insets& mouse_insets,
250 const gfx::Insets& touch_insets) {
251 hit_test_bounds_override_outer_mouse_ = mouse_insets;
252 hit_test_bounds_override_outer_touch_ = touch_insets;
255 gfx::Insets hit_test_bounds_override_outer_touch() const {
256 return hit_test_bounds_override_outer_touch_;
259 gfx::Insets hit_test_bounds_override_outer_mouse() const {
260 return hit_test_bounds_override_outer_mouse_;
263 // Sets the window to grab hits for an area extending |insets| pixels inside
264 // its bounds (even if that inner region overlaps a child window). This can be
265 // used to create an invisible non-client area that overlaps the client area.
266 void set_hit_test_bounds_override_inner(const gfx::Insets& insets) {
267 hit_test_bounds_override_inner_ = insets;
269 gfx::Insets hit_test_bounds_override_inner() const {
270 return hit_test_bounds_override_inner_;
273 // Returns true if the |point_in_root| in root window's coordinate falls
274 // within this window's bounds. Returns false if the window is detached
276 bool ContainsPointInRoot(const gfx::Point& point_in_root) const;
278 // Returns true if relative-to-this-Window's-origin |local_point| falls
279 // within this Window's bounds.
280 bool ContainsPoint(const gfx::Point& local_point) const;
282 // Returns true if the mouse pointer at relative-to-this-Window's-origin
283 // |local_point| can trigger an event for this Window.
284 // TODO(beng): A Window can supply a hit-test mask to cause some portions of
285 // itself to not trigger events, causing the events to fall through to the
287 bool HitTest(const gfx::Point& local_point);
289 // Returns the Window that most closely encloses |local_point| for the
290 // purposes of event targeting.
291 Window* GetEventHandlerForPoint(const gfx::Point& local_point);
293 // Returns the topmost Window with a delegate containing |local_point|.
294 Window* GetTopWindowContainingPoint(const gfx::Point& local_point);
296 // Returns this window's toplevel window (the highest-up-the-tree anscestor
297 // that has a delegate set). The toplevel window may be |this|.
298 Window* GetToplevelWindow();
300 // Claims or relinquishes the claim to focus.
304 // Returns true if the Window is currently the focused window.
305 bool HasFocus() const;
307 // Returns true if the Window can be focused.
308 virtual bool CanFocus() const;
310 // Returns true if the Window can receive events.
311 virtual bool CanReceiveEvents() const;
313 // Does a capture on the window. This does nothing if the window isn't showing
314 // (VISIBILITY_SHOWN) or isn't contained in a valid window hierarchy.
317 // Releases a capture.
318 void ReleaseCapture();
320 // Returns true if this window has capture.
323 // Suppresses painting window content by disgarding damaged rect and ignoring
324 // new paint requests.
325 void SuppressPaint();
327 // Sets the |value| of the given window |property|. Setting to the default
328 // value (e.g., NULL) removes the property. The caller is responsible for the
329 // lifetime of any object set as a property on the Window.
331 void SetProperty(const WindowProperty<T>* property, T value);
333 // Returns the value of the given window |property|. Returns the
334 // property-specific default value if the property was not previously set.
336 T GetProperty(const WindowProperty<T>* property) const;
338 // Sets the |property| to its default value. Useful for avoiding a cast when
341 void ClearProperty(const WindowProperty<T>* property);
343 // NativeWidget::[GS]etNativeWindowProperty use strings as keys, and this is
344 // difficult to change while retaining compatibility with other platforms.
345 // TODO(benrg): Find a better solution.
346 void SetNativeWindowProperty(const char* key, void* value);
347 void* GetNativeWindowProperty(const char* key) const;
349 // Type of a function to delete a property that this window owns.
350 typedef void (*PropertyDeallocator)(int64 value);
352 // Overridden from ui::LayerDelegate:
353 virtual void OnDeviceScaleFactorChanged(float device_scale_factor) OVERRIDE;
356 // These methods are useful when debugging.
357 std::string GetDebugInfo() const;
358 void PrintWindowHierarchy(int depth) const;
362 // Deletes (or removes if not owned by parent) all child windows. Intended for
363 // use from the destructor.
364 void RemoveOrDestroyChildren();
367 friend class test::WindowTestApi;
368 friend class LayoutManager;
370 // Used when stacking windows.
371 enum StackDirection {
376 // Called by the public {Set,Get,Clear}Property functions.
377 int64 SetPropertyInternal(const void* key,
379 PropertyDeallocator deallocator,
381 int64 default_value);
382 int64 GetPropertyInternal(const void* key, int64 default_value) const;
384 // Changes the bounds of the window without condition.
385 void SetBoundsInternal(const gfx::Rect& new_bounds);
387 // Updates the visible state of the layer, but does not make visible-state
388 // specific changes. Called from Show()/Hide().
389 void SetVisible(bool visible);
391 // Schedules a paint for the Window's entire bounds.
392 void SchedulePaint();
394 // Gets a Window (either this one or a subwindow) containing |local_point|.
395 // If |return_tightest| is true, returns the tightest-containing (i.e.
396 // furthest down the hierarchy) Window containing the point; otherwise,
397 // returns the loosest. If |for_event_handling| is true, then hit-test masks
398 // are honored; otherwise, only bounds checks are performed.
399 Window* GetWindowForPoint(const gfx::Point& local_point,
400 bool return_tightest,
401 bool for_event_handling);
403 // Implementation of RemoveChild(). If |child| is being removed as the result
404 // of an add, |new_parent| is the new parent |child| is going to be parented
406 void RemoveChildImpl(Window* child, Window* new_parent);
408 // Called when this window's parent has changed.
409 void OnParentChanged();
411 // Populates |ancestors| with all transient ancestors of |window| that are
412 // children of |this|. Returns true if any ancestors were found, false if not.
413 bool GetAllTransientAncestors(Window* window, Windows* ancestors) const;
415 // Replaces two windows |window1| and |window2| with their possible transient
416 // ancestors that are still siblings (have a common transient parent).
417 // |window1| and |window2| are not modified if such ancestors cannot be found.
418 void FindCommonSiblings(Window** window1, Window** window2) const;
420 // Returns true when |ancestor| is a transient ancestor of |this|.
421 bool HasTransientAncestor(const Window* ancestor) const;
423 // Determines the real location for stacking |child| and invokes
424 // StackChildRelativeToImpl().
425 void StackChildRelativeTo(Window* child,
427 StackDirection direction);
429 // Implementation of StackChildRelativeTo().
430 void StackChildRelativeToImpl(Window* child,
432 StackDirection direction);
434 // Called when this window's stacking order among its siblings is changed.
435 void OnStackingChanged();
437 // Notifies observers registered with this Window (and its subtree) when the
438 // Window has been added or is about to be removed from a RootWindow.
439 void NotifyRemovingFromRootWindow();
440 void NotifyAddedToRootWindow();
442 // Methods implementing hierarchy change notifications. See WindowObserver for
444 void NotifyWindowHierarchyChange(
445 const WindowObserver::HierarchyChangeParams& params);
446 // Notifies this window and its child hierarchy.
447 void NotifyWindowHierarchyChangeDown(
448 const WindowObserver::HierarchyChangeParams& params);
449 // Notifies this window and its parent hierarchy.
450 void NotifyWindowHierarchyChangeUp(
451 const WindowObserver::HierarchyChangeParams& params);
452 // Notifies this window's observers.
453 void NotifyWindowHierarchyChangeAtReceiver(
454 const WindowObserver::HierarchyChangeParams& params);
456 // Methods implementing visibility change notifications. See WindowObserver
458 void NotifyWindowVisibilityChanged(aura::Window* target, bool visible);
459 // Notifies this window's observers. Returns false if |this| was deleted
460 // during the call (by an observer), otherwise true.
461 bool NotifyWindowVisibilityChangedAtReceiver(aura::Window* target,
463 // Notifies this window and its child hierarchy. Returns false if
464 // |this| was deleted during the call (by an observer), otherwise
466 bool NotifyWindowVisibilityChangedDown(aura::Window* target, bool visible);
467 // Notifies this window and its parent hierarchy.
468 void NotifyWindowVisibilityChangedUp(aura::Window* target, bool visible);
470 // Invoked from the closure returned by PrepareForLayerBoundsChange() after
471 // the bounds of the layer has changed. |old_bounds| is the previous bounds of
472 // the layer, and |contained_mouse| is true if the mouse was previously within
473 // the window's bounds.
474 void OnLayerBoundsChanged(const gfx::Rect& old_bounds, bool contained_mouse);
476 // Overridden from ui::LayerDelegate:
477 virtual void OnPaintLayer(gfx::Canvas* canvas) OVERRIDE;
478 virtual base::Closure PrepareForLayerBoundsChange() OVERRIDE;
480 // Overridden from ui::EventTarget:
481 virtual bool CanAcceptEvent(const ui::Event& event) OVERRIDE;
482 virtual EventTarget* GetParentTarget() OVERRIDE;
484 // Updates the layer name with a name based on the window's name and id.
485 void UpdateLayerName(const std::string& name);
487 // Returns true if the mouse is currently within our bounds.
488 bool ContainsMouse();
490 WindowEventDispatcher* dispatcher_;
492 client::WindowType type_;
494 // True if the Window is owned by its parent - i.e. it will be deleted by its
495 // parent during its parents destruction. True is the default.
496 bool owned_by_parent_;
498 WindowDelegate* delegate_;
500 // The Window's parent.
503 // Child windows. Topmost is last.
506 // Transient windows.
507 Windows transient_children_;
509 Window* transient_parent_;
511 // The visibility state of the window as set by Show()/Hide(). This may differ
512 // from the visibility of the underlying layer, which may remain visible after
513 // the window is hidden (e.g. to animate its disappearance).
519 base::string16 title_;
521 // Whether layer is initialized as non-opaque.
524 scoped_ptr<ui::EventHandler> event_filter_;
525 scoped_ptr<LayoutManager> layout_manager_;
529 // Makes the window pass all events through to any windows behind it.
532 // See set_hit_test_outer_override().
533 gfx::Insets hit_test_bounds_override_outer_mouse_;
534 gfx::Insets hit_test_bounds_override_outer_touch_;
535 gfx::Insets hit_test_bounds_override_inner_;
537 ObserverList<WindowObserver> observers_;
539 // Value struct to keep the name and deallocator for this property.
540 // Key cannot be used for this purpose because it can be char* or
545 PropertyDeallocator deallocator;
548 std::map<const void*, Value> prop_map_;
550 DISALLOW_COPY_AND_ASSIGN(Window);
555 #endif // UI_AURA_WINDOW_H_