vcs.maemo.org Git - hildon/blob - src/hildon-program.c

   1 /*
   2  * This file is a part of hildon
   3  *
   4  * Copyright (C) 2006 Nokia Corporation, all rights reserved.
   5  *
   6  * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public License
  10  * as published by the Free Software Foundation; version 2.1 of
  11  * the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  21  * 02110-1301 USA
  22  *
  23  */
  24
  25 /**
  26  * SECTION:hildon-program
  27  * @short_description: An object that represents an application running in the Hildon framework.
  28  * @see_also: #HildonWindow, #HildonStackableWindow
  29  *
  30  * The #HildonProgram is an object used to represent an application running
  31  * in the Hildon framework.
  32  *
  33  * Such an application is thought to have one or more #HildonWindow. These
  34  * shall be registered to the #HildonProgram with hildon_program_add_window(),
  35  * and can be unregistered similarly with hildon_program_remove_window().
  36  *
  37  * The #HildonProgram provides the programmer with commodities such
  38  * as applying a common toolbar and menu to all the #HildonWindow
  39  * registered to it. This is done with hildon_program_set_common_menu()
  40  * and hildon_program_set_common_toolbar().
  41  *
  42  * The #HildonProgram is also used to apply program-wide properties that
  43  * are specific to the Hildon framework. For instance
  44  * hildon_program_set_can_hibernate() sets whether or not an application
  45  * can be set to hibernate by the Hildon task navigator, in situations of
  46  * low memory.
  47  *
  48  * <example>
  49  * <programlisting>
  50  * HildonProgram *program;
  51  * HildonWindow *window1;
  52  * HildonWindow *window2;
  53  * GtkToolbar *common_toolbar, *window_specific_toolbar;
  54  * GtkMenu *menu;
  55  * <!-- -->
  56  * program = HILDON_PROGRAM (hildon_program_get_instance ());
  57  * <!-- -->
  58  * window1 = HILDON_WINDOW (hildon_window_new ());
  59  * window2 = HILDON_WINDOW (hildon_window_new ());
  60  * <!-- -->
  61  * common_toolbar = create_common_toolbar ();
  62  * window_specific_toolbar = create_window_specific_toolbar ();
  63  * <!-- -->
  64  * menu = create_menu ();
  65  * <!-- -->
  66  * hildon_program_add_window (program, window1);
  67  * hildon_program_add_window (program, window2);
  68  * <!-- -->
  69  * hildon_program_set_common_menu (program, menu);
  70  * <!-- -->
  71  * hildon_program_set_common_toolbar (program, common_toolbar);
  72  * hildon_window_add_toolbar (window1, window_specific_toolbar);
  73  * <!-- -->
  74  * hildon_program_set_can_hibernate (program, TRUE);
  75  * </programlisting>
  76  * </example>
  77  */
  78
  79 #undef                                          HILDON_DISABLE_DEPRECATED
  80
  81 #ifdef                                          HAVE_CONFIG_H
  82 #include                                        <config.h>
  83 #endif
  84
  85 #include                                        <X11/Xatom.h>
  86
  87 #include                                        "hildon-program.h"
  88 #include                                        "hildon-program-private.h"
  89 #include                                        "hildon-window-private.h"
  90 #include                                        "hildon-window-stack.h"
  91 #include                                        "hildon-app-menu-private.h"
  92
  93 static void
  94 hildon_program_init                             (HildonProgram *self);
  95
  96 static void
  97 hildon_program_finalize                         (GObject *self);
  98
  99 static void
 100 hildon_program_class_init                       (HildonProgramClass *self);
 101
 102 static void
 103 hildon_program_get_property                     (GObject *object,
 104                                                  guint property_id,
 105                                                  GValue *value,
 106                                                  GParamSpec *pspec);
 107 static void
 108 hildon_program_set_property                     (GObject *object,
 109                                                  guint property_id,
 110                                                  const GValue *value,
 111                                                  GParamSpec *pspec);
 112
 113 enum
 114 {
 115     PROP_0,
 116     PROP_IS_TOPMOST,
 117     PROP_KILLABLE
 118 };
 119
 120 GType G_GNUC_CONST
 121 hildon_program_get_type                         (void)
 122 {
 123     static GType program_type = 0;
 124
 125     if (! program_type)
 126     {
 127         static const GTypeInfo program_info =
 128         {
 129             sizeof (HildonProgramClass),
 130             NULL,       /* base_init */
 131             NULL,       /* base_finalize */
 132             (GClassInitFunc) hildon_program_class_init,
 133             NULL,       /* class_finalize */
 134             NULL,       /* class_data */
 135             sizeof (HildonProgram),
 136             0,  /* n_preallocs */
 137             (GInstanceInitFunc) hildon_program_init,
 138         };
 139         program_type = g_type_register_static(G_TYPE_OBJECT,
 140                 "HildonProgram", &program_info, 0);
 141     }
 142     return program_type;
 143 }
 144
 145 static void
 146 hildon_program_init                             (HildonProgram *self)
 147 {
 148     HildonProgramPrivate *priv = HILDON_PROGRAM_GET_PRIVATE (self);
 149     g_assert (priv);
 150
 151     priv->killable = FALSE;
 152     priv->window_count = 0;
 153     priv->is_topmost = FALSE;
 154     priv->window_group = GDK_WINDOW_XID (gdk_display_get_default_group (gdk_display_get_default()));
 155     priv->common_menu = NULL;
 156     priv->common_app_menu = NULL;
 157     priv->common_toolbar = NULL;
 158     priv->windows = NULL;
 159 }
 160
 161 static void
 162 hildon_program_finalize                         (GObject *self)
 163 {
 164     HildonProgramPrivate *priv = HILDON_PROGRAM_GET_PRIVATE (HILDON_PROGRAM (self));
 165     g_assert (priv);
 166
 167     if (priv->common_toolbar)
 168     {
 169         g_object_unref (priv->common_toolbar);
 170         priv->common_toolbar = NULL;
 171     }
 172
 173     if (priv->common_menu)
 174     {
 175         g_object_unref (priv->common_menu);
 176         priv->common_menu = NULL;
 177     }
 178 }
 179
 180 static void
 181 hildon_program_class_init                       (HildonProgramClass *self)
 182 {
 183     GObjectClass *object_class = G_OBJECT_CLASS (self);
 184
 185     g_type_class_add_private (self, sizeof (HildonProgramPrivate));
 186
 187     /* Set up object virtual functions */
 188     object_class->finalize      = hildon_program_finalize;
 189     object_class->set_property  = hildon_program_set_property;
 190     object_class->get_property  = hildon_program_get_property;
 191
 192     /* Install properties */
 193
 194     /**
 195      * HildonProgram:is-topmost:
 196      *
 197      * Whether one of the program's window or dialog currently
 198      * is activated by window manager.
 199      */
 200     g_object_class_install_property (object_class, PROP_IS_TOPMOST,
 201                 g_param_spec_boolean ("is-topmost",
 202                 "Is top-most",
 203                 "Whether one of the program's window or dialog currently "
 204                 "is activated by window manager",
 205                 FALSE,
 206                 G_PARAM_READABLE));
 207
 208     /**
 209      * HildonProgram:can-hibernate:
 210      *
 211      * Whether the program should be set to hibernate by the Task
 212      * Navigator in low memory situation.
 213      */
 214     g_object_class_install_property (object_class, PROP_KILLABLE,
 215                 g_param_spec_boolean ("can-hibernate",
 216                 "Can hibernate",
 217                 "Whether the program should be set to hibernate by the Task "
 218                 "Navigator in low memory situation",
 219                 FALSE,
 220                 G_PARAM_READWRITE));
 221     return;
 222 }
 223
 224 static void
 225 hildon_program_set_property                     (GObject *object,
 226                                                  guint property_id,
 227                                                  const GValue *value,
 228                                                  GParamSpec *pspec)
 229 {
 230     switch (property_id) {
 231
 232         case PROP_KILLABLE:
 233             hildon_program_set_can_hibernate (HILDON_PROGRAM (object), g_value_get_boolean (value));
 234             break;
 235
 236         default:
 237             G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 238             break;
 239     }
 240
 241 }
 242
 243 static void
 244 hildon_program_get_property                     (GObject *object,
 245                                                  guint property_id,
 246                                                  GValue *value,
 247                                                  GParamSpec *pspec)
 248 {
 249     HildonProgramPrivate *priv = HILDON_PROGRAM_GET_PRIVATE (object);
 250     g_assert (priv);
 251
 252     switch (property_id)
 253     {
 254         case PROP_KILLABLE:
 255             g_value_set_boolean (value, priv->killable);
 256             break;
 257
 258         case PROP_IS_TOPMOST:
 259             g_value_set_boolean (value, priv->is_topmost);
 260             break;
 261
 262         default:
 263             G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 264             break;
 265     }
 266 }
 267
 268 /**
 269  * hildon_program_pop_window_stack:
 270  * @self: A #HildonProgram
 271  *
 272  * Pops a window from the stack.
 273  *
 274  * Deprecated: Use hildon_window_stack_pop() instead
 275  *
 276  * Returns: A #HildonStackableWindow, or %NULL
 277  */
 278 HildonStackableWindow *
 279 hildon_program_pop_window_stack                 (HildonProgram *self)
 280 {
 281     HildonWindowStack *stack = hildon_window_stack_get_default ();
 282     GtkWidget *win = hildon_window_stack_pop_1 (stack);
 283     g_warning ("%s: this function is deprecated. Use hildon_window_stack_pop() instead", __FUNCTION__);
 284     return win ? HILDON_STACKABLE_WINDOW (win) : NULL;
 285 }
 286
 287 /**
 288  * hildon_program_peek_window_stack:
 289  * @self: A #HildonProgram
 290  *
 291  * Deprecated: Use hildon_window_stack_peek() instead
 292  *
 293  * Returns: A #HildonStackableWindow, or %NULL
 294  */
 295 HildonStackableWindow *
 296 hildon_program_peek_window_stack                (HildonProgram *self)
 297 {
 298     HildonWindowStack *stack = hildon_window_stack_get_default ();
 299     GtkWidget *win = hildon_window_stack_peek (stack);
 300     g_warning ("%s: this function is deprecated. Use hildon_window_stack_peek() instead", __FUNCTION__);
 301     return win ? HILDON_STACKABLE_WINDOW (win) : NULL;
 302 }
 303
 304 /* Utilities */
 305 static gint
 306 hildon_program_window_list_compare              (gconstpointer window_a,
 307                                                  gconstpointer window_b)
 308 {
 309     g_return_val_if_fail (HILDON_IS_WINDOW(window_a) &&
 310                           HILDON_IS_WINDOW(window_b), 1);
 311
 312     return window_a != window_b;
 313 }
 314
 315 /*
 316  * foreach function, checks if a window is topmost and acts consequently
 317  */
 318 static void
 319 hildon_program_window_list_is_is_topmost        (gpointer data,
 320                                                  gpointer window_id_)
 321 {
 322     if (data && HILDON_IS_WINDOW (data))
 323     {
 324         HildonWindow *window = HILDON_WINDOW (data);
 325         Window window_id = * (Window*)window_id_;
 326
 327         hildon_window_update_topmost (window, window_id);
 328     }
 329 }
 330
 331 /*
 332  * Check the _MB_CURRENT_APP_WINDOW on the root window, and update
 333  * the top_most status accordingly
 334  */
 335 static void
 336 hildon_program_update_top_most                  (HildonProgram *program)
 337 {
 338     XWMHints *wm_hints;
 339     Window active_window;
 340     HildonProgramPrivate *priv;
 341
 342     priv = HILDON_PROGRAM_GET_PRIVATE (program);
 343     g_assert (priv);
 344
 345     active_window = hildon_window_get_active_window();
 346
 347     if (active_window)
 348     {
 349       gint xerror;
 350       gboolean is_topmost = FALSE;
 351
 352       gdk_error_trap_push ();
 353       wm_hints = XGetWMHints (GDK_DISPLAY (), active_window);
 354       xerror = gdk_error_trap_pop ();
 355       if (xerror)
 356         return;
 357
 358       if (wm_hints)
 359       {
 360         is_topmost = (wm_hints->window_group == priv->window_group);
 361         XFree (wm_hints);
 362       }
 363
 364       /* Send notification if is_topmost has changed */
 365       if (!priv->is_topmost != !is_topmost)
 366       {
 367         priv->is_topmost = is_topmost;
 368         g_object_notify (G_OBJECT (program), "is-topmost");
 369       }
 370     }
 371
 372     /* Check each window if it was is_topmost */
 373     g_slist_foreach (priv->windows,
 374             (GFunc)hildon_program_window_list_is_is_topmost, &active_window);
 375 }
 376
 377 /*
 378  * We keep track of the _MB_CURRENT_APP_WINDOW property on the root window,
 379  * to detect when a window belonging to this program was is_topmost. This
 380  * is based on the window group WM hint.
 381  */
 382 static GdkFilterReturn
 383 hildon_program_root_window_event_filter         (GdkXEvent *xevent,
 384                                                  GdkEvent *event,
 385                                                  gpointer data)
 386 {
 387     XAnyEvent *eventti = xevent;
 388     HildonProgram *program = HILDON_PROGRAM (data);
 389     Atom active_app_atom =
 390             XInternAtom (GDK_DISPLAY (), "_MB_CURRENT_APP_WINDOW", False);
 391
 392     if (eventti->type == PropertyNotify)
 393     {
 394         XPropertyEvent *pevent = xevent;
 395
 396         if (pevent->atom == active_app_atom)
 397         {
 398             hildon_program_update_top_most (program);
 399         }
 400     }
 401
 402     return GDK_FILTER_CONTINUE;
 403 }
 404
 405 /*
 406  * Checks if the window is the topmost window of the program and in
 407  * that case forces the window to take the common toolbar.
 408  */
 409 static void
 410 hildon_program_common_toolbar_topmost_window    (gpointer window,
 411                                                  gpointer data)
 412 {
 413     if (HILDON_IS_WINDOW (window) && hildon_window_get_is_topmost (HILDON_WINDOW (window)))
 414         hildon_window_take_common_toolbar (HILDON_WINDOW (window));
 415 }
 416
 417 /**
 418  * hildon_program_get_instance:
 419  *
 420  * Returns the #HildonProgram for the current process. The object is
 421  * created on the first call. Note that you're not supposed to unref
 422  * the returned object since it's not reffed in the first place.
 423  *
 424  * Return value: the #HildonProgram.
 425  **/
 426 HildonProgram*
 427 hildon_program_get_instance                     (void)
 428 {
 429     static HildonProgram *program = NULL;
 430
 431     if (! program)
 432     {
 433         program = g_object_new (HILDON_TYPE_PROGRAM, NULL);
 434     }
 435
 436     return program;
 437 }
 438
 439 /**
 440  * hildon_program_add_window:
 441  * @self: The #HildonProgram to which the window should be registered
 442  * @window: A #HildonWindow to be added
 443  *
 444  * Registers a #HildonWindow as belonging to a given #HildonProgram. This
 445  * allows to apply program-wide settings as all the registered windows,
 446  * such as hildon_program_set_common_menu() and
 447  * hildon_pogram_set_common_toolbar()
 448  **/
 449 void
 450 hildon_program_add_window                       (HildonProgram *self,
 451                                                  HildonWindow *window)
 452 {
 453     HildonProgramPrivate *priv;
 454
 455     g_return_if_fail (HILDON_IS_PROGRAM (self));
 456
 457     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 458     g_assert (priv);
 459
 460     if (g_slist_find_custom (priv->windows, window,
 461            hildon_program_window_list_compare) )
 462     {
 463         /* We already have that window */
 464         return;
 465     }
 466
 467     if (!priv->window_count)
 468     {
 469         hildon_program_update_top_most (self);
 470
 471         /* Now that we have a window we should start keeping track of
 472          * the root window */
 473         gdk_window_set_events (gdk_get_default_root_window (),
 474                 gdk_window_get_events (gdk_get_default_root_window ()) | GDK_PROPERTY_CHANGE_MASK);
 475
 476         gdk_window_add_filter (gdk_get_default_root_window (),
 477                 hildon_program_root_window_event_filter, self );
 478     }
 479
 480     hildon_window_set_can_hibernate_property (window, &priv->killable);
 481
 482     hildon_window_set_program (window, G_OBJECT (self));
 483
 484     priv->windows = g_slist_append (priv->windows, window);
 485     priv->window_count ++;
 486 }
 487
 488 /**
 489  * hildon_program_remove_window:
 490  * @self: The #HildonProgram to which the window should be unregistered
 491  * @window: The @HildonWindow to unregister
 492  *
 493  * Used to unregister a window from the program. Subsequent calls to
 494  * hildon_program_set_common_menu() and hildon_pogram_set_common_toolbar()
 495  * will not affect the window
 496  **/
 497 void
 498 hildon_program_remove_window                    (HildonProgram *self,
 499                                                  HildonWindow *window)
 500 {
 501     HildonProgramPrivate *priv;
 502
 503     g_return_if_fail (HILDON_IS_PROGRAM (self));
 504
 505     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 506     g_assert (priv);
 507
 508     hildon_window_unset_program (window);
 509
 510     priv->windows = g_slist_remove (priv->windows, window);
 511
 512     priv->window_count --;
 513
 514     if (! priv->window_count)
 515         gdk_window_remove_filter (gdk_get_default_root_window(),
 516                 hildon_program_root_window_event_filter,
 517                 self);
 518 }
 519
 520 /**
 521  * hildon_program_set_can_hibernate:
 522  * @self: The #HildonProgram which can hibernate or not
 523  * @can_hibernate: whether or not the #HildonProgram can hibernate
 524  *
 525  * Used to set whether or not the Hildon task navigator should
 526  * be able to set the program to hibernation in case of low memory
 527  **/
 528 void
 529 hildon_program_set_can_hibernate                (HildonProgram *self,
 530                                                  gboolean can_hibernate)
 531 {
 532     HildonProgramPrivate *priv;
 533
 534     g_return_if_fail (HILDON_IS_PROGRAM (self));
 535
 536     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 537     g_assert (priv);
 538
 539     if (priv->killable != can_hibernate)
 540     {
 541         g_slist_foreach (priv->windows,
 542                 (GFunc) hildon_window_set_can_hibernate_property, &can_hibernate);
 543     }
 544
 545     priv->killable = can_hibernate;
 546 }
 547
 548 /**
 549  * hildon_program_get_can_hibernate:
 550  * @self: The #HildonProgram which can hibernate or not
 551  *
 552  * Returns whether the #HildonProgram is set to be support hibernation
 553  * from the Hildon task navigator
 554  *
 555  * Return value: %TRUE if the program can hibernate, %FALSE otherwise.
 556  **/
 557 gboolean
 558 hildon_program_get_can_hibernate                (HildonProgram *self)
 559 {
 560     HildonProgramPrivate *priv;
 561
 562     g_return_val_if_fail (HILDON_IS_PROGRAM (self), FALSE);
 563
 564     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 565     g_assert (priv);
 566
 567     return priv->killable;
 568 }
 569
 570 /**
 571  * hildon_program_set_common_menu:
 572  * @self: The #HildonProgram in which the common menu should be used
 573  * @menu: A GtkMenu to use as common menu for the program
 574  *
 575  * Sets a GtkMenu that will appear in all the #HildonWindow registered
 576  * with the #HildonProgram. Only one common GtkMenu can be set, further
 577  * calls will detach the previous common GtkMenu. A #HildonWindow
 578  * can use its own GtkMenu with hildon_window_set_menu()
 579  *
 580  * This method is not intented for #HildonStackableWindow<!-- -->s and
 581  * does not support #HildonAppMenu objects. See
 582  * hildon_program_set_common_app_menu() for that.
 583  *
 584  * Since: 2.2
 585  **/
 586 void
 587 hildon_program_set_common_menu                  (HildonProgram *self,
 588                                                  GtkMenu *menu)
 589 {
 590     HildonProgramPrivate *priv;
 591
 592     g_return_if_fail (HILDON_IS_PROGRAM (self));
 593
 594     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 595     g_assert (priv);
 596
 597     if (priv->common_menu)
 598     {
 599         if (GTK_WIDGET_VISIBLE (priv->common_menu))
 600         {
 601             gtk_menu_popdown (GTK_MENU (priv->common_menu));
 602             gtk_menu_shell_deactivate (GTK_MENU_SHELL (priv->common_menu));
 603         }
 604
 605         if (gtk_menu_get_attach_widget (GTK_MENU (priv->common_menu)))
 606         {
 607             gtk_menu_detach (GTK_MENU (priv->common_menu));
 608         }
 609         else
 610         {
 611             g_object_unref (priv->common_menu);
 612         }
 613     }
 614
 615     priv->common_menu = GTK_WIDGET (menu);
 616
 617     if (priv->common_menu)
 618     {
 619         g_object_ref (menu);
 620         gtk_object_sink (GTK_OBJECT (menu));
 621         gtk_widget_show_all (GTK_WIDGET (menu));
 622     }
 623 }
 624
 625 /**
 626  * hildon_program_get_common_menu:
 627  * @self: The #HildonProgram from which to retrieve the common menu
 628  *
 629  * Returns the #GtkMenu that was set as common menu for this
 630  * #HildonProgram.
 631  *
 632  * Return value: the #GtkMenu or %NULL of no common menu was set.
 633  **/
 634 GtkMenu*
 635 hildon_program_get_common_menu                  (HildonProgram *self)
 636 {
 637     HildonProgramPrivate *priv;
 638
 639     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 640
 641     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 642     g_assert (priv);
 643
 644     return GTK_MENU (priv->common_menu);
 645 }
 646
 647 /**
 648  * hildon_program_set_common_app_menu:
 649  * @self: The #HildonProgram in which the common menu should be used
 650  * @menu: A #HildonAppMenu to use as common menu for the program
 651  *
 652  * Sets a #HildonAppMenu that will appear in all the
 653  * #HildonStackableWindow<!-- -->s registered with the
 654  * #HildonProgram. Only one common #HildonAppMenu can be set, further
 655  * calls will detach the previous common #HildonAppMenu. A
 656  * #HildonStackableWindow can use its own #HildonAppMenu with
 657  * hildon_stackable_window_set_main_menu()
 658  *
 659  * This method is not intented for standard #HildonWindow<!-- -->s and
 660  * does not support #GtkMenu objects. See
 661  * hildon_program_set_common_menu() for that.
 662  *
 663  * Since: 2.2
 664  **/
 665 void
 666 hildon_program_set_common_app_menu              (HildonProgram *self,
 667                                                  HildonAppMenu *menu)
 668 {
 669     HildonProgramPrivate *priv;
 670     GtkWidget *old_menu;
 671
 672     g_return_if_fail (HILDON_IS_PROGRAM (self));
 673     g_return_if_fail (menu == NULL || HILDON_IS_APP_MENU (menu));
 674
 675     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 676     g_assert (priv);
 677
 678     old_menu = priv->common_app_menu;
 679
 680     /* Set new menu */
 681     priv->common_app_menu = GTK_WIDGET (menu);
 682     if (menu)
 683         g_object_ref_sink (menu);
 684
 685     /* Hide and unref old menu */
 686     if (old_menu) {
 687         hildon_app_menu_set_parent_window (HILDON_APP_MENU (old_menu), NULL);
 688         g_object_unref (old_menu);
 689     }
 690 }
 691
 692 /**
 693  * hildon_program_get_common_app_menu:
 694  * @self: The #HildonProgram from which to retrieve the common app menu
 695  *
 696  * Returns the #HildonAppMenu that was set as common menu for this
 697  * #HildonProgram.
 698  *
 699  * Return value: the #HildonAppMenu or %NULL of no common app menu was
 700  * set.
 701  *
 702  * Since: 2.2
 703  **/
 704 HildonAppMenu*
 705 hildon_program_get_common_app_menu              (HildonProgram *self)
 706 {
 707     HildonProgramPrivate *priv;
 708
 709     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 710
 711     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 712     g_assert (priv);
 713
 714     return HILDON_APP_MENU (priv->common_app_menu);
 715 }
 716
 717 /**
 718  * hildon_program_set_common_toolbar:
 719  * @self: The #HildonProgram in which the common toolbar should be used
 720  * @toolbar: A GtkToolbar to use as common toolbar for the program
 721  *
 722  * Sets a GtkToolbar that will appear in all the #HildonWindow registered
 723  * to the #HildonProgram. Only one common GtkToolbar can be set, further
 724  * call will detach the previous common GtkToolbar. A #HildonWindow
 725  * can use its own GtkToolbar with hildon_window_add_toolbar(). Both
 726  * #HildonProgram and #HildonWindow specific toolbars will be shown
 727  **/
 728 void
 729 hildon_program_set_common_toolbar               (HildonProgram *self,
 730                                                  GtkToolbar *toolbar)
 731 {
 732     HildonProgramPrivate *priv;
 733
 734     g_return_if_fail (HILDON_IS_PROGRAM (self));
 735
 736     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 737     g_assert (priv);
 738
 739     if (priv->common_toolbar)
 740     {
 741         if (priv->common_toolbar->parent)
 742         {
 743             gtk_container_remove (GTK_CONTAINER (priv->common_toolbar->parent),
 744                                   priv->common_toolbar);
 745         }
 746
 747         g_object_unref (priv->common_toolbar);
 748     }
 749
 750     priv->common_toolbar = GTK_WIDGET (toolbar);
 751
 752     if (priv->common_toolbar)
 753     {
 754         g_object_ref (priv->common_toolbar);
 755         gtk_object_sink (GTK_OBJECT (priv->common_toolbar) );
 756     }
 757
 758     /* if the program is the topmost we have to update the common
 759        toolbar right now for the topmost window */
 760     if (priv->is_topmost)
 761       {
 762         g_slist_foreach (priv->windows,
 763                          (GFunc) hildon_program_common_toolbar_topmost_window, NULL);
 764       }
 765 }
 766
 767 /**
 768  * hildon_program_get_common_toolbar:
 769  * @self: The #HildonProgram from which to retrieve the common toolbar
 770  *
 771  * Returns the #GtkToolbar that was set as common toolbar for this
 772  * #HildonProgram.
 773  *
 774  * Return value: the #GtkToolbar or %NULL of no common toolbar was
 775  * set.
 776  **/
 777 GtkToolbar*
 778 hildon_program_get_common_toolbar               (HildonProgram *self)
 779 {
 780     HildonProgramPrivate *priv;
 781
 782     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 783
 784     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 785     g_assert (priv);
 786
 787     return priv->common_toolbar ? GTK_TOOLBAR (priv->common_toolbar) : NULL;
 788 }
 789
 790 /**
 791  * hildon_program_get_is_topmost:
 792  * @self: A #HildonWindow
 793  *
 794  * Returns whether one of the program's windows or dialogs is
 795  * currently activated by the window manager.
 796  *
 797  * Return value: %TRUE if a window or dialog is topmost, %FALSE
 798  * otherwise.
 799  **/
 800 gboolean
 801 hildon_program_get_is_topmost                   (HildonProgram *self)
 802 {
 803     HildonProgramPrivate *priv;
 804
 805     g_return_val_if_fail (HILDON_IS_PROGRAM (self), FALSE);
 806
 807     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 808     g_assert (priv);
 809
 810     return priv->is_topmost;
 811 }
 812
 813 /**
 814  * hildon_program_go_to_root_window:
 815  * @self: A #HildonProgram
 816  *
 817  * Goes to the root window of the stack.
 818  *
 819  * Deprecated: See #HildonWindowStack
 820  */
 821 void
 822 hildon_program_go_to_root_window                (HildonProgram *self)
 823 {
 824     HildonWindowStack *stack = hildon_window_stack_get_default ();
 825     gint n = hildon_window_stack_size (stack);
 826     g_warning ("%s: this function is deprecated. Use hildon_window_stack_pop() instead.", __FUNCTION__);
 827     if (n > 1) {
 828         hildon_window_stack_pop (stack, n-1, NULL);
 829     }
 830 }