Legacy Maemo 5 Documentation/Graphical UI Tutorial/Utilities

(wikify slightly)
 
(3 intermediate revisions not shown)
Line 1: Line 1:
-
= Utilities =
+
{{Legacy documentation}}
 +
 
Apart from the widgets, Hildon provides a set of helper functions and objects.  
Apart from the widgets, Hildon provides a set of helper functions and objects.  
== The Program object ==
== The Program object ==
-
Hildon provides an object to represent a whole application, the HildonProgramObject. This object provides several convenience functions that make it easier to develop Hildon applications.
 
-
The HildonProgram provides the programmer with commodities including applying a common menu or toolbar to every HildonWindow registered to it.
+
Hildon provides an object to represent a whole application, the <code>HildonProgram</code> object. This object provides several convenience functions that make it easier to develop Hildon applications.
-
In order to apply a shared menu and toolbar, all windows must be registered as belonging to the program.
+
The <code>HildonProgram</code> provides the programmer with commodities including applying a common menu or toolbar to every <code>HildonWindow</code> registered with it.
-
To register or unregister windows you should use the following functions:
+
To apply a shared menu and toolbar, register all windows as belonging to the program.
-
<tt><span><font color="#009900">void</font></span>       <span>'''<span><font color="#000000">hildon_program_add_window</font></span>'''</span>       <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
To register or unregister windows, use the following functions:
-
                                              HildonWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000">);</font></span>
+
 
-
<span><font color="#009900">void</font></span>       <span>'''<span><font color="#000000">hildon_program_remove_window</font></span>'''</span>   <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                                              HildonWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000">);</font></span>
+
void        hildon_program_add_window      (HildonProgram *self,
-
</tt>
+
                                            HildonWindow *window);
 +
void        hildon_program_remove_window    (HildonProgram *self,
 +
                                            HildonWindow *window);
 +
</source>
The following functions take effect over each registered window, providing a convenient way to set up common elements for each registered window in your application.
The following functions take effect over each registered window, providing a convenient way to set up common elements for each registered window in your application.
-
<tt><span><font color="#009900">void</font></span>           <span>'''<span><font color="#000000">hildon_program_set_common_menu</font></span>'''</span>       <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                                                      GtkMenu <span><font color="#990000"><nowiki>*</nowiki></font></span>menu<span><font color="#990000">);</font></span>
+
void          hildon_program_set_common_menu        (HildonProgram *self,
-
GtkMenu<span><font color="#990000"><nowiki>*</nowiki></font></span>       <span>'''<span><font color="#000000">hildon_program_get_common_menu</font></span>'''</span>       <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">);</font></span>
+
                                                      GtkMenu *menu);
-
<span><font color="#009900">void</font></span>           <span>'''<span><font color="#000000">hildon_program_set_common_app_menu</font></span>'''</span>   <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
GtkMenu*      hildon_program_get_common_menu        (HildonProgram *self);
-
                                                      HildonAppMenu <span><font color="#990000"><nowiki>*</nowiki></font></span>menu<span><font color="#990000">);</font></span>
+
void          hildon_program_set_common_app_menu    (HildonProgram *self,
-
HildonAppMenu<span><font color="#990000"><nowiki>*</nowiki></font></span> <span>'''<span><font color="#000000">hildon_program_get_common_app_menu</font></span>'''</span>   <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">);</font></span>
+
                                                      HildonAppMenu *menu);
-
<span><font color="#009900">void</font></span>           <span>'''<span><font color="#000000">hildon_program_set_common_toolbar</font></span>'''</span>     <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
HildonAppMenu* hildon_program_get_common_app_menu    (HildonProgram *self);
-
                                                      GtkToolbar <span><font color="#990000"><nowiki>*</nowiki></font></span>toolbar<span><font color="#990000">);</font></span>
+
void          hildon_program_set_common_toolbar    (HildonProgram *self,
-
GtkToolbar<span><font color="#990000"><nowiki>*</nowiki></font></span>   <span>'''<span><font color="#000000">hildon_program_get_common_toolbar</font></span>'''</span>     <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">);</font></span>
+
                                                      GtkToolbar *toolbar);
-
</tt>
+
GtkToolbar*    hildon_program_get_common_toolbar    (HildonProgram *self);
 +
</source>
-
HildonProgram also allows users to apply program-wide properties. For example, the property "can-hibernate" that specify whether the program should be set to hibernate by the Task Navigator in a low memory situation or not.
+
<code>HildonProgram</code> also allows users to apply program-wide properties. For example, the property "<code>can-hibernate</code>" that specify whether the program should be set to hibernate by the Task Navigator in a low memory situation or not.
-
The following convenience functions are provided to set and retrieve the value of the property "can-hibernate".
+
The following convenience functions are provided to set and retrieve the value of the property "<code>can-hibernate</code>".
-
<tt><span><font color="#009900">void</font></span>       <span>'''<span><font color="#000000">hildon_program_set_can_hibernate</font></span>'''</span>     <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                                                    gboolean can_hibernate<span><font color="#990000">);</font></span>
+
void        hildon_program_set_can_hibernate      (HildonProgram *self,
-
gboolean    <span>'''<span><font color="#000000">hildon_program_get_can_hibernate</font></span>'''</span>     <span><font color="#990000">(</font></span>HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>self<span><font color="#990000">);</font></span>
+
                                                  gboolean can_hibernate);
-
</tt>
+
gboolean    hildon_program_get_can_hibernate      (HildonProgram *self);
 +
</source>
==Sound utilities ==
==Sound utilities ==
-
Hildon provides the following function to play a sample. The function receives the sample file name as parameter and the volume level is controlled by the gconf variable /apps/osso/sound/system_alert_volume
 
-
void        hildon_play_system_sound        (const gchar *sample);
+
Hildon provides the following function to play a sample. The function receives the sample file name as parameter and the volume level is controlled by the gconf variable <code>/apps/osso/sound/system_alert_volume</code>
 +
<source lang="c">
 +
void        hildon_play_system_sound        (const gchar *sample);
 +
</source>
-
==Miscellaneous helper functions ==
+
== Miscellaneous helper functions ==
===Text Font and Colors===
===Text Font and Colors===
-
The following funtions allows you to set a font or color for the text diplayed by a certain widget. The size or color is identified by a logical name which should be defined by the GTK's rc files defined as part of the themes definition.
 
-
Because logical names are used to identify the colors and font, they are independent from the theme, meaning that if the theme is changed the widget keeps the same logical font or color set by these functions.
+
The following funtions allows you to set a font or color for the text diplayed by a certain widget. The size or color is identified by a logical name which must be defined by the GTK's rc files defined as part of the themes definition.
-
<tt>gulong      <span>'''<span><font color="#000000">hildon_helper_set_logical_font</font></span>'''</span>  <span><font color="#990000">(</font></span>GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>widget<span><font color="#990000">,</font></span>
+
Because logical names are used to identify the colors and font, they are independent from the theme, meaning that if you change the theme, the widget keeps the same logical font or color set by these functions.
-
                                              <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span>logicalfontname<span><font color="#990000">);</font></span>
+
-
gulong      <span>'''<span><font color="#000000">hildon_helper_set_logical_color</font></span>'''</span> <span><font color="#990000">(</font></span>GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>widget<span><font color="#990000">,</font></span>
+
-
                                              GtkRcFlags rcflags<span><font color="#990000">,</font></span>
+
-
                                              GtkStateType state<span><font color="#990000">,</font></span>
+
-
                                              <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span>logicalcolorname<span><font color="#990000">);</font></span>
+
-
</tt>
+
-
These functions achieve to keep the set logical font or color by connecting to "style-set" signal. The returned signal identifier can be used to disconnect the signal.
+
<source lang="c">
 +
gulong      hildon_helper_set_logical_font  (GtkWidget *widget,
 +
                                            const gchar *logicalfontname);
 +
gulong      hildon_helper_set_logical_color (GtkWidget *widget,
 +
                                            GtkRcFlags rcflags,
 +
                                            GtkStateType state,
 +
                                            const gchar *logicalcolorname);
 +
</source>
-
To set a logical color is necessary to pass in the GtkRcFlags and GtkStateType to indicate which color you want to modify. For example, to modify the foreground color of the widget during normal operations then set rcflags to GTK_RC_BG and state to GTK_STATE_NORMAL.
+
These functions keep the set logical font or color by connecting to "<code>style-set</code>" signal. Use the returned signal identifier to disconnect the signal.
 +
 
 +
To set a logical color, pass in the <code>GtkRcFlags</code> and <code>GtkStateType</code> to indicate which color you want to modify. For example, to modify the foreground color of the widget during normal operations then set rcflags to <code>GTK_RC_BG</code> and state to <code>GTK_STATE_NORMAL</code>.
===Finger Events===
===Finger Events===
 +
The following function can be in callbacks that handle button events to check if the given button event is a finger event, meaning that the event was emitted as a result of a push with the finger somewhere on the touchscreen.
The following function can be in callbacks that handle button events to check if the given button event is a finger event, meaning that the event was emitted as a result of a push with the finger somewhere on the touchscreen.
-
<tt>gboolean    <span>'''<span><font color="#000000">hildon_helper_event_button_is_finger</font></span>'''</span> <span><font color="#990000">(</font></span>GdkEventButton <span><font color="#990000"><nowiki>*</nowiki></font></span>event<span><font color="#990000">);</font></span>
+
<source lang="c">
-
</tt>
+
gboolean    hildon_helper_event_button_is_finger (GdkEventButton *event);
 +
</source>
-
This function is rarely used in applications development.
+
This function is rarely used in application development.
===Thumbable Scrollbars===
===Thumbable Scrollbars===
 +
The function showed bellow enables a thumb scrollbar on a given scrolled window, converting the existing normal scrollbar into a larger, finger-usable scrollbar that works without a stylus.
The function showed bellow enables a thumb scrollbar on a given scrolled window, converting the existing normal scrollbar into a larger, finger-usable scrollbar that works without a stylus.
-
<tt><span><font color="#009900">void</font></span>       <span>'''<span><font color="#000000">hildon_helper_set_thumb_scrollbar</font></span>'''</span> <span><font color="#990000">(</font></span>GtkScrolledWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>win<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                                                gboolean thumb<span><font color="#990000">);</font></span>
+
void        hildon_helper_set_thumb_scrollbar (GtkScrolledWindow *win,
-
</tt>
+
                                              gboolean thumb);
 +
</source>

Latest revision as of 09:32, 18 October 2010

Image:Ambox_content.png
This article is legacy documentation, and is superseded by Forum Nokia documentation.
The Forum Nokia documentation is available as the Hildon 2.2 UI style guide, Fremantle master layout guide and the Hildon 2.2 widget UI specification

Apart from the widgets, Hildon provides a set of helper functions and objects.

Contents

[edit] The Program object

Hildon provides an object to represent a whole application, the HildonProgram object. This object provides several convenience functions that make it easier to develop Hildon applications.

The HildonProgram provides the programmer with commodities including applying a common menu or toolbar to every HildonWindow registered with it.

To apply a shared menu and toolbar, register all windows as belonging to the program.

To register or unregister windows, use the following functions:

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

The following functions take effect over each registered window, providing a convenient way to set up common elements for each registered window in your application.

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

HildonProgram also allows users to apply program-wide properties. For example, the property "can-hibernate" that specify whether the program should be set to hibernate by the Task Navigator in a low memory situation or not.

The following convenience functions are provided to set and retrieve the value of the property "can-hibernate".

void        hildon_program_set_can_hibernate      (HildonProgram *self,
                                                   gboolean can_hibernate);
gboolean    hildon_program_get_can_hibernate      (HildonProgram *self);

[edit] Sound utilities

Hildon provides the following function to play a sample. The function receives the sample file name as parameter and the volume level is controlled by the gconf variable /apps/osso/sound/system_alert_volume

void        hildon_play_system_sound        (const gchar *sample);

[edit] Miscellaneous helper functions

[edit] Text Font and Colors

The following funtions allows you to set a font or color for the text diplayed by a certain widget. The size or color is identified by a logical name which must be defined by the GTK's rc files defined as part of the themes definition.

Because logical names are used to identify the colors and font, they are independent from the theme, meaning that if you change the theme, the widget keeps the same logical font or color set by these functions.

gulong      hildon_helper_set_logical_font  (GtkWidget *widget,
                                             const gchar *logicalfontname);
gulong      hildon_helper_set_logical_color (GtkWidget *widget,
                                             GtkRcFlags rcflags,
                                             GtkStateType state,
                                             const gchar *logicalcolorname);

These functions keep the set logical font or color by connecting to "style-set" signal. Use the returned signal identifier to disconnect the signal.

To set a logical color, pass in the GtkRcFlags and GtkStateType to indicate which color you want to modify. For example, to modify the foreground color of the widget during normal operations then set rcflags to GTK_RC_BG and state to GTK_STATE_NORMAL.

[edit] Finger Events

The following function can be in callbacks that handle button events to check if the given button event is a finger event, meaning that the event was emitted as a result of a push with the finger somewhere on the touchscreen.

gboolean    hildon_helper_event_button_is_finger (GdkEventButton *event);

This function is rarely used in application development.

[edit] Thumbable Scrollbars

The function showed bellow enables a thumb scrollbar on a given scrolled window, converting the existing normal scrollbar into a larger, finger-usable scrollbar that works without a stylus.

void        hildon_helper_set_thumb_scrollbar (GtkScrolledWindow *win,
                                               gboolean thumb);