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