Editing Legacy Maemo 5 Documentation/Graphical UI Tutorial/Additions to GTK+

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

A Hildon application can use any GTK+ widget but in some cases you need to adapt the widgets to fit them perfectly.

Hildon provides a set of convenience functions to do that. The next section explains these additions

==Hildon size types==

Hildon defines the following sizes to be used as sizes for widgets such as buttons or entries in your Hildon application.

* <code>HILDON_SIZE_AUTO_WIDTH</code> (set to automatic width)
* <code>HILDON_SIZE_HALFSCREEN_WIDTH</code> (set to 50% screen width)
* <code>HILDON_SIZE_FULLSCREEN_WIDTH</code> (set to 100% screen width)
* <code>HILDON_SIZE_AUTO_HEIGHT</code> (set to automatic height)
* <code>HILDON_SIZE_FINGER_HEIGHT</code> (set to finger height)
* <code>HILDON_SIZE_THUMB_HEIGHT</code> (set to thumb height)
* <code>HILDON_SIZE_AUTO</code> (set to automatic width and automatic height)

Hildon widgets allow you to set their sizes in their construction functions, but in case you want to set the size of a GTK+ widget, Hildon also provides functions to do that:

<source lang="c">
GtkWidget*  hildon_gtk_button_new           (HildonSizeType size);
GtkWidget*  hildon_gtk_toggle_button_new    (HildonSizeType size);
GtkWidget*  hildon_gtk_radio_button_new     (HildonSizeType size,
                                              GSList *group);
GtkWidget*  hildon_gtk_radio_button_new_from_widget
                                            (HildonSizeType size,
                                             GtkRadioButton *radio_group_member);
</source>

==UI Modes==

Hildon defines two modes in the UI that change the way user interacts with certain widgets. The main purpose of these modes is to enable direct manipulation of items while still allowing the user to select single or multiple items. The following modes are supported:

===Normal mode===

Normal mode is the default mode. In lists and grids, tapping on an item causes a direct action. In views, this direct action could open a new subview to perform a certain action with the item.

===Edit mode===

Edit mode is used in Edit Mode views and in some dialogs. The purpose of this mode is providing single or multiple selection functionality in list or grid and providing standard UI for editing single content item.

Hildon provides the following functions to set mode for a treeview or icon view.

<source lang="c">
GtkWidget*  hildon_gtk_tree_view_new            (HildonUIMode mode);
GtkWidget*  hildon_gtk_tree_view_new_with_model (HildonUIMode mode,
                                                 GtkTreeModel *model);
void        hildon_gtk_tree_view_set_ui_mode    (GtkTreeView *treeview,
                                                 HildonUIMode mode);
GtkWidget*  hildon_gtk_icon_view_new            (HildonUIMode mode);
GtkWidget*  hildon_gtk_icon_view_new_with_model (HildonUIMode mode,
                                                 GtkTreeModel *model);
void        hildon_gtk_icon_view_set_ui_mode    (GtkIconView *iconview,
                                                HildonUIMode mode);
</source>

The enum <code>HildonUIMode</code> defines the following flags:

* <code>HILDON_UI_MODE_NORMAL</code>
* <code>HILDON_UI_MODE_EDIT</code>

When you use a list or grid in the edit mode inside a window you should use a <code>HildonEditToolbar</code> to control the edition and set the window to fullscreen, building an Edit subview. For more information about edit views, see the [[Legacy Maemo 5 Documentation/Graphical UI Tutorial/Toolbars|Toolbars chapter]]. In that chapter you can check an example of <code>HildonToolbar</code>, which uses the concepts explained above.

==Seek Bars==

The seek bars are a useful way to select a value from a range of predetermined values by adjusting the slider with a finger. These seek bars can be horizontal or vertical and are implemented using <code>GtkVScale</code> and <code>GtkHScale</code>. Thus, you can use this GTK+ widget in your Hildon application as seek bar, but use the following creation function instead of the GTK+ ones:

<source lang="c">
GtkWidget*  hildon_gtk_hscale_new           (void);
GtkWidget*  hildon_gtk_vscale_new           (void);
</source>
    
Scales created by using these constructors has a hildonized behavior, meaning that when user tap or click in a point of the bar immediately jumps to the desired position.

==Progress indicators==

A convenient way to inform the user that a long-term task is being performed is to show a progress indicator icon in the window or dialog title.

Hildon provides the following function to show a progress icon. This function applies to <code>HildonWindow</code> and <code>GtkDialog</code>.

<source lang="c">
void        hildon_gtk_window_set_progress_indicator (GtkWindow *window,
                                                      guint state);
</source>

The argument state must be 1 to show the indicator and 0 to hide it.

Here, a little example that sets a progress indicator in a <code>GtkDialog</code>.

Example 8.1. Adding a progress indicator to a dialog

<source lang="c">
#include <hildon/hildon.h>

int main( int   argc, char *argv[] )
{
  GtkWidget *dialog;

hildon_gtk_init (&argc, &argv);

dialog = gtk_dialog_new ();

gtk_window_set_title (GTK_WINDOW (dialog),
                        "Performing a long task");

gtk_widget_show  (dialog);

hildon_gtk_window_set_progress_indicator (GTK_WINDOW (dialog),
                                            1);
  
  gtk_dialog_run (GTK_DIALOG (dialog));

return 0;
}
</source>

Additionally, if you consider that additional text information should be given to the user, use an informational banner.

Another convenient way to indicate to the user that a long operation is being performed is using the [http://maemo.org/api_refs/5.0/beta/gtk/GtkProgressBar.html GtkProgressBar] widget.

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Templates used on this page:

Template:Ambox (view source) (semi-protected)
Template:Legacy documentation (view source) (semi-protected)

Retrieved from "http://wiki.maemo.org/Legacy_Maemo_5_Documentation/Graphical_UI_Tutorial/Additions_to_GTK%2B"

Personal tools

Navigation

Views

Editing Legacy Maemo 5 Documentation/Graphical UI Tutorial/Additions to GTK+

@@ Line 72: / Line 72: @@
 </source>
-Scales created by using these constructors has a hildonized behavior, meaning that when the user taps or clicks a point of the bar, it immediately jumps to the desired position.
+Scales created by using these constructors has a hildonized behavior, meaning that when user tap or click in a point of the bar immediately jumps to the desired position.
 ==Progress indicators==