git.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
 351       gdk_error_trap_push ();
 352       wm_hints = XGetWMHints (GDK_DISPLAY (), active_window);
 353       xerror = gdk_error_trap_pop ();
 354       if (xerror)
 355         return;
 356
 357       if (wm_hints)
 358       {
 359
 360           if (wm_hints->window_group == priv->window_group)
 361           {
 362               if (!priv->is_topmost)
 363               {
 364                   priv->is_topmost = TRUE;
 365                   g_object_notify (G_OBJECT (program), "is-topmost");
 366               }
 367           }
 368           else if (priv->is_topmost)
 369           {
 370             priv->is_topmost = FALSE;
 371             g_object_notify (G_OBJECT (program), "is-topmost");
 372           }
 373       }
 374       XFree (wm_hints);
 375     }
 376
 377     /* Check each window if it was is_topmost */
 378     g_slist_foreach (priv->windows,
 379             (GFunc)hildon_program_window_list_is_is_topmost, &active_window);
 380 }
 381
 382 /*
 383  * We keep track of the _MB_CURRENT_APP_WINDOW property on the root window,
 384  * to detect when a window belonging to this program was is_topmost. This
 385  * is based on the window group WM hint.
 386  */
 387 static GdkFilterReturn
 388 hildon_program_root_window_event_filter         (GdkXEvent *xevent,
 389                                                  GdkEvent *event,
 390                                                  gpointer data)
 391 {
 392     XAnyEvent *eventti = xevent;
 393     HildonProgram *program = HILDON_PROGRAM (data);
 394     Atom active_app_atom =
 395             XInternAtom (GDK_DISPLAY (), "_MB_CURRENT_APP_WINDOW", False);
 396
 397     if (eventti->type == PropertyNotify)
 398     {
 399         XPropertyEvent *pevent = xevent;
 400
 401         if (pevent->atom == active_app_atom)
 402         {
 403             hildon_program_update_top_most (program);
 404         }
 405     }
 406
 407     return GDK_FILTER_CONTINUE;
 408 }
 409
 410 /*
 411  * Checks if the window is the topmost window of the program and in
 412  * that case forces the window to take the common toolbar.
 413  */
 414 static void
 415 hildon_program_common_toolbar_topmost_window    (gpointer window,
 416                                                  gpointer data)
 417 {
 418     if (HILDON_IS_WINDOW (window) && hildon_window_get_is_topmost (HILDON_WINDOW (window)))
 419         hildon_window_take_common_toolbar (HILDON_WINDOW (window));
 420 }
 421
 422 /**
 423  * hildon_program_get_instance:
 424  *
 425  * Returns the #HildonProgram for the current process. The object is
 426  * created on the first call. Note that you're not supposed to unref
 427  * the returned object since it's not reffed in the first place.
 428  *
 429  * Return value: the #HildonProgram.
 430  **/
 431 HildonProgram*
 432 hildon_program_get_instance                     (void)
 433 {
 434     static HildonProgram *program = NULL;
 435
 436     if (! program)
 437     {
 438         program = g_object_new (HILDON_TYPE_PROGRAM, NULL);
 439     }
 440
 441     return program;
 442 }
 443
 444 /**
 445  * hildon_program_add_window:
 446  * @self: The #HildonProgram to which the window should be registered
 447  * @window: A #HildonWindow to be added
 448  *
 449  * Registers a #HildonWindow as belonging to a given #HildonProgram. This
 450  * allows to apply program-wide settings as all the registered windows,
 451  * such as hildon_program_set_common_menu() and
 452  * hildon_pogram_set_common_toolbar()
 453  **/
 454 void
 455 hildon_program_add_window                       (HildonProgram *self,
 456                                                  HildonWindow *window)
 457 {
 458     HildonProgramPrivate *priv;
 459
 460     g_return_if_fail (HILDON_IS_PROGRAM (self));
 461
 462     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 463     g_assert (priv);
 464
 465     if (g_slist_find_custom (priv->windows, window,
 466            hildon_program_window_list_compare) )
 467     {
 468         /* We already have that window */
 469         return;
 470     }
 471
 472     if (!priv->window_count)
 473     {
 474         hildon_program_update_top_most (self);
 475
 476         /* Now that we have a window we should start keeping track of
 477          * the root window */
 478         gdk_window_set_events (gdk_get_default_root_window (),
 479                 gdk_window_get_events (gdk_get_default_root_window ()) | GDK_PROPERTY_CHANGE_MASK);
 480
 481         gdk_window_add_filter (gdk_get_default_root_window (),
 482                 hildon_program_root_window_event_filter, self );
 483     }
 484
 485     hildon_window_set_can_hibernate_property (window, &priv->killable);
 486
 487     hildon_window_set_program (window, G_OBJECT (self));
 488
 489     priv->windows = g_slist_append (priv->windows, window);
 490     priv->window_count ++;
 491 }
 492
 493 /**
 494  * hildon_program_remove_window:
 495  * @self: The #HildonProgram to which the window should be unregistered
 496  * @window: The @HildonWindow to unregister
 497  *
 498  * Used to unregister a window from the program. Subsequent calls to
 499  * hildon_program_set_common_menu() and hildon_pogram_set_common_toolbar()
 500  * will not affect the window
 501  **/
 502 void
 503 hildon_program_remove_window                    (HildonProgram *self,
 504                                                  HildonWindow *window)
 505 {
 506     HildonProgramPrivate *priv;
 507
 508     g_return_if_fail (HILDON_IS_PROGRAM (self));
 509
 510     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 511     g_assert (priv);
 512
 513     hildon_window_unset_program (window);
 514
 515     priv->windows = g_slist_remove (priv->windows, window);
 516
 517     priv->window_count --;
 518
 519     if (! priv->window_count)
 520         gdk_window_remove_filter (gdk_get_default_root_window(),
 521                 hildon_program_root_window_event_filter,
 522                 self);
 523 }
 524
 525 /**
 526  * hildon_program_set_can_hibernate:
 527  * @self: The #HildonProgram which can hibernate or not
 528  * @can_hibernate: whether or not the #HildonProgram can hibernate
 529  *
 530  * Used to set whether or not the Hildon task navigator should
 531  * be able to set the program to hibernation in case of low memory
 532  **/
 533 void
 534 hildon_program_set_can_hibernate                (HildonProgram *self,
 535                                                  gboolean can_hibernate)
 536 {
 537     HildonProgramPrivate *priv;
 538
 539     g_return_if_fail (HILDON_IS_PROGRAM (self));
 540
 541     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 542     g_assert (priv);
 543
 544     if (priv->killable != can_hibernate)
 545     {
 546         g_slist_foreach (priv->windows,
 547                 (GFunc) hildon_window_set_can_hibernate_property, &can_hibernate);
 548     }
 549
 550     priv->killable = can_hibernate;
 551 }
 552
 553 /**
 554  * hildon_program_get_can_hibernate:
 555  * @self: The #HildonProgram which can hibernate or not
 556  *
 557  * Returns whether the #HildonProgram is set to be support hibernation
 558  * from the Hildon task navigator
 559  *
 560  * Return value: %TRUE if the program can hibernate, %FALSE otherwise.
 561  **/
 562 gboolean
 563 hildon_program_get_can_hibernate                (HildonProgram *self)
 564 {
 565     HildonProgramPrivate *priv;
 566
 567     g_return_val_if_fail (HILDON_IS_PROGRAM (self), FALSE);
 568
 569     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 570     g_assert (priv);
 571
 572     return priv->killable;
 573 }
 574
 575 /**
 576  * hildon_program_set_common_menu:
 577  * @self: The #HildonProgram in which the common menu should be used
 578  * @menu: A GtkMenu to use as common menu for the program
 579  *
 580  * Sets a GtkMenu that will appear in all the #HildonWindow registered
 581  * with the #HildonProgram. Only one common GtkMenu can be set, further
 582  * calls will detach the previous common GtkMenu. A #HildonWindow
 583  * can use its own GtkMenu with hildon_window_set_menu()
 584  *
 585  * This method is not intented for #HildonStackableWindow<!-- -->s and
 586  * does not support #HildonAppMenu objects. See
 587  * hildon_program_set_common_app_menu() for that.
 588  *
 589  * Since: 2.2
 590  **/
 591 void
 592 hildon_program_set_common_menu                  (HildonProgram *self,
 593                                                  GtkMenu *menu)
 594 {
 595     HildonProgramPrivate *priv;
 596
 597     g_return_if_fail (HILDON_IS_PROGRAM (self));
 598
 599     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 600     g_assert (priv);
 601
 602     if (priv->common_menu)
 603     {
 604         if (GTK_WIDGET_VISIBLE (priv->common_menu))
 605         {
 606             gtk_menu_popdown (GTK_MENU (priv->common_menu));
 607             gtk_menu_shell_deactivate (GTK_MENU_SHELL (priv->common_menu));
 608         }
 609
 610         if (gtk_menu_get_attach_widget (GTK_MENU (priv->common_menu)))
 611         {
 612             gtk_menu_detach (GTK_MENU (priv->common_menu));
 613         }
 614         else
 615         {
 616             g_object_unref (priv->common_menu);
 617         }
 618     }
 619
 620     priv->common_menu = GTK_WIDGET (menu);
 621
 622     if (priv->common_menu)
 623     {
 624         g_object_ref (menu);
 625         gtk_object_sink (GTK_OBJECT (menu));
 626         gtk_widget_show_all (GTK_WIDGET (menu));
 627     }
 628 }
 629
 630 /**
 631  * hildon_program_get_common_menu:
 632  * @self: The #HildonProgram from which to retrieve the common menu
 633  *
 634  * Returns the #GtkMenu that was set as common menu for this
 635  * #HildonProgram.
 636  *
 637  * Return value: the #GtkMenu or %NULL of no common menu was set.
 638  **/
 639 GtkMenu*
 640 hildon_program_get_common_menu                  (HildonProgram *self)
 641 {
 642     HildonProgramPrivate *priv;
 643
 644     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 645
 646     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 647     g_assert (priv);
 648
 649     return GTK_MENU (priv->common_menu);
 650 }
 651
 652 /**
 653  * hildon_program_set_common_app_menu:
 654  * @self: The #HildonProgram in which the common menu should be used
 655  * @menu: A #HildonAppMenu to use as common menu for the program
 656  *
 657  * Sets a #HildonAppMenu that will appear in all the
 658  * #HildonStackableWindow<!-- -->s registered with the
 659  * #HildonProgram. Only one common #HildonAppMenu can be set, further
 660  * calls will detach the previous common #HildonAppMenu. A
 661  * #HildonStackableWindow can use its own #HildonAppMenu with
 662  * hildon_stackable_window_set_main_menu()
 663  *
 664  * This method is not intented for standard #HildonWindow<!-- -->s and
 665  * does not support #GtkMenu objects. See
 666  * hildon_program_set_common_menu() for that.
 667  *
 668  * Since: 2.2
 669  **/
 670 void
 671 hildon_program_set_common_app_menu              (HildonProgram *self,
 672                                                  HildonAppMenu *menu)
 673 {
 674     HildonProgramPrivate *priv;
 675     GtkWidget *old_menu;
 676
 677     g_return_if_fail (HILDON_IS_PROGRAM (self));
 678     g_return_if_fail (menu == NULL || HILDON_IS_APP_MENU (menu));
 679
 680     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 681     g_assert (priv);
 682
 683     old_menu = priv->common_app_menu;
 684
 685     /* Set new menu */
 686     priv->common_app_menu = GTK_WIDGET (menu);
 687     if (menu)
 688         g_object_ref_sink (menu);
 689
 690     /* Hide and unref old menu */
 691     if (old_menu) {
 692         hildon_app_menu_set_parent_window (HILDON_APP_MENU (old_menu), NULL);
 693         g_object_unref (old_menu);
 694     }
 695 }
 696
 697 /**
 698  * hildon_program_get_common_app_menu:
 699  * @self: The #HildonProgram from which to retrieve the common app menu
 700  *
 701  * Returns the #HildonAppMenu that was set as common menu for this
 702  * #HildonProgram.
 703  *
 704  * Return value: the #HildonAppMenu or %NULL of no common app menu was
 705  * set.
 706  *
 707  * Since: 2.2
 708  **/
 709 HildonAppMenu*
 710 hildon_program_get_common_app_menu              (HildonProgram *self)
 711 {
 712     HildonProgramPrivate *priv;
 713
 714     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 715
 716     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 717     g_assert (priv);
 718
 719     return HILDON_APP_MENU (priv->common_app_menu);
 720 }
 721
 722 /**
 723  * hildon_program_set_common_toolbar:
 724  * @self: The #HildonProgram in which the common toolbar should be used
 725  * @toolbar: A GtkToolbar to use as common toolbar for the program
 726  *
 727  * Sets a GtkToolbar that will appear in all the #HildonWindow registered
 728  * to the #HildonProgram. Only one common GtkToolbar can be set, further
 729  * call will detach the previous common GtkToolbar. A #HildonWindow
 730  * can use its own GtkToolbar with hildon_window_add_toolbar(). Both
 731  * #HildonProgram and #HildonWindow specific toolbars will be shown
 732  **/
 733 void
 734 hildon_program_set_common_toolbar               (HildonProgram *self,
 735                                                  GtkToolbar *toolbar)
 736 {
 737     HildonProgramPrivate *priv;
 738
 739     g_return_if_fail (HILDON_IS_PROGRAM (self));
 740
 741     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 742     g_assert (priv);
 743
 744     if (priv->common_toolbar)
 745     {
 746         if (priv->common_toolbar->parent)
 747         {
 748             gtk_container_remove (GTK_CONTAINER (priv->common_toolbar->parent),
 749                                   priv->common_toolbar);
 750         }
 751
 752         g_object_unref (priv->common_toolbar);
 753     }
 754
 755     priv->common_toolbar = GTK_WIDGET (toolbar);
 756
 757     if (priv->common_toolbar)
 758     {
 759         g_object_ref (priv->common_toolbar);
 760         gtk_object_sink (GTK_OBJECT (priv->common_toolbar) );
 761     }
 762
 763     /* if the program is the topmost we have to update the common
 764        toolbar right now for the topmost window */
 765     if (priv->is_topmost)
 766       {
 767         g_slist_foreach (priv->windows,
 768                          (GFunc) hildon_program_common_toolbar_topmost_window, NULL);
 769       }
 770 }
 771
 772 /**
 773  * hildon_program_get_common_toolbar:
 774  * @self: The #HildonProgram from which to retrieve the common toolbar
 775  *
 776  * Returns the #GtkToolbar that was set as common toolbar for this
 777  * #HildonProgram.
 778  *
 779  * Return value: the #GtkToolbar or %NULL of no common toolbar was
 780  * set.
 781  **/
 782 GtkToolbar*
 783 hildon_program_get_common_toolbar               (HildonProgram *self)
 784 {
 785     HildonProgramPrivate *priv;
 786
 787     g_return_val_if_fail (HILDON_IS_PROGRAM (self), NULL);
 788
 789     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 790     g_assert (priv);
 791
 792     return priv->common_toolbar ? GTK_TOOLBAR (priv->common_toolbar) : NULL;
 793 }
 794
 795 /**
 796  * hildon_program_get_is_topmost:
 797  * @self: A #HildonWindow
 798  *
 799  * Returns whether one of the program's windows or dialogs is
 800  * currently activated by the window manager.
 801  *
 802  * Return value: %TRUE if a window or dialog is topmost, %FALSE
 803  * otherwise.
 804  **/
 805 gboolean
 806 hildon_program_get_is_topmost                   (HildonProgram *self)
 807 {
 808     HildonProgramPrivate *priv;
 809
 810     g_return_val_if_fail (HILDON_IS_PROGRAM (self), FALSE);
 811
 812     priv = HILDON_PROGRAM_GET_PRIVATE (self);
 813     g_assert (priv);
 814
 815     return priv->is_topmost;
 816 }
 817
 818 /**
 819  * hildon_program_go_to_root_window:
 820  * @self: A #HildonProgram
 821  *
 822  * Goes to the root window of the stack.
 823  *
 824  * Deprecated: See #HildonWindowStack
 825  */
 826 void
 827 hildon_program_go_to_root_window                (HildonProgram *self)
 828 {
 829     HildonWindowStack *stack = hildon_window_stack_get_default ();
 830     gint n = hildon_window_stack_size (stack);
 831     g_warning ("%s: this function is deprecated. Use hildon_window_stack_pop() instead.", __FUNCTION__);
 832     if (n > 1) {
 833         hildon_window_stack_pop (stack, n-1, NULL);
 834     }
 835 }