PyMaemo/UI tutorial/Controls

(Information Notes)
(Confirmation Notes)
Line 265: Line 265:
Confirmation notes show an information text that is usually a question and two buttons labelled "Yes" and "No".
Confirmation notes show an information text that is usually a question and two buttons labelled "Yes" and "No".
-
To create a confirmation note with the text you specify and two buttons labelled "Yes"/"No", use <code>hildon_note_new_confirmation()</code> as follows:
+
To create a confirmation note with the text you specify and two buttons labelled "Yes"/"No", use <code>hildon.Note.add_buttons()</code> as follows:
'''Example 7.7. Example of a Hildon confirmation note'''
'''Example 7.7. Example of a Hildon confirmation note'''
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span>
+
    def show_confirmation_note(parent):
-
<span>'''<span><font color="#000000">show_confirmation_note</font></span>'''</span>                          <span><font color="#990000">(</font></span>GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>parent<span><font color="#990000">)</font></span>
+
        note = hildon.hildon_note_new_confirmation(parent, "Do you want foo ?")
-
<span><font color="#FF0000">{</font></span>
+
   
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>note<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
        response = gtk.Dialog.run(note)
-
    gint response<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
   
-
    note <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_note_new_confirmation</font></span>'''</span> <span><font color="#990000">(</font></span>parent<span><font color="#990000">,</font></span>
+
        if response == gtk.RESPONSE_DELETE_EVENT:
-
                                          <span><font color="#FF0000">"Do you want foo ?"</font></span><span><font color="#990000">);</font></span>
+
            print "show_information_note: gtk.RESPONSE_DELETE_EVENT"
-
    response <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>response <span><font color="#990000"><nowiki>==</nowiki></font></span> GTK_RESPONSE_DELETE_EVENT<span><font color="#990000">)</font></span>
+
-
      <span>'''<span><font color="#000000">g_debug</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"%s: GTK_RESPONSE_DELETE_EVENT"</font></span><span><font color="#990000">,</font></span> __FUNCTION__<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">gtk_object_destroy</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
</tt>
+
-
Alternatively, you can use <code>hildon_note_new_confirmation_add_buttons()</code> to create a confirmation note with custom buttons.
+
Alternatively, you can use <code>hildon.Note.add_buttons()</code> to create a confirmation note with custom buttons.
'''Example 7.8. Example of a Hildon copnfirmation note with custom buttons'''
'''Example 7.8. Example of a Hildon copnfirmation note with custom buttons'''
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span>
+
    def show_confirmation_note_with_buttons(parent):
-
<span>'''<span><font color="#000000">show_confirmation_note</font></span>'''</span>                          <span><font color="#990000">(</font></span>GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>parent<span><font color="#990000">)</font></span>
+
        note = hildon.hildon_note_new_confirmation(parent, "Do you want foo ?")
-
<span><font color="#FF0000">{</font></span>
+
        note.add_buttons("ACCEPT", gtk.RESPONSE_OK, \
-
    GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>note<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
                        "CANCEL", gtk.RESPONSE_CANCEL, \
-
    gint response<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
                        "DELETE", gtk.RESPONSE_DELETE_EVENT)
-
    note <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_note_new_confirmation_add_buttons</font></span>'''</span><span><font color="#990000">(</font></span>parent<span><font color="#990000">,</font></span>
+
   
-
                                                    <span><font color="#FF0000">"Do you want foo?"</font></span><span><font color="#990000">,</font></span>
+
        response = gtk.Dialog.run(note)
-
                                                    <span><font color="#FF0000">"ACCEPT"</font></span><span><font color="#990000">,</font></span> GTK_RESPONSE_OK<span><font color="#990000">,</font></span>
+
   
-
                                                    <span><font color="#FF0000">"CANCEL"</font></span><span><font color="#990000">,</font></span> GTK_RESPONSE_CANCEL<span><font color="#990000">,</font></span>
+
        if response == gtk.RESPONSE_DELETE_EVENT:
-
                                                    <span><font color="#FF0000">"DELETE"</font></span><span><font color="#990000">,</font></span> GTK_RESPONSE_DELETE_EVENT<span><font color="#990000">);</font></span>
+
            print "show_information_note: gtk.RESPONSE_DELETE_EVENT"
-
    response <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
    <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>response <span><font color="#990000"><nowiki>==</nowiki></font></span> GTK_RESPONSE_DELETE_EVENT<span><font color="#990000">)</font></span>
+
-
      <span>'''<span><font color="#000000">g_debug</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"%s: GTK_RESPONSE_DELETE_EVENT"</font></span><span><font color="#990000">,</font></span> __FUNCTION__<span><font color="#990000">);</font></span>
+
-
    <span>'''<span><font color="#000000">gtk_object_destroy</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
</tt>
+
-
 
+
-
'''Cancel Notes'''
+
-
 
+
-
A cancel note displays a text, a Cancel button and a progress bar. They are useful to tell users that a long task is in progress. Also, cancel notes allow users to cancel the task in progress.
+
-
 
+
-
Next example shows how to create a cancel note with a progress bar. Note that to control the progress bar, additional code is needed.
+
-
 
+
-
'''Example 7.9. Example of a Hildon cancel note with a progress bar'''
+
-
 
+
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span>
+
-
<span>'''<span><font color="#000000">show_information_note</font></span>'''</span>                          <span><font color="#990000">(</font></span>GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>parent<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>note
+
-
  GtkProgressBar <span><font color="#990000"><nowiki>*</nowiki></font></span>progressbar
+
-
  gint response<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
  progressbar <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_progress_bar_new</font><font color="#990000">()</font></span>'''
+
-
  note <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_note_new_cancel_with_progress_bar</font></span>'''</span> <span><font color="#990000">(</font></span>parent<span><font color="#990000">,</font></span>
+
-
                                                  <span><font color="#FF0000">"A large task is happening"</font></span>
+
-
                                                  <span><font color="#990000">progressbar</font></span><span><font color="#990000">);</font></span>
+
-
  response <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
  <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>response <span><font color="#990000"><nowiki>==</nowiki></font></span> GTK_RESPONSE_DELETE_EVENT<span><font color="#990000">)</font></span>
+
-
    <span>'''<span><font color="#000000">g_debug</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"%s: GTK_RESPONSE_DELETE_EVENT"</font></span><span><font color="#990000">,</font></span> __FUNCTION__<span><font color="#990000">);</font></span>
+
-
  <span>'''<span><font color="#000000">gtk_object_destroy</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>note<span><font color="#990000">));</font></span>
+
-
<span><font color="#FF0000">}</font></span>
+

Revision as of 17:53, 9 October 2009

Contents

Controls

Hildon provides a set of controls specially designed for touchscreens that allows to build simple and easy-to-use interfaces. This chapter explains how to use these widgets.


Buttons

A Hildon application can use several types of buttons. Hildon provides specialized buttons derived from GtkButton which provide additional commodities specific to the Hildon framework. Using GtkButtons and GtkToggleButtons is also recommended.

Hildon Button

HildonButton is a GtkButton which usually contains two labels, title and value. It can also include an image.

To create a HildonButton, use the following function:

   button = hildon.Button(size, arrangement, title=, value=)


Note that in the creation of a HildonButton you must indicate the value for the properties "size" and "arrangement", choosing a Hildon size and a horizontal or vertical arrangement of the labels.

You can set and retrieve both labels by using the following convenience functions:

   hildon.Button.set_title(title)
   hildon.Button.set_value(value)
   title = hildon.Button.get_title()
   value = hildon.Button.get_value()


Alternatively, use the following function to set both labels of a HildonButton:

   hildon.Button.set_text(title, value)

To add images to HildonButtons, use the following functions to set and retrieve the current image: hildon_button_set_image() and hildon_button_get_image().

You can also set the position of the image.

   hildon.Button.set_image_position(position)


Currently supported positions are gtk.POS_LEFT or gtk.POS_RIGHT.

The visual style (color, fonts, etc) of a HildonButton can be changed by using the function set_style(). Use hildon.BUTTON_STYLE_NORMAL to make it look like a normal HildonButton, or hildon.BUTTON_STYLE_PICKER to make it look like a HildonPickerButton.

The next simple example shows how to create a HildonButton, set the label text and add an image.

Example 7.1. Example of a Hildon button with a label and an image

   def create_button():
       # Create a hildon button
       button = hildon.Button(gtk.HILDON_SIZE_AUTO_WIDTH | gtk.HILDON_SIZE_FINGER_HEIGHT,
                              hildon.BUTTON_ARRANGEMENT_VERTICAL)
   
       # Set labels value
       button.set_text("Some title", "Some value")
   
       # Set image
       image = gtk.image_new_from_stock(gtk.STOCK_INFO, gtk.ICON_SIZE_BUTTON)
       button.set_image(image)
       button.set_image_position(gtk.POS_RIGHT)
   
       return button

Hildon Check Button

HildonCheckButton is a button that contains a label and a check box. The check box toggles between checked or unchecked.

To create a HildonCheckButton:

   button = hildon.CheckButton(size)


Note that, again, you must specify the size of the button.

You can retrieve or set the current state of the button with the following functions, respectively:

   is_active = hildon.CheckButton.get_active()
   hildon.CheckButton.set_active(is_active)


The signal "toggled" is emitted when the state of the button changes. A handler can be attached to this signal if a further action is required.

Here is a simple example which creates a check button and a simple callback to handle the signal "toggled".

Example 7.2. Example of a Hildon check button

   def button_toggled(checkbutton):
       if (checkbutton.get_active()):
          print "Button is active"
       else:
          print "Button is not active"
   
   def create_check_button():
       button = hildon.CheckButton(gtk.HILDON_SIZE_AUTO)
       button.set_label("Click me")
       button.connect("toggled", button_toggled)
       return button

Using Gtk Buttons and Toggles

As was said above, apart from Hildon specific buttons, use GtkButton and GtkToggleButton also in the Hildon framework.

GtkButton

If only a label is needed, you do not need to use HildonButtons and a GtkButton can be used instead. You can use it as you would do in a GTK application. The only change is the creation function that you must use:

   button = hildon.GtkButton(size)

This alternative constructor allows you to set a Hildon size for the newly create function.

GtkToggleButton

To create a GtkToggleButton in a Hildon application you should use:

   togglebutton = hildon.GtkToggleButton(size)

GtkRadioButton

To create a GtkRadioButton in a Hildon application, use:

   radiobutton = hildon.GtkRadioButton(size, group)


The most common use case of this type of buttons in a Hildon application is as filters in a application menu. For more information, see section Touch View Menu.

Text display and handling

Text entry fields are used for entering one or more lines of plain text. Use a HildonEntry for a single-line text input or HildonTextView if you need a multi-line text input.

Hildon Text Entry

The HildonEntry is a GTK+ widget which represents a text entry. It is derived from the GtkEntry widget and provides additional commodities specific to the Hildon framework.

The main additional feature is a placeholder text to display if the entry is empty and not in focus.

Creating a new HildonEntry:

   entry = hildon.Entry(size)


Note that the creation function needs to specify a size from HildonSizeType.

The placeholder is stored as a property. To set it, use the following convenience function:

   hildon.Entry.set_placeholder(text)


Here's a very simple example showing how to create a HindonEntry.

Example 7.3. Example of a Hildon entry

   def create_entry():
       entry = hildon.Entry(gtk.HILDON_SIZE_AUTO)
       entry.set_placeholder("First name")
       return entry

Hildon Text Area

The HildonTextView is a GTK+ widget which represents a text area in Hildon applications. It is derived from the GtkTextView widget and provides additional commodities specific to the Hildon framework.

Create a HildonTextView:

   textview = hildon.TextView()


Like for the HildonTextEntry presented above, you can store a placeholder as well using the function.

   hildon.TextView.set_placeholder(text)


The text that is being edited with a HildonTextView is represented by a object GtkTextBuffer. The following functions can be used to set and retrieve the buffer associated with a HildonTextView.

   hildon.TextView.set_buffer(buffer)
   textbuffer = hildon.TextView.get_buffer()


Here is an example that shows how to create a HildonTextView and how to set its placeholder. Also, the buffer is retrieved and a function is set as a handler to the "changed" of the buffer. The handler simply gets the text from the HildonTextView's buffer and prints it.

Example 7.4. Example of a Hildon text view with a placeholder

   def text_changed(buffer):
       start = buffer.get_start_iter()
   
       end = buffer.get_end_iter()
       text = buffer.get_text(start, end, false)
   
       print text
   
   def create_text_view():
       text_view = hildon.TextView()
       text_view.set_placeholder("Type some text here")
   
       buffer = text_view.get_buffer()
       buffer.connect("changed", text_changed)
   
       return text_view

Warning

Although HildonTextView is derived from GtkTextView, gtk_text_view_get_buffer() and gtk_text_view_set_buffer() must never be used to get/set the buffer in this widget, hildon_text_view_get_buffer() and hildon_text_view_set_buffer() must be used instead.


Notification widgets

To cover the main use cases regarding notification of users, Hildon provides banners and notes. Banner widgets display a text information during a certain period of time. Notes are specialized GtkDialogs that need a small amount of input from the user.

Banners

A HildonBanner is useful to display information which does not need any user response. This widget automatically disappears after a certain time period.

To create and show a banner, use the following function:

   banner = hildon.hildon_banner_show_information(widget, icon_name, text)
   
   banner = hildon.hildon_banner_show_information_with_markup(widget, icon_name, markup)


All functions above require a widget as an argument that must be a pointer to the owner widget of the banner. Usually, the owner is the window that represents the currently displayed view.

Function show_information() shows a banner with the given text.

Function show_informationf() shows a banner which displays the text given by the printf-like formated string applied to the parameters that the rest of the function's arguments represent.

You can also apply a Pango markup and add some attributes to the displayed text. To do that, either use show_information_with_markup() to create the banner or setup the markup by calling set_markup() after the initialization

Warning

Currently, icons are not displayed in banners, so any value that you pass as the icon_name is ignored.

The period of time after the banner automatically disappear is stored in the property "timeout" (in miliseconds). A convenience function to set this property is provided:

hildon.Banner.set_timeout(timeout)

Here is a simple example showing how to setup and show an informational banner.

Example 7.5. Setting up an informational banner

   # Create a banner with a markup
   banner = hildon.Banner.show_information_with_markup(widget, None,   "Information banner")
   banner.set_timeout(9000)

Note

Only one timed banner can exist for each window in your application. If you spawn a new banner before the previous one has timed out, the first one is replaced.

Notes

HildonNotes are GtkDialogs designed to request a small amount of input from users. Usually, notes show an information text and buttons to confirm and cancel, for example, according to their type.

Unlike banners, notes always need a user action, that is, notes do not disappear automatically after a period of time.

The HildonNote widget provides functions to create and show different types of notes: information notes, confirmation notes and cancel notes.

   def hildon_note_new_information(parent, description)
   def hildon_note_new_information_with_icon_name(parent, description, icon_name)
   def hildon_note_new_confirmation(parent, description)
   def hildon_note_new_confirmation_with_icon_name(parent, description,  icon_name)
   def hildon_note_new_cancel_with_progress_bar(parent, description, progressbar)

Every function to create notes receives as a parameter the parent window of the newly created note. This is important in order to allow the window manager to handle the windows properly.

Information Notes

Information notes are used to show an information to the users. This note disappears when user taps outside the note's area. Otherwise the note remains visible.

Here is an example of how to show an information note and handle the user's answer.

Example 7.6. Example of a Hildon information note

   def show_information_note(parent):
       note = hildon.hildon_note_new_information(parent, \
           "Lorem ipsum dolor sit amet, consectetur adipiscing elit." \
           "Maecenas tristique dictum est. Aenean rhoncus aliquam mi." \
           "In hac habitasse platea dictumst.")
   
       response = gtk.Dialog.run(note)
   
       if response == gtk.RESPONSE_DELETE_EVENT:
           print "show_information_note: gtk.RESPONSE_DELETE_EVENT"

Confirmation Notes

Confirmation notes show an information text that is usually a question and two buttons labelled "Yes" and "No".

To create a confirmation note with the text you specify and two buttons labelled "Yes"/"No", use hildon.Note.add_buttons() as follows:

Example 7.7. Example of a Hildon confirmation note

    def show_confirmation_note(parent):
       note = hildon.hildon_note_new_confirmation(parent, "Do you want foo ?")
   
       response = gtk.Dialog.run(note)
   
       if response == gtk.RESPONSE_DELETE_EVENT:
           print "show_information_note: gtk.RESPONSE_DELETE_EVENT"

Alternatively, you can use hildon.Note.add_buttons() to create a confirmation note with custom buttons.

Example 7.8. Example of a Hildon copnfirmation note with custom buttons

    def show_confirmation_note_with_buttons(parent):
       note = hildon.hildon_note_new_confirmation(parent, "Do you want foo ?")
       note.add_buttons("ACCEPT", gtk.RESPONSE_OK, \
                        "CANCEL", gtk.RESPONSE_CANCEL, \
                        "DELETE", gtk.RESPONSE_DELETE_EVENT)
   
       response = gtk.Dialog.run(note)
   
       if response == gtk.RESPONSE_DELETE_EVENT:
           print "show_information_note: gtk.RESPONSE_DELETE_EVENT"