* Changes in the autotools stuff affecting a lot of platform dependent
[modest] / src / widgets / modest-window-mgr.h
1 /* Copyright (c) 2006,2007 Nokia Corporation
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  * * Redistributions of source code must retain the above copyright
9  *   notice, this list of conditions and the following disclaimer.
10  * * Redistributions in binary form must reproduce the above copyright
11  *   notice, this list of conditions and the following disclaimer in the
12  *   documentation and/or other materials provided with the distribution.
13  * * Neither the name of the Nokia Corporation nor the names of its
14  *   contributors may be used to endorse or promote products derived from
15  *   this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
18  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
20  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
21  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
24  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
25  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
26  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30 #ifndef __MODEST_WINDOW_MGR_H__
31 #define __MODEST_WINDOW_MGR_H__
32
33 #include <glib-object.h>
34 #include "widgets/modest-msg-view-window.h"
35
36 G_BEGIN_DECLS
37
38 /* convenience macros */
39 #define MODEST_TYPE_WINDOW_MGR             (modest_window_mgr_get_type())
40 #define MODEST_WINDOW_MGR(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),MODEST_TYPE_WINDOW_MGR,ModestWindowMgr))
41 #define MODEST_WINDOW_MGR_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),MODEST_TYPE_WINDOW_MGR,GObject))
42 #define MODEST_IS_WINDOW_MGR(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),MODEST_TYPE_WINDOW_MGR))
43 #define MODEST_IS_WINDOW_MGR_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),MODEST_TYPE_WINDOW_MGR))
44 #define MODEST_WINDOW_MGR_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj),MODEST_TYPE_WINDOW_MGR,ModestWindowMgrClass))
45
46 typedef struct _ModestWindowMgr      ModestWindowMgr;
47 typedef struct _ModestWindowMgrClass ModestWindowMgrClass;
48
49 struct _ModestWindowMgr {
50          GObject parent;
51 };
52
53 struct _ModestWindowMgrClass {
54         GObjectClass parent_class;
55
56         /* Signals */
57         void (*window_list_empty) (ModestWindowMgr *self);
58 };
59
60
61 /* member functions */
62 GType        modest_window_mgr_get_type    (void) G_GNUC_CONST;
63
64 /* typical parameter-less _new function */
65 ModestWindowMgr*    modest_window_mgr_new         (void);
66
67
68 /**
69  * modest_window_mgr_register_window:
70  * @self: the #ModestWindowMgr
71  * @window: a #ModestWindow
72  * 
73  * Registers a new window in the window manager. The window manager
74  * will keep a reference.
75  **/
76 void           modest_window_mgr_register_window       (ModestWindowMgr *self, 
77                                                         ModestWindow *window);
78
79 /**
80  * modest_window_mgr_unregister_window:
81  * @self: the #ModestWindowMgr
82  * @window: a #ModestWindow
83  * 
84  * Unregisters a given window from the window manager. The window
85  * manager will free its reference to it.
86  **/
87 void           modest_window_mgr_unregister_window     (ModestWindowMgr *self, 
88                                                         ModestWindow *window);
89
90 /**
91  * modest_window_mgr_register_banner:
92  * @self: a #ModestWindowMgr
93  *
94  * Increase the count of pending banners in the window manager
95  */
96 void           modest_window_mgr_register_banner (ModestWindowMgr *self);
97
98 /**
99  * modest_window_mgr_unregister_banner:
100  * @self: a #ModestWindowMgr
101  *
102  * Decrease the count of pending banners in the window manager
103  */
104 void           modest_window_mgr_unregister_banner (ModestWindowMgr *self);
105
106 /**
107  * modest_window_mgr_set_fullscreen_mode:
108  * @self: a #ModestWindowMgr
109  * @on: a #gboolean
110  * 
111  * sets/unsets the application windows in fullscreen mode
112  **/
113 void           modest_window_mgr_set_fullscreen_mode   (ModestWindowMgr *self,
114                                                         gboolean on);
115
116 /**
117  * modest_window_mgr_get_fullscreen_mode:
118  * @self: a #ModestWindowMgr
119  * 
120  * gets the application current fullscreen mode
121  *
122  * Return value: TRUE is the application is in fullscrenn mode,
123  * otherwise FALSE
124  **/
125 gboolean       modest_window_mgr_get_fullscreen_mode   (ModestWindowMgr *self);
126
127
128 /**
129  * modest_window_mgr_show_toolbars:
130  * @self: a #ModestWindowMgr
131  * @window_type: apply the show toolbars command only to the windows of this type
132  * @show_toolbar: whether or not the toolbars should be shown
133  * @fullscreen: TRUE/FALSE for show/hide in fullscreen mode, otherwise
134  * it applies to normal mode
135  * 
136  * shows or hides the toolbars of the registered windows. Note that if
137  * the #fullscreen attribute is TRUE and the application is in normal
138  * mode, you will not see the changes until the application switches
139  * to fullscreen mode and viceversa
140  **/
141 void           modest_window_mgr_show_toolbars         (ModestWindowMgr *self,
142                                                         GType window_type,
143                                                         gboolean show_toolbars,
144                                                         gboolean fullscreen);
145 /**
146  * modest_window_mgr_get_main_window:
147  * @self: a #ModestWindowMgr
148  * @create: if TRUE, create the main window if it was not yet existing
149  *
150  * get the main window, and depending on @create, create one if it does not exist yet
151  *
152  * Returns: the main window or NULL in case of error, or the main-window
153  * did not yet exist
154  **/
155 ModestWindow*  modest_window_mgr_get_main_window       (ModestWindowMgr *self,
156                                                         gboolean create);
157
158
159 /**
160  * modest_window_mgr_main_window_exists:
161  * @self: a #ModestWindowMgr
162  *
163  * do we have a main window?
164  *
165  * Returns: TRUE if there's a main window, FALSE otherwise
166  **/
167 gboolean  modest_window_mgr_main_window_exists       (ModestWindowMgr *self);
168
169
170
171 /**
172  * modest_window_mgr_get_modal:
173  * @self: a #ModestWindowMgr
174  *
175  * get the modal window; if it's NULL, there's no active modal window
176  *
177  * Returns: the modal window or NULL
178  **/
179 GtkWindow*    modest_window_mgr_get_modal  (ModestWindowMgr *self);
180
181
182 /**
183  * modest_window_mgr_get_easysetup_dialog:
184  * @self: a #ModestWindowMgr
185  *
186  * set the modal dialog; set it to NULL after destroying the dialog
187  *
188  **/
189 void          modest_window_mgr_set_modal  (ModestWindowMgr *self,
190                                             GtkWindow *window);
191
192 /**
193  * modest_window_mgr_prevent_hibernation_while_window_is_shown:
194  * @self: a #ModestWindowMgr
195  * @window: The window that should prevent hibernation while it is shown.
196  * 
197  * Call this if hibernation should not be allowed because 
198  * windows are open whose state cannot sensible be saved, such as Account 
199  * Settings dialogs.
200  * This causes modest_window_mgr_get_hibernation_is_prevented() to return TRUE 
201  * until all such windows have been closed. That means, until the windows have 
202  * been hidden - window destruction or other memory management is not relevant.
203  **/
204 void modest_window_mgr_prevent_hibernation_while_window_is_shown (ModestWindowMgr *self, 
205         GtkWindow *window);
206
207
208
209 /**
210  * modest_window_mgr_register_help_id
211  * @self: a #ModestWindowMgr
212  * @win: some window
213  * @help_id: the help_id for this window
214  * 
215  * register a help id for a window
216  **/
217 void
218 modest_window_mgr_register_help_id (ModestWindowMgr *self, GtkWindow *win, const gchar* help_id);
219
220
221 /**
222  * modest_window_mgr_get_help_id:
223  * @self: a #ModestWindowMgr
224  * @win: some window
225  * 
226  * get the help id for a window; if the window is the main-window and some folder is
227  * selected, it will return the proper help_id for that
228  *
229  * Returns: a help _id
230  **/
231 const gchar*
232 modest_window_mgr_get_help_id (ModestWindowMgr *self, GtkWindow *win);
233
234
235
236 /**
237  * modest_window_mgr_find_registered_header
238  * @self: a #ModestWindowMgr
239  * @header: a valid #TnyHeader
240  * 
241  * search for the given uid in both the list of preregistered uids and in the window list;
242  * if it's available in the window list, fill the *win out-param
243  *
244  * returns TRUE if found, FALSE otherwise
245  **/
246 gboolean modest_window_mgr_find_registered_header (ModestWindowMgr *self,  TnyHeader *header,
247                                                ModestWindow **win);
248
249
250 /**
251  * modest_window_mgr_close_all_windows
252  * @self: a #ModestWindowMgr
253  * 
254  * Close all registered windows. 
255  **/
256 void modest_window_mgr_close_all_windows (ModestWindowMgr *self);
257
258 /**
259  * modest_window_mgr_register_header
260  * @self: a #ModestWindowMgr
261  * @header: a valid #TnyHeader
262  * @alt_uid: alternative uid in case @header does not provide one
263  * 
264  * register the uid, even before the window is created. thus, we know when
265  * some window creation might already be underway. the uid will automatically be
266  * removed when the window itself will registered
267  * 
268  **/
269 void  modest_window_mgr_register_header   (ModestWindowMgr *self,  TnyHeader *header, const gchar *alt_uid);
270         
271
272 /**
273  * modest_window_mgr_unregister_header
274  * @self: a #ModestWindowMgr
275  * @header: a valid #TnyHeader
276  * 
277  * unregister the uid. We could need to do that if there is any error
278  * retrieving a message. In that case the window will not be
279  * registered and thus the header will not be removed, so we must do
280  * it manually
281  **/
282 void  modest_window_mgr_unregister_header (ModestWindowMgr *self,  TnyHeader *header);
283
284 /**
285  * modest_window_mgr_get_hibernation_is_prevented:
286  * @self: a #ModestWindowMgr
287  * @result: Whether any windows are currently preventing hibernation.
288  * 
289  * Use this to discover whether hibernation should not be allowed because 
290  * windows are open whose state cannot sensible be saved, such as Account 
291  * Settings dialogs. This function will return true after someone has called 
292  * modest_window_mgr_prevent_hibernation_while_window_is_shown() and before 
293  * that window has been closed.
294  **/
295 gboolean modest_window_mgr_get_hibernation_is_prevented (ModestWindowMgr *self);
296
297 /**
298  * modest_window_mgr_save_state_for_all_windows:
299  * @self: a #ModestWindowMgr
300  * 
301  * Save any state for all windows. For instance, call this before allowing 
302  * application hibernation.
303  **/
304 void modest_window_mgr_save_state_for_all_windows (ModestWindowMgr *self);
305
306 /**
307  * modest_window_mgr_num_windows:
308  * @self: a #ModestWindowMgr
309  * 
310  * Gets the number of already registered windows, and pending banners
311  *
312  * Returns: the number of already registered windows, and pending banners
313  **/
314 gint modest_window_mgr_num_windows (ModestWindowMgr *self);
315
316 /**
317  * modest_window_mgr_get_msg_view_window:
318  * @self: a #ModestWindowMgr
319  *
320  * obtain a cached #ModestMsgViewWindow if available, or construct a new
321  * one.
322  *
323  * Returns: a #ModestMsgViewWindow
324  */
325 GtkWidget *   modest_window_mgr_get_msg_view_window (ModestWindowMgr *self);
326
327 /**
328  * modest_window_mgr_get_msg_edit_window:
329  * @self: a #ModestWindowMgr
330  *
331  * obtain a cached #ModestMsgEditWindow if available, or construct a new
332  * one.
333  *
334  * Returns: a #ModestMsgEditWindow
335  */
336 GtkWidget *   modest_window_mgr_get_msg_edit_window (ModestWindowMgr *self);
337         
338 G_END_DECLS
339
340 #endif /* __MODEST_WINDOW_MGR_H__ */
341