git.maemo.org Git - modest/blob - 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 "modest-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,ModestWindowMgrClass))
  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         /* Virtuals */
  57         gboolean              (*register_window)                (ModestWindowMgr *self,
  58                                                                  ModestWindow *window,
  59                                                                  ModestWindow *parent);
  60         void                  (*unregister_window)              (ModestWindowMgr *self,
  61                                                                  ModestWindow *window);
  62         void                  (*set_fullscreen_mode)            (ModestWindowMgr *self,
  63                                                                  gboolean on);
  64         gboolean              (*get_fullscreen_mode)            (ModestWindowMgr *self);
  65         void                  (*show_toolbars)                  (ModestWindowMgr *self,
  66                                                                  GType window_type,
  67                                                                  gboolean show_toolbars,
  68                                                                  gboolean fullscreen);
  69         ModestWindow *        (*get_main_window)                (ModestWindowMgr *self,
  70                                                                  gboolean show);
  71         gboolean              (*close_all_windows)              (ModestWindowMgr *self);
  72         GtkWindow *           (*get_modal)                      (ModestWindowMgr *self);
  73         void                  (*set_modal)                      (ModestWindowMgr *self,
  74                                                                  GtkWindow *window,
  75                                                                  GtkWindow *parent);
  76         gboolean              (*find_registered_header)         (ModestWindowMgr *self,
  77                                                                  TnyHeader *header,
  78                                                                  ModestWindow **win);
  79         gboolean              (*find_registered_message_uid)    (ModestWindowMgr *self,
  80                                                                  const gchar *msg_uid,
  81                                                                  ModestWindow **win);
  82         GList *               (*get_window_list)                (ModestWindowMgr *self);
  83         ModestWindow *        (*show_initial_window)            (ModestWindowMgr *self);
  84         ModestWindow *        (*get_current_top)                (ModestWindowMgr *self);
  85         gboolean              (*close_all_but_initial)          (ModestWindowMgr *self);
  86
  87         gboolean              (*screen_is_on)                   (ModestWindowMgr *self);
  88         void                  (*create_caches)                  (ModestWindowMgr *self);
  89
  90         /* Signals */
  91         void (*window_list_empty) (ModestWindowMgr *self);
  92         void (*progress_list_changed) (ModestWindowMgr *self);
  93 };
  94
  95
  96 /* member functions */
  97 GType        modest_window_mgr_get_type    (void) G_GNUC_CONST;
  98
  99 /* typical parameter-less _new function */
 100 ModestWindowMgr*    modest_window_mgr_new         (void);
 101
 102
 103 /**
 104  * modest_window_mgr_register_window:
 105  * @self: the #ModestWindowMgr
 106  * @window: a #ModestWindow
 107  *
 108  * Registers a new window in the window manager. The window manager
 109  * will keep a reference.
 110  **/
 111 gboolean           modest_window_mgr_register_window       (ModestWindowMgr *self,
 112                                                             ModestWindow *window,
 113                                                             ModestWindow *parent);
 114
 115 /**
 116  * modest_window_mgr_unregister_window:
 117  * @self: the #ModestWindowMgr
 118  * @window: a #ModestWindow
 119  *
 120  * Unregisters a given window from the window manager. The window
 121  * manager will free its reference to it.
 122  **/
 123 void           modest_window_mgr_unregister_window     (ModestWindowMgr *self,
 124                                                         ModestWindow *window);
 125
 126 /**
 127  * modest_window_mgr_register_banner:
 128  * @self: a #ModestWindowMgr
 129  *
 130  * Increase the count of pending banners in the window manager
 131  */
 132 void           modest_window_mgr_register_banner (ModestWindowMgr *self);
 133
 134 /**
 135  * modest_window_mgr_unregister_banner:
 136  * @self: a #ModestWindowMgr
 137  *
 138  * Decrease the count of pending banners in the window manager
 139  */
 140 void           modest_window_mgr_unregister_banner (ModestWindowMgr *self);
 141
 142 /**
 143  * modest_window_mgr_set_fullscreen_mode:
 144  * @self: a #ModestWindowMgr
 145  * @on: a #gboolean
 146  *
 147  * sets/unsets the application windows in fullscreen mode
 148  **/
 149 void           modest_window_mgr_set_fullscreen_mode   (ModestWindowMgr *self,
 150                                                         gboolean on);
 151
 152 /**
 153  * modest_window_mgr_get_fullscreen_mode:
 154  * @self: a #ModestWindowMgr
 155  *
 156  * gets the application current fullscreen mode
 157  *
 158  * Return value: TRUE is the application is in fullscrenn mode,
 159  * otherwise FALSE
 160  **/
 161 gboolean       modest_window_mgr_get_fullscreen_mode   (ModestWindowMgr *self);
 162
 163
 164 /**
 165  * modest_window_mgr_show_toolbars:
 166  * @self: a #ModestWindowMgr
 167  * @window_type: apply the show toolbars command only to the windows of this type
 168  * @show_toolbar: whether or not the toolbars should be shown
 169  * @fullscreen: TRUE/FALSE for show/hide in fullscreen mode, otherwise
 170  * it applies to normal mode
 171  *
 172  * shows or hides the toolbars of the registered windows. Note that if
 173  * the #fullscreen attribute is TRUE and the application is in normal
 174  * mode, you will not see the changes until the application switches
 175  * to fullscreen mode and viceversa
 176  **/
 177 void           modest_window_mgr_show_toolbars         (ModestWindowMgr *self,
 178                                                         GType window_type,
 179                                                         gboolean show_toolbars,
 180                                                         gboolean fullscreen);
 181 /**
 182  * modest_window_mgr_get_main_window:
 183  * @self: a #ModestWindowMgr
 184  * @show: if TRUE, create the main window and show it if it was not existing.
 185  *
 186  * get the main window, and depending on @create, create one if it does not exist yet
 187  *
 188  * Returns: the main window or NULL in case of error, or the main-window
 189  * did not yet exist
 190  **/
 191 ModestWindow*  modest_window_mgr_get_main_window       (ModestWindowMgr *self,
 192                                                         gboolean show);
 193
 194 /**
 195  * modest_window_mgr_set_main_window:
 196  * @self: a #ModestWindowMgr
 197  * @main_win: a #ModestMainWindow
 198  */
 199 void modest_window_mgr_set_main_window (ModestWindowMgr *self, ModestWindow *main_win);
 200
 201
 202 /**
 203  * modest_window_mgr_main_window_exists:
 204  * @self: a #ModestWindowMgr
 205  *
 206  * do we have a main window?
 207  *
 208  * Returns: TRUE if there's a main window, FALSE otherwise
 209  **/
 210 gboolean  modest_window_mgr_main_window_exists       (ModestWindowMgr *self);
 211
 212
 213
 214 /**
 215  * modest_window_mgr_get_modal:
 216  * @self: a #ModestWindowMgr
 217  *
 218  * get the modal window; if it's NULL, there's no active modal window
 219  *
 220  * Returns: the modal window or NULL
 221  **/
 222 GtkWindow*    modest_window_mgr_get_modal  (ModestWindowMgr *self);
 223
 224
 225 /**
 226  * modest_window_mgr_get_easysetup_dialog:
 227  * @self: a #ModestWindowMgr
 228  *
 229  * set the modal dialog; set it to NULL after destroying the dialog
 230  *
 231  **/
 232 void          modest_window_mgr_set_modal  (ModestWindowMgr *self,
 233                                             GtkWindow *window,
 234                                             GtkWindow *parent);
 235
 236 /**
 237  * modest_window_mgr_prevent_hibernation_while_window_is_shown:
 238  * @self: a #ModestWindowMgr
 239  * @window: The window that should prevent hibernation while it is shown.
 240  *
 241  * Call this if hibernation should not be allowed because
 242  * windows are open whose state cannot sensible be saved, such as Account
 243  * Settings dialogs.
 244  * This causes modest_window_mgr_get_hibernation_is_prevented() to return TRUE
 245  * until all such windows have been closed. That means, until the windows have
 246  * been hidden - window destruction or other memory management is not relevant.
 247  **/
 248 void modest_window_mgr_prevent_hibernation_while_window_is_shown (ModestWindowMgr *self,
 249         GtkWindow *window);
 250
 251
 252
 253 /**
 254  * modest_window_mgr_register_help_id
 255  * @self: a #ModestWindowMgr
 256  * @win: some window
 257  * @help_id: the help_id for this window
 258  *
 259  * register a help id for a window
 260  **/
 261 void
 262 modest_window_mgr_register_help_id (ModestWindowMgr *self, GtkWindow *win, const gchar* help_id);
 263
 264
 265 /**
 266  * modest_window_mgr_get_help_id:
 267  * @self: a #ModestWindowMgr
 268  * @win: some window
 269  *
 270  * get the help id for a window; if the window is the main-window and some folder is
 271  * selected, it will return the proper help_id for that
 272  *
 273  * Returns: a help _id
 274  **/
 275 const gchar*
 276 modest_window_mgr_get_help_id (ModestWindowMgr *self, GtkWindow *win);
 277
 278
 279
 280 /**
 281  * modest_window_mgr_find_registered_header
 282  * @self: a #ModestWindowMgr
 283  * @header: a valid #TnyHeader
 284  *
 285  * search for the given uid in both the list of preregistered uids and in the window list;
 286  * if it's available in the window list, fill the *win out-param
 287  *
 288  * returns TRUE if found, FALSE otherwise
 289  **/
 290 gboolean modest_window_mgr_find_registered_header (ModestWindowMgr *self,  TnyHeader *header,
 291                                                ModestWindow **win);
 292
 293
 294 /**
 295  * modest_window_mgr_find_registered_header
 296  * @self: a #ModestWindowMgr
 297  * @msg_uid: a message uid
 298  *
 299  * search for the given uid in both the list of preregistered uids and in the window list;
 300  * if it's available in the window list, fill the *win out-param
 301  *
 302  * returns TRUE if found, FALSE otherwise
 303  **/
 304 gboolean modest_window_mgr_find_registered_message_uid (ModestWindowMgr *self,  const gchar *msg_uid,
 305                                                         ModestWindow **win);
 306
 307 /**
 308  * modest_window_mgr_get_window_list:
 309  * @self: a #ModestWindowMgr
 310  *
 311  * get the list of windows registered in window mgr.
 312  *
 313  * Returns: a #GList, that caller should free
 314  */
 315 GList *modest_window_mgr_get_window_list (ModestWindowMgr *self);
 316
 317 /**
 318  * modest_window_mgr_close_all_windows
 319  * @self: a #ModestWindowMgr
 320  *
 321  * Close all registered windows. If failed (for example because
 322  * one confirmation dialog rejected the operation), return %FALSE
 323  **/
 324 gboolean modest_window_mgr_close_all_windows (ModestWindowMgr *self);
 325
 326 /**
 327  * modest_window_mgr_register_header
 328  * @self: a #ModestWindowMgr
 329  * @header: a valid #TnyHeader
 330  * @alt_uid: alternative uid in case @header does not provide one
 331  *
 332  * register the uid, even before the window is created. thus, we know when
 333  * some window creation might already be underway. the uid will automatically be
 334  * removed when the window itself will registered
 335  *
 336  **/
 337 void  modest_window_mgr_register_header   (ModestWindowMgr *self,  TnyHeader *header, const gchar *alt_uid);
 338
 339
 340 /**
 341  * modest_window_mgr_unregister_header
 342  * @self: a #ModestWindowMgr
 343  * @header: a valid #TnyHeader
 344  *
 345  * unregister the uid. We could need to do that if there is any error
 346  * retrieving a message. In that case the window will not be
 347  * registered and thus the header will not be removed, so we must do
 348  * it manually
 349  **/
 350 void  modest_window_mgr_unregister_header (ModestWindowMgr *self,  TnyHeader *header);
 351
 352 /**
 353  * modest_window_mgr_get_hibernation_is_prevented:
 354  * @self: a #ModestWindowMgr
 355  * @result: Whether any windows are currently preventing hibernation.
 356  *
 357  * Use this to discover whether hibernation should not be allowed because
 358  * windows are open whose state cannot sensible be saved, such as Account
 359  * Settings dialogs. This function will return true after someone has called
 360  * modest_window_mgr_prevent_hibernation_while_window_is_shown() and before
 361  * that window has been closed.
 362  **/
 363 gboolean modest_window_mgr_get_hibernation_is_prevented (ModestWindowMgr *self);
 364
 365 /**
 366  * modest_window_mgr_save_state_for_all_windows:
 367  * @self: a #ModestWindowMgr
 368  *
 369  * Save any state for all windows. For instance, call this before allowing
 370  * application hibernation.
 371  **/
 372 void modest_window_mgr_save_state_for_all_windows (ModestWindowMgr *self);
 373
 374 /**
 375  * modest_window_mgr_get_num_windows:
 376  * @self: a #ModestWindowMgr
 377  *
 378  * Gets the number of already registered windows, and pending banners
 379  *
 380  * Returns: the number of already registered windows, and pending banners
 381  **/
 382 guint modest_window_mgr_get_num_windows (ModestWindowMgr *self);
 383
 384 /**
 385  * modest_window_mgr_get_msg_view_window:
 386  * @self: a #ModestWindowMgr
 387  *
 388  * obtain a cached #ModestMsgViewWindow if available, or construct a new
 389  * one.
 390  *
 391  * Returns: a #ModestMsgViewWindow
 392  */
 393 GtkWidget *   modest_window_mgr_get_msg_view_window (ModestWindowMgr *self);
 394
 395 /**
 396  * modest_window_mgr_get_msg_edit_window:
 397  * @self: a #ModestWindowMgr
 398  *
 399  * obtain a cached #ModestMsgEditWindow if available, or construct a new
 400  * one.
 401  *
 402  * Returns: a #ModestMsgEditWindow
 403  */
 404 GtkWidget *   modest_window_mgr_get_msg_edit_window (ModestWindowMgr *self);
 405
 406 /**
 407  * modest_window_mgr_show_initial_window:
 408  * @self: a #ModestWindowMgr
 409  *
 410  * This function determines which is the window that should be
 411  * initially launched. After that it shows that window. If there is no
 412  * account available this function also launches the account setup
 413  * wizard.
 414  *
 415  * Returns: the initial window. NULL if something goes wrong
 416  **/
 417 ModestWindow* modest_window_mgr_show_initial_window (ModestWindowMgr *self);
 418
 419 /**
 420  * modest_window_mgr_get_current_top:
 421  * @self: a #ModestWindowMgr
 422  *
 423  * this function returns the ModestWindow that is currently on top of all the others
 424  *
 425  * Returns: the topmost #ModestWindow
 426  **/
 427 ModestWindow* modest_window_mgr_get_current_top (ModestWindowMgr *self);
 428
 429 /**
 430  * modest_window_mgr_screen_is_on:
 431  * @self: a #ModestWindowMgr
 432  *
 433  * this function returns if device display is on or not
 434  *
 435  * Returns: %TRUE if screen is on, %FALSE if not
 436  */
 437 gboolean modest_window_mgr_screen_is_on (ModestWindowMgr *self);
 438
 439 /**
 440  * modest_window_mgr_get_progress_operations:
 441  * @self: a #ModestWindowMgr
 442  *
 443  * get a list of operations in progress
 444  *
 445  * Returns: a newly allocated #TnyList
 446  */
 447 TnyList *modest_window_mgr_get_progress_operations (ModestWindowMgr *self);
 448
 449 /**
 450  * modest_window_mgr_has_progress_operation:
 451  * @self: a #ModestWindowMgr
 452  *
 453  * is there are send/receive or receive operations in progress for any account.
 454  *
 455  * Returns: %TRUE if receive progress operations are in progress.
 456  */
 457 gboolean modest_window_mgr_has_progress_operation (ModestWindowMgr *self);
 458
 459 /**
 460  * modest_window_mgr_has_progress_operation_on_account:
 461  * @self: a #ModestWindowMgr
 462  * @account_name: a string
 463  *
 464  * is there are send/receive or receive operations in progress for @account_name.
 465  *
 466  * Returns: %TRUE if receive progress operations are in progress.
 467  */
 468 gboolean modest_window_mgr_has_progress_operation_on_account (ModestWindowMgr *self,
 469                                                               const gchar *account_name);
 470
 471 /**
 472  * modest_window_mgr_create_caches:
 473  * @self: a #ModestWindowMgr
 474  *
 475  * creates cached windows. This is called in modest main, just before the show-ui
 476  * code. So it should be valid for the two startup ways (with --show-ui and without).
 477  */
 478 void modest_window_mgr_create_caches (ModestWindowMgr *self);
 479
 480 /**
 481  * modest_window_mgr_close_all_but_initial:
 482  * @self: a #ModestWindowMgr
 483  *
 484  * closes all but the initial window.
 485  *
 486  * Returns: %TRUE if the initial window is returned in @initial_window
 487  * and it does not have any other dialog or window on top, otherwhise
 488  * %FALSE
 489  */
 490 gboolean modest_window_mgr_close_all_but_initial (ModestWindowMgr *self);
 491
 492
 493 G_END_DECLS
 494
 495 #endif /* __MODEST_WINDOW_MGR_H__ */