HildonProgram

HildonProgram — Application abstraction in the Hildon framework.

Synopsis


#include <hildon/hildon.h>

                    HildonProgram;
HildonProgram*      hildon_program_get_instance         (void);
void                hildon_program_add_window           (HildonProgram *self,
                                                         HildonWindow *window);
void                hildon_program_remove_window        (HildonProgram *self,
                                                         HildonWindow *window);
void                hildon_program_set_can_hibernate    (HildonProgram *self,
                                                         gboolean can_hibernate);
gboolean            hildon_program_get_can_hibernate    (HildonProgram *self);
void                hildon_program_set_common_menu      (HildonProgram *self,
                                                         GtkMenu *menu);
GtkMenu*            hildon_program_get_common_menu      (HildonProgram *self);
void                hildon_program_set_common_app_menu  (HildonProgram *self,
                                                         HildonAppMenu *menu);
HildonAppMenu*      hildon_program_get_common_app_menu  (HildonProgram *self);
void                hildon_program_set_common_toolbar   (HildonProgram *self,
                                                         GtkToolbar *toolbar);
GtkToolbar*         hildon_program_get_common_toolbar   (HildonProgram *self);
gboolean            hildon_program_get_is_topmost       (HildonProgram *self);
HildonStackableWindow* hildon_program_pop_window_stack  (HildonProgram *self);
HildonStackableWindow* hildon_program_peek_window_stack (HildonProgram *self);
void                hildon_program_go_to_root_window    (HildonProgram *self);

Object Hierarchy

  GObject
   +----HildonProgram

Properties

  "can-hibernate"            gboolean              : Read / Write
  "is-topmost"               gboolean              : Read

Description

HildonProgram is an object used to represent an application running in the Hildon framework.

Applications can have one or more HildonWindows. These can be registered in the HildonProgram with hildon_program_add_window(), and can be unregistered similarly with hildon_program_remove_window().

HildonProgram provides the programmer with commodities such as applying a common toolbar and menu to all registered HildonWindows. This is done with hildon_program_set_common_menu(), hildon_program_set_common_app_menu() and hildon_program_set_common_toolbar().

HildonProgram is also used to apply program-wide properties that are specific to the Hildon framework. For instance hildon_program_set_can_hibernate() sets whether or not an application can be set to hibernate by the Hildon task navigator, in situations of low memory.

Example 2. 

HildonProgram *program;
HildonWindow *window1;
HildonWindow *window2;
GtkToolbar *common_toolbar, *window_specific_toolbar;
HildonAppMenu *menu;

program = HILDON_PROGRAM (hildon_program_get_instance ());

window1 = HILDON_WINDOW (hildon_window_new ());
window2 = HILDON_WINDOW (hildon_window_new ());

common_toolbar = create_common_toolbar ();
window_specific_toolbar = create_window_specific_toolbar ();

menu = create_menu ();

hildon_program_add_window (program, window1);
hildon_program_add_window (program, window2);

hildon_program_set_common_app_menu (program, menu);

hildon_program_set_common_toolbar (program, common_toolbar);
hildon_window_add_toolbar (window1, window_specific_toolbar);

hildon_program_set_can_hibernate (program, TRUE);


Details

HildonProgram

typedef struct _HildonProgram HildonProgram;

hildon_program_get_instance ()

HildonProgram*      hildon_program_get_instance         (void);

Returns the HildonProgram for the current process. The object is created on the first call. Note that you're not supposed to unref the returned object since it's not reffed in the first place.

Returns : the HildonProgram.

hildon_program_add_window ()

void                hildon_program_add_window           (HildonProgram *self,
                                                         HildonWindow *window);

Registers a HildonWindow as belonging to a given HildonProgram. This allows to apply program-wide settings as all the registered windows, such as hildon_program_set_common_menu(), hildon_program_set_common_app_menu() and hildon_program_set_common_toolbar().

self : The HildonProgram to which the window should be registered
window : A HildonWindow to be added

hildon_program_remove_window ()

void                hildon_program_remove_window        (HildonProgram *self,
                                                         HildonWindow *window);

Used to unregister a window from the program. Subsequent calls to hildon_program_set_common_menu(), hildon_program_set_common_app_menu() and hildon_program_set_common_toolbar() will not affect the window.

self : The HildonProgram to which the window should be unregistered
window : The HildonWindow to unregister

hildon_program_set_can_hibernate ()

void                hildon_program_set_can_hibernate    (HildonProgram *self,
                                                         gboolean can_hibernate);

Used to set whether or not the Hildon task navigator should be able to set the program to hibernation in case of low memory

self : The HildonProgram which can hibernate or not
can_hibernate : whether or not the HildonProgram can hibernate

hildon_program_get_can_hibernate ()

gboolean            hildon_program_get_can_hibernate    (HildonProgram *self);

Returns whether the HildonProgram is set to be support hibernation from the Hildon task navigator

self : The HildonProgram which can hibernate or not
Returns : TRUE if the program can hibernate, FALSE otherwise.

hildon_program_set_common_menu ()

void                hildon_program_set_common_menu      (HildonProgram *self,
                                                         GtkMenu *menu);

Sets a GtkMenu that will appear in all HildonWindows registered with the HildonProgram. Only one common GtkMenu can be set, further calls will detach the previous common GtkMenu. A HildonWindow can use its own GtkMenu with hildon_window_set_menu()

This method does not support HildonAppMenus. See hildon_program_set_common_app_menu() for that.

self : The HildonProgram in which the common menu should be used
menu : A GtkMenu to use as common menu for the program

hildon_program_get_common_menu ()

GtkMenu*            hildon_program_get_common_menu      (HildonProgram *self);

Returns the GtkMenu that was set as common menu for this HildonProgram.

self : The HildonProgram from which to retrieve the common menu
Returns : the GtkMenu or NULL of no common menu was set.

hildon_program_set_common_app_menu ()

void                hildon_program_set_common_app_menu  (HildonProgram *self,
                                                         HildonAppMenu *menu);

Sets a HildonAppMenu that will appear in all HildonWindows registered with the HildonProgram. Only one common HildonAppMenu can be set, further calls will detach the previous common HildonAppMenu. A HildonWindow can use its own HildonAppMenu with hildon_window_set_app_menu()

This method does not support GtkMenus. See hildon_program_set_common_menu() for that.

self : The HildonProgram in which the common menu should be used
menu : A HildonAppMenu to use as common menu for the program

Since 2.2

hildon_program_get_common_app_menu ()

HildonAppMenu*      hildon_program_get_common_app_menu  (HildonProgram *self);

Returns the HildonAppMenu that was set as common menu for this HildonProgram.

self : The HildonProgram from which to retrieve the common app menu
Returns : the HildonAppMenu or NULL of no common app menu was set.

Since 2.2

hildon_program_set_common_toolbar ()

void                hildon_program_set_common_toolbar   (HildonProgram *self,
                                                         GtkToolbar *toolbar);

Sets a GtkToolbar that will appear in all the HildonWindow registered to the HildonProgram. Only one common GtkToolbar can be set, further call will detach the previous common GtkToolbar. A HildonWindow can use its own GtkToolbar with hildon_window_add_toolbar(). Both HildonProgram and HildonWindow specific toolbars will be shown

self : The HildonProgram in which the common toolbar should be used
toolbar : A GtkToolbar to use as common toolbar for the program

hildon_program_get_common_toolbar ()

GtkToolbar*         hildon_program_get_common_toolbar   (HildonProgram *self);

Returns the GtkToolbar that was set as common toolbar for this HildonProgram.

self : The HildonProgram from which to retrieve the common toolbar
Returns : the GtkToolbar or NULL of no common toolbar was set.

hildon_program_get_is_topmost ()

gboolean            hildon_program_get_is_topmost       (HildonProgram *self);

Returns whether one of the program's windows or dialogs is currently activated by the window manager.

self : A HildonWindow
Returns : TRUE if a window or dialog is topmost, FALSE otherwise.

hildon_program_pop_window_stack ()

HildonStackableWindow* hildon_program_pop_window_stack  (HildonProgram *self);

Warning

hildon_program_pop_window_stack is deprecated and should not be used in newly-written code. Use hildon_window_stack_pop() instead

Pops a window from the stack.

self : A HildonProgram
Returns : A HildonStackableWindow, or NULL

Since 2.2

hildon_program_peek_window_stack ()

HildonStackableWindow* hildon_program_peek_window_stack (HildonProgram *self);

Warning

hildon_program_peek_window_stack is deprecated and should not be used in newly-written code. Use hildon_window_stack_peek() instead

self : A HildonProgram
Returns : A HildonStackableWindow, or NULL

Since 2.2

hildon_program_go_to_root_window ()

void                hildon_program_go_to_root_window    (HildonProgram *self);

Warning

hildon_program_go_to_root_window is deprecated and should not be used in newly-written code. See HildonWindowStack

Goes to the root window of the stack.

self : A HildonProgram

Since 2.2

Property Details

The "can-hibernate" property

  "can-hibernate"            gboolean              : Read / Write

Whether the program should be set to hibernate by the Task Navigator in low memory situation.

Default value: FALSE

The "is-topmost" property

  "is-topmost"               gboolean              : Read

Whether one of the program's window or dialog currently is activated by window manager.

Default value: FALSE

See Also

HildonWindow, HildonStackableWindow
Generated by GTK-Doc V1.10