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_AURA_WINDOW_OBSERVER_H_
6#define UI_AURA_WINDOW_OBSERVER_H_
7
8#include "base/basictypes.h"
9#include "base/strings/string16.h"
10#include "ui/aura/aura_export.h"
11
12namespace gfx {
13class Rect;
14}  // namespace gfx
15
16namespace aura {
17
18class Window;
19
20class AURA_EXPORT WindowObserver {
21 public:
22  struct HierarchyChangeParams {
23    enum HierarchyChangePhase {
24      HIERARCHY_CHANGING,
25      HIERARCHY_CHANGED
26    };
27
28    Window* target;     // The window that was added or removed.
29    Window* new_parent;
30    Window* old_parent;
31    HierarchyChangePhase phase;
32    Window* receiver;   // The window receiving the notification.
33  };
34
35  WindowObserver();
36
37  // Called when a window is added or removed. Notifications are sent to the
38  // following hierarchies in this order:
39  // 1. |target|.
40  // 2. |target|'s child hierarchy.
41  // 3. |target|'s parent hierarchy in its |old_parent|
42  //        (only for Changing notifications).
43  // 3. |target|'s parent hierarchy in its |new_parent|.
44  //        (only for Changed notifications).
45  // This sequence is performed via the Changing and Changed notifications below
46  // before and after the change is committed.
47  virtual void OnWindowHierarchyChanging(const HierarchyChangeParams& params) {}
48  virtual void OnWindowHierarchyChanged(const HierarchyChangeParams& params) {}
49
50  // Invoked when |new_window| has been added as a child of this window.
51  virtual void OnWindowAdded(Window* new_window) {}
52
53  // Invoked prior to removing |window| as a child of this window.
54  virtual void OnWillRemoveWindow(Window* window) {}
55
56  // Invoked when this window's parent window changes.  |parent| may be NULL.
57  virtual void OnWindowParentChanged(Window* window, Window* parent) {}
58
59  // Invoked when SetProperty(), ClearProperty(), or
60  // NativeWidgetAura::SetNativeWindowProperty() is called on the window.
61  // |key| is either a WindowProperty<T>* (SetProperty, ClearProperty)
62  // or a const char* (SetNativeWindowProperty). Either way, it can simply be
63  // compared for equality with the property constant. |old| is the old property
64  // value, which must be cast to the appropriate type before use.
65  virtual void OnWindowPropertyChanged(Window* window,
66                                       const void* key,
67                                       intptr_t old) {}
68
69  // Invoked when SetVisible() is invoked on a window. |visible| is the
70  // value supplied to SetVisible(). If |visible| is true, window->IsVisible()
71  // may still return false. See description in Window::IsVisible() for details.
72  virtual void OnWindowVisibilityChanging(Window* window, bool visible) {}
73  virtual void OnWindowVisibilityChanged(Window* window, bool visible) {}
74
75  // Invoked when SetBounds() is invoked on |window|. |old_bounds| and
76  // |new_bounds| are in parent coordinates.
77  virtual void OnWindowBoundsChanged(Window* window,
78                                     const gfx::Rect& old_bounds,
79                                     const gfx::Rect& new_bounds) {}
80
81  // Invoked when SetTransform() is invoked on |window|.
82  virtual void OnWindowTransforming(Window* window) {}
83  virtual void OnWindowTransformed(Window* window) {}
84
85  // Invoked when SetTransform() is invoked on an ancestor of the window being
86  // observed (including the window itself).
87  virtual void OnAncestorWindowTransformed(Window* source, Window* window) {}
88
89  // Invoked when |window|'s position among its siblings in the stacking order
90  // has changed.
91  virtual void OnWindowStackingChanged(Window* window) {}
92
93  // Invoked when a region of |window| has damage from a new delegated frame.
94  virtual void OnDelegatedFrameDamage(Window* window,
95                                      const gfx::Rect& damage_rect_in_dip) {}
96
97  // Invoked when the Window is being destroyed (i.e. from the start of its
98  // destructor). This is called before the window is removed from its parent.
99  virtual void OnWindowDestroying(Window* window) {}
100
101  // Invoked when the Window has been destroyed (i.e. at the end of
102  // its destructor). This is called after the window is removed from
103  // its parent.  Window automatically removes its WindowObservers
104  // before calling this method, so the following code is no op.
105  //
106  // void MyWindowObserver::OnWindowDestroyed(aura::Window* window) {
107  //    window->RemoveObserver(this);
108  // }
109  virtual void OnWindowDestroyed(Window* window) {}
110
111  // Called when a Window has been added to a RootWindow.
112  virtual void OnWindowAddedToRootWindow(Window* window) {}
113
114  // Called when a Window is about to be removed from a root Window.
115  // |new_root| contains the new root Window if it is being added to one
116  // atomically.
117  virtual void OnWindowRemovingFromRootWindow(Window* window,
118                                              Window* new_root) {}
119
120  // Called when the window title has changed.
121  virtual void OnWindowTitleChanged(Window* window) {}
122
123 protected:
124  virtual ~WindowObserver();
125
126 private:
127  friend class Window;
128
129  // Called when this is added as an observer on |window|.
130  void OnObservingWindow(Window* window);
131
132  // Called when this is removed from the observers on |window|.
133  void OnUnobservingWindow(Window* window);
134
135  // Tracks the number of windows being observed to track down
136  // http://crbug.com/365364.
137  int observing_;
138
139  DISALLOW_COPY_AND_ASSIGN(WindowObserver);
140};
141
142}  // namespace aura
143
144#endif  // UI_AURA_WINDOW_OBSERVER_H_
145