Legacy Maemo 5 Documentation/Graphical UI Tutorial/Utilities - Revision history

imported_>amigadave: wikify slightly

2010-10-18T09:32:21Z

wikify slightly

imported_>amigadave: {{Legacy documentation}}

2010-02-12T09:45:34Z

← Older revision		Revision as of 09:45, 12 February 2010
Line 1:		Line 1:
			{{Legacy documentation}}

	= Utilities =		= Utilities =
	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.

imported_>msoini: Documentation/Maemo 5 Developer Guide/Graphical UI Tutorial/Utilities moved to Legacy Maemo 5 Documentation/Graphical UI Tutorial/Utilities: Phase out from Maemo Developer Guide, superceded by Official Nokia Forum documentation

2009-10-14T09:34:37Z

Documentation/Maemo 5 Developer Guide/Graphical UI Tutorial/Utilities moved to Legacy Maemo 5 Documentation/Graphical UI Tutorial/Utilities: Phase out from Maemo Developer Guide, superceded by Official Nokia Forum documentation

← Older revision	Revision as of 09:34, 14 October 2009
(No difference)

imported_>liox_lang_valid: /* Utilities */

2009-09-25T08:07:11Z

Utilities

← Older revision		Revision as of 08:07, 25 September 2009
Line 7:		Line 7:
	The HildonProgram provides the programmer with commodities including applying a common menu or toolbar to every HildonWindow registered to it.		The HildonProgram provides the programmer with commodities including applying a common menu or toolbar to every HildonWindow registered to it.

	~~In order to~~ apply a shared menu and toolbar, all windows ~~must be registered~~ as belonging to the program.		To apply a shared menu and toolbar, register all windows as belonging to the program.

	To register or unregister windows ~~you should~~ use the following functions:		To register or unregister windows, use the following functions:

	<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>		<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>
Line 48:		Line 48:

	===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.		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 the theme ~~is changed~~ the widget keeps the same logical font or color set by these functions.		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.

	<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>		<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>
Line 60:		Line 60:
	</tt>		</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.		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 ~~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.		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.

	===Finger Events===		===Finger Events===

imported_>bijjal: Documentation/Maemo 5 Developer Guide/Application Development/Utilities moved to Documentation/Maemo 5 Developer Guide/Graphical UI Tutorial/Utilities

2009-08-18T08:29:56Z

Documentation/Maemo 5 Developer Guide/Application Development/Utilities moved to Documentation/Maemo 5 Developer Guide/Graphical UI Tutorial/Utilities

← Older revision	Revision as of 08:29, 18 August 2009
(No difference)

imported_>bijjal: /* Utilities */

2009-08-17T10:07:35Z

Utilities

← Older revision		Revision as of 10:07, 17 August 2009
Line 1:		Line 1:
	= Utilities =		= Utilities =
	Apart from the widgets, Hildon provides a set of helper functions and objects. ~~The Program object~~		Apart from the widgets, Hildon provides a set of helper functions and objects.


	== The Program object ==		== The Program object ==

imported_>bijjal: /* The Program object */

2009-07-13T14:39:35Z

The Program object

← Older revision		Revision as of 14:39, 13 July 2009
Line 39:		Line 39:
	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 <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>
	</tt>		</tt>

	~~@@COMMENT@@[Here a simple example of use of the HildonProgram object.]~~



	==Sound utilities ==		==Sound utilities ==

imported_>danielwilms: 1 revision

2009-07-13T11:36:08Z

1 revision

← Older revision	Revision as of 11:36, 13 July 2009
(No difference)

imported_>wikiadmin: moved Maemo 5 Developer Guide/Application Development/Utilities to Documentation/Maemo 5 Developer Guide/Application Development/Utilities

2009-07-13T11:26:00Z

moved Maemo 5 Developer Guide/Application Development/Utilities to Documentation/Maemo 5 Developer Guide/Application Development/Utilities

New page

= Utilities =
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.

In order to apply a shared menu and toolbar, all windows must be registered as belonging to the program.

To register or unregister windows you should use the following functions:

<tt>void '''hildon_program_add_window''' (HildonProgram <nowiki>*</nowiki>self,
HildonWindow <nowiki>*</nowiki>window);
void '''hildon_program_remove_window''' (HildonProgram <nowiki>*</nowiki>self,
HildonWindow <nowiki>*</nowiki>window);
</tt>

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>void '''hildon_program_set_common_menu''' (HildonProgram <nowiki>*</nowiki>self,
GtkMenu <nowiki>*</nowiki>menu);
GtkMenu<nowiki>*</nowiki> '''hildon_program_get_common_menu''' (HildonProgram <nowiki>*</nowiki>self);
void '''hildon_program_set_common_app_menu''' (HildonProgram <nowiki>*</nowiki>self,
HildonAppMenu <nowiki>*</nowiki>menu);
HildonAppMenu<nowiki>*</nowiki> '''hildon_program_get_common_app_menu''' (HildonProgram <nowiki>*</nowiki>self);
void '''hildon_program_set_common_toolbar''' (HildonProgram <nowiki>*</nowiki>self,
GtkToolbar <nowiki>*</nowiki>toolbar);
GtkToolbar<nowiki>*</nowiki> '''hildon_program_get_common_toolbar''' (HildonProgram <nowiki>*</nowiki>self);
</tt>

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".

<tt>void '''hildon_program_set_can_hibernate''' (HildonProgram <nowiki>*</nowiki>self,
gboolean can_hibernate);
gboolean '''hildon_program_get_can_hibernate''' (HildonProgram <nowiki>*</nowiki>self);
</tt>

@@COMMENT@@[Here a simple example of use of the HildonProgram object.]

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

==Miscellaneous helper functions ==

===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.

<tt>gulong '''hildon_helper_set_logical_font''' (GtkWidget <nowiki>*</nowiki>widget,
'''const''' gchar <nowiki>*</nowiki>logicalfontname);
gulong '''hildon_helper_set_logical_color''' (GtkWidget <nowiki>*</nowiki>widget,
GtkRcFlags rcflags,
GtkStateType state,
'''const''' gchar <nowiki>*</nowiki>logicalcolorname);
</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.

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.

===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.

<tt>gboolean '''hildon_helper_event_button_is_finger''' (GdkEventButton <nowiki>*</nowiki>event);
</tt>

This function is rarely used in applications development.

===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.

<tt>void '''hildon_helper_set_thumb_scrollbar''' (GtkScrolledWindow <nowiki>*</nowiki>win,
gboolean thumb);
</tt>