Mir
window_manager_tools.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2016-2020 Canonical Ltd.
3  *
4  * This program is free software: you can redistribute it and/or modify it
5  * under the terms of the GNU General Public License version 2 or 3 as
6  * published by the Free Software Foundation.
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11  * GNU General Public License for more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program. If not, see <http://www.gnu.org/licenses/>.
15  */
16 
17 #ifndef MIRAL_WINDOW_MANAGER_TOOLS_H
18 #define MIRAL_WINDOW_MANAGER_TOOLS_H
19 
20 #include "miral/application.h"
21 #include "window_info.h"
22 
23 #include <mir/geometry/displacement.h>
24 
25 #include <functional>
26 #include <memory>
27 
28 namespace mir
29 {
30 namespace scene { class Surface; }
31 }
32 
33 namespace miral
34 {
35 class Window;
36 struct WindowInfo;
37 struct ApplicationInfo;
39 class Zone;
40 
41 /**
42  * Workspace is intentionally opaque in the miral API. Its only purpose is to
43  * provide a shared_ptr which is used as an identifier.
44  *
45  * The MirAL implementation of workspaces only prescribes the following:
46  * o When child windows are created they are added to all(any) workspaces of parent
47  * o Focus changes will first try windows with a common workspace
48  * o Adding/removing windows to a workspace affects the whole ancestor/decendent tree
49  *
50  * The presentation of workspaces is left entirely to the policy
51  */
52 class Workspace;
53 
54 class WindowManagerToolsImplementation;
55 
56 /// Window management functions for querying and updating MirAL's model
58 {
59 public:
60  explicit WindowManagerTools(WindowManagerToolsImplementation* tools);
64 
65 /** @name Query & Update Model
66  * These functions assume that the BasicWindowManager data structures can be accessed freely.
67  * I.e. they should only be used by a thread that has called the WindowManagementPolicy methods
68  * (where any necessary locks are held) or via a invoke_under_lock() callback.
69  * @{ */
70 
71  /** count the applications
72  *
73  * @return number of applications
74  */
75  auto count_applications() const -> unsigned int;
76 
77  /** execute functor for each application
78  *
79  * @param functor the functor
80  */
81  void for_each_application(std::function<void(ApplicationInfo& info)> const& functor);
82 
83  /** find an application meeting the predicate
84  *
85  * @param predicate the predicate
86  * @return the application
87  */
88  auto find_application(std::function<bool(ApplicationInfo const& info)> const& predicate)
89  -> Application;
90 
91  /** retrieve metadata for an application
92  *
93  * @param session the application session
94  * @return the metadata
95  */
96  auto info_for(std::weak_ptr<mir::scene::Session> const& session) const -> ApplicationInfo&;
97 
98  /** retrieve metadata for a window
99  *
100  * @param surface the window surface
101  * @return the metadata
102  */
103  auto info_for(std::weak_ptr<mir::scene::Surface> const& surface) const -> WindowInfo&;
104 
105  /** retrieve metadata for a window
106  *
107  * @param window the window
108  * @return the metadata
109  */
110  auto info_for(Window const& window) const -> WindowInfo&;
111 
112  /** retrieve metadata for a persistent surface id
113  *
114  * @param id the persistent surface id
115  * @return the metadata
116  * @throw invalid_argument or runtime_error if the id is badly formatted/doesn't identify a current window
117  */
118  auto info_for_window_id(std::string const& id) const -> WindowInfo&;
119 
120  /** retrieve the persistent surface id for a window
121  *
122  * @param window the window
123  * @return the persistent surface id
124  */
125  auto id_for_window(Window const& window) const -> std::string;
126 
127  /// Send close request to the window
128  void ask_client_to_close(Window const& window);
129 
130  /// retrieve the active window
131  auto active_window() const -> Window;
132 
133  /** select a new active window based on the hint
134  *
135  * @param hint the hint
136  * @return the new active window
137  */
138  auto select_active_window(Window const& hint) -> Window;
139 
140  /// move the active window
141  void drag_active_window(mir::geometry::Displacement movement);
142 
143  /// move the window
144  void drag_window(Window const& window, mir::geometry::Displacement movement);
145 
146  /// make the next application active
148 
149  /// make the previous application active
150  /// \remark Since MirAL 2.5
152 
153  /// make the next surface active within the active application
155 
156  /// make the prev surface active within the active application
158 
159  /// Find the topmost window at the cursor
160  auto window_at(mir::geometry::Point cursor) const -> Window;
161 
162  /// Find the active output area
163  auto active_output() -> mir::geometry::Rectangle const;
164 
165  /// Find the active zone area
166  /// \remark Since MirAL 3.0
167  auto active_application_zone() const -> Zone;
168 
169  /// Raise window and all its children
170  void raise_tree(Window const& root);
171 
172  /** Start drag and drop. The handle will be passed to the client which can
173  * then use it to talk to the whatever service is being used to support drag
174  * and drop (e.g. on Ubuntu the content hub).
175  *
176  * @param window_info source window
177  * @param handle drag handle
178  */
179  void start_drag_and_drop(WindowInfo& window_info, std::vector<uint8_t> const& handle);
180 
181  /// End drag and drop
183 
184  /// Apply modifications to a window
185  void modify_window(WindowInfo& window_info, WindowSpecification const& modifications);
186 
187  /// Apply modifications to a window
188  void modify_window(Window const& window, WindowSpecification const& modifications);
189 
190  /// Set a default size and position to reflect state change
191  void place_and_size_for_state(WindowSpecification& modifications, WindowInfo const& window_info) const;
192 
193  /** Create a workspace.
194  * \remark the tools hold only a weak_ptr<> to the workspace - there is no need for an explicit "destroy".
195  * @return a shared_ptr owning the workspace
196  */
197  auto create_workspace() -> std::shared_ptr<Workspace>;
198 
199  /**
200  * Add the tree containing window to a workspace
201  * @param window the window
202  * @param workspace the workspace;
203  */
204  void add_tree_to_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace);
205 
206  /**
207  * Remove the tree containing window from a workspace
208  * @param window the window
209  * @param workspace the workspace;
210  */
211  void remove_tree_from_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace);
212 
213  /**
214  * Moves all the content from one workspace to another
215  * @param from_workspace the workspace to move the windows from;
216  * @param to_workspace the workspace to move the windows to;
217  */
219  std::shared_ptr<Workspace> const& to_workspace,
220  std::shared_ptr<Workspace> const& from_workspace);
221 
222  /**
223  * invoke callback with each workspace containing window
224  * \warning it is unsafe to add or remove windows from workspaces from the callback during enumeration
225  * @param window
226  * @param callback
227  */
229  Window const& window,
230  std::function<void(std::shared_ptr<Workspace> const& workspace)> const& callback);
231 
232  /**
233  * invoke callback with each window contained in workspace
234  * \warning it is unsafe to add or remove windows from workspaces from the callback during enumeration
235  * @param workspace
236  * @param callback
237  */
239  std::shared_ptr<Workspace> const& workspace,
240  std::function<void(Window const& window)> const& callback);
241 
242 /** @} */
243 
244  /** Multi-thread support
245  * Allows threads that don't hold a lock on the model to acquire one and call the "Update Model"
246  * member functions.
247  * This should NOT be used by a thread that has called the WindowManagementPolicy methods (and
248  * already holds the lock).
249  */
250  void invoke_under_lock(std::function<void()> const& callback);
251 
252 private:
253  WindowManagerToolsImplementation* tools;
254 };
255 }
256 
257 #endif //MIRAL_WINDOW_MANAGER_TOOLS_H

Copyright © 2012-2022 Canonical Ltd.
Generated on Tue Sep 13 03:20:30 UTC 2022
This documentation is licensed under the GPL version 2 or 3.