HildonProgram

HildonProgram — An object that represents an application running in the Hildon framework.

Synopsis




            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_toolbar
                                            (HildonProgram *self,
                                             GtkToolbar *toolbar);
GtkToolbar* hildon_program_get_common_toolbar
                                            (HildonProgram *self);
gboolean    hildon_program_get_is_topmost   (HildonProgram *self);

Object Hierarchy


  GObject
   +----HildonProgram

Properties


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

Description

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

Such an application is thought to have one or more HildonWindow. These shall be registered to the HildonProgram with hildon_program_add_window, and can be unregistered similarly with hildon_program_remove_window.

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

The 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 *first_window;
HildonWindow *second_window;
GtkToolbar *common_toolbar, *window_specific_toolbar;
GtkMenu *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 (program, window1);
hildon_program_add (program, window2);

hildon_program_set_common_menu (program, menu);

hildon_program_set_common_toolbar (program, common_toolbar);
hildon_window_add_toolbar (first_window, 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 : 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.

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() and hildon_pogram_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() and hildon_pogram_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);

self : The HildonProgram which can hibernate or not
Returns : Whether or not this HildonProgram is set to be support hibernation from the Hildon task navigator

hildon_program_set_common_menu ()

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

Sets a GtkMenu that will appear in all the HildonWindow registered to the HildonProgram. Only one common GtkMenu can be set, further call will detach the previous common GtkMenu. A HildonWindow can use it's own GtkMenu with hildon_window_set_menu

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);

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

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_set_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);

self : The HildonProgram from which to retrieve the common toolbar
Returns : the GtkToolbar that was set as common toolbar for this HildonProgram, or NULL of no common menu was set.

hildon_program_get_is_topmost ()

gboolean    hildon_program_get_is_topmost   (HildonProgram *self);

self : A HildonWindow
Returns : Whether or not one of the program's window or dialog is currenltly activated by the window manager.

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