Legacy Maemo 5 Documentation/Graphical UI Tutorial/Getting started

m (Stepping through Hello World)
(wikify slightly)
 
(5 intermediate revisions not shown)
Line 1: Line 1:
-
=Getting started=
+
{{Legacy documentation}}
 +
 
Before starting to develop your Hildon applications you need to get, install and properly configure the Maemo SDK. You can download and learn how to use the latest SDK in [http://maemo.org/development/sdks/ Maemo SDK Releases].
Before starting to develop your Hildon applications you need to get, install and properly configure the Maemo SDK. You can download and learn how to use the latest SDK in [http://maemo.org/development/sdks/ Maemo SDK Releases].
-
To begin our introduction to Hildon, we start with the simplest program possible - base.c. This program creates a window and has no way of exiting except to be killed by using the shell.
+
To begin our introduction to Hildon, we start with the simplest program possible - <code>base.c</code>. This program creates a window and has no way of exiting except to be killed by using the shell.
'''Example 1.1. Simple Hildon program'''
'''Example 1.1. Simple Hildon program'''
-
<tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;hildon/hildon.h&gt;</font></span>
+
<source lang="c">
-
<span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span> <span><font color="#009900">int</font></span>   argc<span><font color="#990000">,</font></span>
+
#include <hildon/hildon.h>
-
          <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>argv<span><font color="#990000">[]</font></span> <span><font color="#990000">)</font></span>
+
int main( int  argc,
-
<span><font color="#FF0000">{</font></span>
+
          char *argv[] )
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
{
-
  <span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&amp;</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>argv<span><font color="#990000">);</font></span>
+
  GtkWidget *window;
-
  <span>'''<span><font color="#000000">g_set_application_name</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Simplest example"</font></span><span><font color="#990000">);</font></span>
+
  hildon_gtk_init (&argc, &argv);
-
  window <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_new</font></span>'''</span> <span><font color="#990000">();</font></span>
+
  g_set_application_name ("Simplest example");
-
  <span>'''<span><font color="#000000">gtk_widget_show</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">);</font></span>
+
  window = hildon_window_new ();
-
  <span>'''<span><font color="#000000">gtk_main</font></span>'''</span> <span><font color="#990000">();</font></span>
+
  gtk_widget_show  (window);
-
  <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
  gtk_main ();
-
<span><font color="#FF0000">}</font></span>
+
  return 0;
-
</tt>
+
}
 +
</source>
To compile the program, use the following command:
To compile the program, use the following command:
 +
gcc base.c `pkg-config hildon-1 --cflags --libs` -o base
-
<div class="graybox">
+
All programs include <code>hildon/hildon.h</code> which declares the variables, functions, structures, and so on, that are used in your Hildon application.
-
  gcc base.c `pkg-config hildon-1 --cflags --libs` -o base
+
-
</div>
+
-
 
+
-
 
+
-
All programs include hildon/hildon.h which declares the variables, functions, structures, etc. that are used in your Hildon application.
+
The next line is necessary in every program:
The next line is necessary in every program:
-
<tt><span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&amp;</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>argv<span><font color="#990000">);</font></span></tt>
+
<source lang="c">
 +
hildon_gtk_init (&argc, &argv);
 +
</source>
This function replaces a call to <code>gtk_init()</code> and also initializes the Hildon library. This function also performs a call to <code>gtk_init()</code>. For more information on GTK+ initialization and arguments that can be passed to your application on the command line, see [http://library.gnome.org/devel/gtk/unstable/gtk-General.html#gtk-init GTK+ Reference Manual]. The next two lines of code create and display a window.
This function replaces a call to <code>gtk_init()</code> and also initializes the Hildon library. This function also performs a call to <code>gtk_init()</code>. For more information on GTK+ initialization and arguments that can be passed to your application on the command line, see [http://library.gnome.org/devel/gtk/unstable/gtk-General.html#gtk-init GTK+ Reference Manual]. The next two lines of code create and display a window.
-
<tt> window <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_new</font></span>'''</span> <span><font color="#990000">();</font></span>
+
<source lang="c">
-
  <span>'''<span><font color="#000000">gtk_widget_show</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">);</font></span>
+
window = hildon_window_new ();
-
</tt>
+
gtk_widget_show  (window);
 +
</source>
-
The HildonWindow used in this example represents a top-level window in the Hildon framework. It is derived from GtkWindow and provides additional commodities specific to the Hildon framework.
+
The <code>HildonWindow</code> used in this example represents a top-level window in the Hildon framework. It is derived from <code>GtkWindow</code> and provides additional commodities specific to the Hildon framework.
-
In very simple applications, HildonWindow could be enough. However, in most of the applications a HildonStackableWindow should be used.  
+
In very simple applications, <code>HildonWindow</code> can be enough. However, in most of the applications, use a <code>HildonStackableWindow</code>.
The <code>gtk_widget_show()</code> shows the widget (makes it visible) that would not be otherwise displayed.
The <code>gtk_widget_show()</code> shows the widget (makes it visible) that would not be otherwise displayed.
Line 49: Line 50:
The last line enters the GTK+ main processing loop.
The last line enters the GTK+ main processing loop.
-
<tt><span>'''<span><font color="#000000">gtk_widget_main</font></span>'''</span> <span><font color="#990000">();</font></span>  <span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hello</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>
+
<source lang="c">
-
                      gpointer  data <span><font color="#990000">)</font></span>
+
gtk_main ();
-
  <span><font color="#FF0000">{</font></span>
+
</source>
-
    <span>'''<span><font color="#000000">g_print</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Hello World!</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
+
-
  <span><font color="#FF0000">}</font></span>
+
-
</tt>
+
-
 
+
-
This call exists in every GTK+ application and therefore in every Hildon application. When control reaches this point, GTK+ sleeps waiting for X events (for example, button or key presses), timeouts, or file i/o notifications to occur. In our simple example, however, events are ignored.
+
 +
This call exists in every GTK+ application and therefore in every Hildon application. When control reaches this point, GTK+ sleeps waiting for X events (for example, button or key presses), timeouts, or file I/O notifications to occur. In our simple example, however, events are ignored.
==Hello World in Hildon ==
==Hello World in Hildon ==
 +
To begin our introduction to Hildon, we introduce the classic Hello World, Hildon style. This program creates a window with a widget (a button).
To begin our introduction to Hildon, we introduce the classic Hello World, Hildon style. This program creates a window with a widget (a button).
-
 
'''Example 1.2. Hildon Hello World program'''
'''Example 1.2. Hildon Hello World program'''
-
<tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span>                                       <span><font color="#FF0000">&lt;hildon/hildon.h&gt;</font></span>
+
<source lang="c">
-
+
#include                                        <hildon/hildon.h>
-
<span>''<span><font color="#9A1900">/* This is a callback function. The data arguments are ignored</font></span>''</span>
+
 
-
  <span>''<span><font color="#9A1900"> * in this example. More on callbacks . */</font></span>''</span>
+
/* This is a callback function. The data arguments are ignored
-
<span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hello</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>
+
  * in this example. More on callbacks . */
-
                    gpointer  data<span><font color="#990000">)</font></span>
+
static void hello (GtkWidget *widget,
-
<span><font color="#FF0000">{</font></span>
+
                  gpointer  data)
-
  <span>'''<span><font color="#000000">g_print</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Hello World!</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
+
{
-
<span><font color="#FF0000">}</font></span>
+
  g_print ("Hello World!\n");
-
+
}
-
<span><font color="#009900">int</font></span>
+
 
-
<span>'''<span><font color="#000000">main</font></span>'''</span>                                           <span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span>
+
int
-
                                                  <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span>
+
main                                            (int argc,
-
<span><font color="#FF0000">{</font></span>
+
                                                char **argv)
-
  HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>program<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
{
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
  HildonProgram *program;
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>button<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
  GtkWidget *window;
-
+
  GtkWidget *button;
-
  <span>''<span><font color="#9A1900">/* This is called in all Hildon applications. Arguments are parsed</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * from the command line and are returned to the application. */</font></span>''</span>
+
  /* This is called in all Hildon applications. Arguments are parsed
-
  <span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&amp;</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>argv<span><font color="#990000">);</font></span>
+
  * from the command line and are returned to the application. */
-
+
  hildon_gtk_init (&argc, &argv);
-
  <span>''<span><font color="#9A1900">/* Get an instance of HildonProgram. It is an object used to represent</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * an application running in the Hildon framework.              */</font></span>''</span>
+
  /* Get an instance of HildonProgram. It is an object used to represent
-
  program <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_program_get_instance</font></span>'''</span> <span><font color="#990000">();</font></span>
+
  * an application running in the Hildon framework.              */
-
+
  program = hildon_program_get_instance ();
-
  <span>''<span><font color="#9A1900">/* create a new hildon window */</font></span>''</span>
+
 
-
  window <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_new</font></span>'''</span> <span><font color="#990000">();</font></span>
+
  /* create a new hildon window */
-
+
  window = hildon_window_new ();
-
  <span>''<span><font color="#9A1900">/* Registers a window as belonging to the program */</font></span>''</span>
+
 
-
  <span>'''<span><font color="#000000">hildon_program_add_window</font></span>'''</span> <span><font color="#990000">(</font></span>program<span><font color="#990000">,</font></span> <span>'''<span><font color="#000000">HILDON_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">));</font></span>
+
  /* Registers a window as belonging to the program */
-
+
  hildon_program_add_window (program, HILDON_WINDOW (window));
-
  <span>''<span><font color="#9A1900">/* When the window is given the "delete_event" signal (this is given</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * by the window manager, usually by the "close" option, or on the</font></span>''</span>
+
  /* When the window is given the "delete_event" signal (this is given
-
<span>''<span><font color="#9A1900">  * titlebar), we ask it to call the delete_event () function</font></span>''</span>
+
  * by the window manager, usually by the "close" option, or on the
-
<span>''<span><font color="#9A1900">  * as defined above. The data passed to the callback</font></span>''</span>
+
  * titlebar), we ask it to call the delete_event () function
-
<span>''<span><font color="#9A1900">  * function is NULL and is ignored in the callback function. */</font></span>''</span>
+
  * as defined above. The data passed to the callback
-
  <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">),</font></span> <span><font color="#FF0000">"delete_event"</font></span><span><font color="#990000">,</font></span>
+
  * function is NULL and is ignored in the callback function. */
-
                    <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span>gtk_main_quit<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
  g_signal_connect (G_OBJECT (window), "delete_event",
-
+
                    G_CALLBACK (gtk_main_quit), NULL);
-
  <span>''<span><font color="#9A1900">/* Create a new hildon button with its title label set to "Hello world!",</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * also size and type of arrangement is set */</font></span>''</span>
+
  /* Create a new hildon button with its title label set to "Hello world!",
-
  button <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_button_new_with_text</font></span>'''</span> <span><font color="#990000">(</font></span>HILDON_SIZE_AUTO<span><font color="#990000">,</font></span>
+
  * also size and type of arrangement is set */
-
                                        HILDON_BUTTON_ARRANGEMENT_VERTICAL<span><font color="#990000">,</font></span>
+
  button = hildon_button_new_with_text (HILDON_SIZE_AUTO,
-
                                        <span><font color="#FF0000">"Hello world!"</font></span><span><font color="#990000">,</font></span>
+
                                        HILDON_BUTTON_ARRANGEMENT_VERTICAL,
-
                                        NULL<span><font color="#990000">);</font></span>
+
                                        "Hello world!",
-
+
                                        NULL);
-
  <span>''<span><font color="#9A1900">/* When the button is given the "clicked" signal, we ask it to call the</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * hello () function as defined above. The data passed to the callback</font></span>''</span>
+
  /* When the button is given the "clicked" signal, we ask it to call the
-
<span>''<span><font color="#9A1900">  * function is NULL and is ignored in the callback function. */</font></span>''</span>
+
  * hello () function as defined above. The data passed to the callback
-
  <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>button<span><font color="#990000">),</font></span> <span><font color="#FF0000">"clicked"</font></span><span><font color="#990000">,</font></span>
+
  * function is NULL and is ignored in the callback function. */
-
                    <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span>hello<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
  g_signal_connect (G_OBJECT (button), "clicked",
-
+
                    G_CALLBACK (hello), NULL);
-
  <span>''<span><font color="#9A1900">/* This packs the button into the window (a GTK+ container). */</font></span>''</span>
+
 
-
  <span>'''<span><font color="#000000">gtk_container_add</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_CONTAINER</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">),</font></span>
+
  /* This packs the button into the window (a GTK+ container). */
-
                      button<span><font color="#990000">);</font></span>
+
  gtk_container_add (GTK_CONTAINER (window),
-
+
                    button);
-
  <span>''<span><font color="#9A1900">/* The final step is to display this newly created widget</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * and all widgets it contains. */</font></span>''</span>
+
  /* The final step is to display this newly created widget
-
  <span>'''<span><font color="#000000">gtk_widget_show_all</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">));</font></span>
+
  * and all widgets it contains. */
-
+
  gtk_widget_show_all (GTK_WIDGET (window));
-
  <span>''<span><font color="#9A1900">/* All GTK+ applications must have a gtk_main(). Control ends here</font></span>''</span>
+
 
-
<span>''<span><font color="#9A1900">  * and waits for an event to occur (like a key press or</font></span>''</span>
+
  /* All GTK+ applications must have a gtk_main(). Control ends here
-
<span>''<span><font color="#9A1900">  * mouse event). */</font></span>''</span>
+
  * and waits for an event to occur (like a key press or
-
  <span>'''<span><font color="#000000">gtk_main</font></span>'''</span> <span><font color="#990000">();</font></span>
+
  * mouse event). */
-
+
  gtk_main ();
-
  <span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
 
-
<span><font color="#FF0000">}</font></span>
+
  return 0;
-
</tt>
+
}
 +
</source>
As you can see in this simple example, writing Hildon applications is slightly different from writing standard GTK+ applications. We are going to review these differences through the next chapters.
As you can see in this simple example, writing Hildon applications is slightly different from writing standard GTK+ applications. We are going to review these differences through the next chapters.
==Compiling Hello World ==
==Compiling Hello World ==
 +
To compile, use the following command:
To compile, use the following command:
-
<div class="graybox">
+
gcc hello-world.c `pkg-config hildon-1 --cflags --libs` -o hello
-
  gcc hello-world.c `pkg-config hildon-1 --cflags --libs` -o hello
+
-
</div>
+
This uses the program pkg-config, which can be obtained from [http://www.freedesktop.org/wiki/Home Freedesktop]. The program reads the .pc files which come with Hildon to determine what compiler switches are needed to compile programs that use it. pkg-config hildon-1 -cflags outputs a list of include directories for the compiler to look in, and pkg-config hildon-1 -libs outputs the list of libraries for the compiler to link with and the directories to find them in. Although they could be used separately as `pkg-config hildon-1 -cflags` and `pkg-config hildon-1 -libs`, in the above example they were joined as a single instance because it is easier to understand.
This uses the program pkg-config, which can be obtained from [http://www.freedesktop.org/wiki/Home Freedesktop]. The program reads the .pc files which come with Hildon to determine what compiler switches are needed to compile programs that use it. pkg-config hildon-1 -cflags outputs a list of include directories for the compiler to look in, and pkg-config hildon-1 -libs outputs the list of libraries for the compiler to link with and the directories to find them in. Although they could be used separately as `pkg-config hildon-1 -cflags` and `pkg-config hildon-1 -libs`, in the above example they were joined as a single instance because it is easier to understand.
-
'''Note'''
+
N.B. Note that the type of single quote (back-tick) used in the compile command above is significant.
-
 
+
-
Note that the type of single quote used in the compile command above is significant.
+
==Stepping through Hello World ==
==Stepping through Hello World ==
Line 154: Line 149:
This section explains the Hello World example above step-by-step.
This section explains the Hello World example above step-by-step.
-
The following lines define the callback function that is called when the button is "clicked". We ignore both the widget and the data in this example, but usually developers would need to handle events from them.
+
The following lines define the callback function that is called when the button is clicked. We ignore both the widget and the data in this example, but usually developers would need to handle events from them.
-
<tt><span>'''<span><font color="#0000FF">static</font></span>'''</span> <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hello</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>
+
<source lang="c">
-
                      gpointer  data <span><font color="#990000">)</font></span>
+
static void hello( GtkWidget *widget,
-
  <span><font color="#FF0000">{</font></span>
+
                    gpointer  data )
-
    <span>'''<span><font color="#000000">g_print</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#FF0000">"Hello World!</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span>
+
{
-
  <span><font color="#FF0000">}</font></span>
+
  g_print ("Hello World!\n");
-
</tt>
+
}
 +
</source>
The following is the definition of the main function, similar to the standard main function you would find in any C program.
The following is the definition of the main function, similar to the standard main function you would find in any C program.
-
<tt>  <span><font color="#009900">int</font></span>
+
<source lang="c">
-
    <span>'''<span><font color="#000000">main</font></span>'''</span> <span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>**</nowiki></font></span>argv<span><font color="#990000">)</font></span><span><font color="#FF0000">{</font></span>
+
int
-
</tt>
+
main  (int argc, char **argv){
 +
</source>
-
The next lines of code declare pointers to an object of type HildonProgram which represents an application running in the Hildon framework. Pointers to the widgets which show the application are also declared.
+
The next lines of code declare pointers to an object of type <code>HildonProgram</code> which represents an application running in the Hildon framework. Pointers to the widgets which show the application are also declared.
-
<tt>  HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>program<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
<source lang="c">
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
HildonProgram *program;
-
  GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>button<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
GtkWidget *window;
-
</tt>
+
GtkWidget *button;
 +
</source>
To use Hildon, initialize it first. Initialization connects to the window system display, and parses some standard command line arguments.
To use Hildon, initialize it first. Initialization connects to the window system display, and parses some standard command line arguments.
-
<tt><span>'''<span><font color="#000000">hildon_gtk_init</font></span>'''</span> <span><font color="#990000">(&amp;</font></span>argc<span><font color="#990000">,</font></span> <span><font color="#990000">&amp;</font></span>argv<span><font color="#990000">);</font></span>
+
<source lang="c">
-
</tt>
+
hildon_gtk_init (&argc, &argv);
 +
</source>
-
Only one HildonProgram can be created per process. Use <code>hildon_program_get_instance()</code> to access it.
+
Only one <code>HildonProgram</code> can be created per process. Use <code>hildon_program_get_instance()</code> to access it.
-
<tt>program <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_program_get_instance</font></span>'''</span> <span><font color="#990000">();</font></span>
+
<source lang="c">
-
</tt>
+
program = hildon_program_get_instance ();
 +
</source>
-
In this simple example, a new HildonWindow is created. In cases with nested views, a HildonStackableWindow should be used.  
+
In this simple example, a new <code>HildonWindow</code> is created. In cases with nested views, use a <code>HildonStackableWindow</code>.
-
<tt>window <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_window_new</font></span>'''</span> <span><font color="#990000">();</font></span>
+
<source lang="c">
-
</tt>
+
window = hildon_window_new ();
 +
</source>
-
This call registers a window as belonging to the program. This allows applying program-wide settings to all the registered windows, such as, for example, assigning a common menu to all the registered windows by setting it to the program.
+
This call registers a window as belonging to the program. This allows applying program-wide settings to all the registered windows, such as assigning a common menu to all the registered windows by setting it to the program.
-
<tt><span>'''<span><font color="#000000">hildon_program_add_window</font></span>'''</span> <span><font color="#990000">(</font></span>program<span><font color="#990000">,</font></span> <span>'''<span><font color="#000000">HILDON_WINDOW</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">))</font></span>
+
<source lang="c">
-
</tt>
+
hildon_program_add_window (program, HILDON_WINDOW (window));
 +
</source>
-
The following code is an example of connecting a signal handler to an object, in this case, the window. The function <code>gtk_main_quit()</code> is set as a handler to the "delete_event" signal. The function tells GTK+ that it must exit from gtk_main when control is returned to it, making the program terminate.
+
The following code is an example of connecting a signal handler to an object, in this case, the window. The function <code>gtk_main_quit()</code> is set as a handler to the "<code>delete_event</code>" signal. The function tells GTK+ that it must exit from <code>gtk_main</code> when control is returned to it, making the program terminate.
-
<tt>  <span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">),</font></span> <span><font color="#FF0000">"delete_event"</font></span><span><font color="#990000">,</font></span>
+
<source lang="c">
-
                    <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span>gtk_main_quit<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
g_signal_connect (G_OBJECT (window), "delete_event",
-
</tt>
+
                G_CALLBACK (gtk_main_quit), NULL);
 +
</source>
-
This call creates a new HildonButton. This button allows to set two labels, one main label and another secondary one. You can also set the size of the button and the order of the labels. Notice that you can use GtkButton's in Hildon applications in case you don't need the additional features that Hildon provides.
+
This call creates a new <code>HildonButton</code>. This button allows to set two labels, one main label and another secondary one. You can also set the size of the button and the order of the labels. Notice that you can use <code>GtkButton</code>'s in Hildon applications in case you do not need the additional features that Hildon provides.
-
<tt> button <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">hildon_button_new_with_text</font></span>'''</span> <span><font color="#990000">(</font></span>HILDON_SIZE_AUTO<span><font color="#990000">,</font></span>
+
<source lang="c">
-
                                        HILDON_BUTTON_ARRANGEMENT_VERTICAL<span><font color="#990000">,</font></span>
+
button = hildon_button_new_with_text (HILDON_SIZE_AUTO,
-
                                        <span><font color="#FF0000">"Hello world!"</font></span><span><font color="#990000">,</font></span>
+
                                    HILDON_BUTTON_ARRANGEMENT_VERTICAL,
-
                                        NULL<span><font color="#990000">);</font></span>
+
                                    "Hello world!",
-
</tt>
+
                                    NULL);
 +
</source>
-
Here, a signal handler is attached to the newly created button so that when it emits the "clicked" signal, our <code>hello()</code> function is called. The data is ignored, so we simply pass in NULL to the <code>hello()</code> callback function. Obviously, the "clicked" signal is emitted when the button is pressed.
+
Here, a signal handler is attached to the newly created button so that when it emits the "<code>clicked</code>" signal, our <code>hello()</code> function is called. The data is ignored, so we simply pass in <code>NULL</code> to the <code>hello()</code> callback function. Obviously, the "<code>clicked</code>" signal is emitted when the button is pressed.
-
<tt><span>'''<span><font color="#000000">g_signal_connect</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">G_OBJECT</font></span>'''</span> <span><font color="#990000">(</font></span>button<span><font color="#990000">),</font></span> <span><font color="#FF0000">"clicked"</font></span><span><font color="#990000">,</font></span>
+
<source lang="c">
-
                    <span>'''<span><font color="#000000">G_CALLBACK</font></span>'''</span> <span><font color="#990000">(</font></span>hello<span><font color="#990000">),</font></span> NULL<span><font color="#990000">);</font></span>
+
g_signal_connect (G_OBJECT (button), "clicked",
-
</tt>
+
                    G_CALLBACK (hello), NULL);
 +
</source>
This packing call tells GTK+ to place the button in the window. For more information, see the Packing Widgets section of the [http://library.gnome.org/devel/gtk-tutorial/stable/ GTK+ 2.0] Tutorial.
This packing call tells GTK+ to place the button in the window. For more information, see the Packing Widgets section of the [http://library.gnome.org/devel/gtk-tutorial/stable/ GTK+ 2.0] Tutorial.
-
<tt><span>'''<span><font color="#000000">gtk_container_add</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_CONTAINER</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">),</font></span>
+
<source lang="c">
-
                      button<span><font color="#990000">);</font></span>
+
gtk_container_add (GTK_CONTAINER (window),
-
</tt>
+
                    button);
 +
</source>
-
Once everything is set up with all signal handlers in place and the button placed in the window, we ask GTK to "show" the widgets on the screen.
+
When everything is set up with all signal handlers in place and the button placed in the window, we ask GTK to "show" the widgets on the screen.
-
<tt><span>'''<span><font color="#000000">gtk_widget_show_all</font></span>'''</span> <span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span> <span><font color="#990000">(</font></span>window<span><font color="#990000">));</font></span>
+
<source lang="c">
-
</tt>
+
gtk_widget_show_all (GTK_WIDGET (window));
 +
</source>
And of course, we call <code>gtk_main()</code> which waits for events to come from the X server and calls on the widgets to emit signals when these events come.
And of course, we call <code>gtk_main()</code> which waits for events to come from the X server and calls on the widgets to emit signals when these events come.
-
<tt><span>'''<span><font color="#000000">gtk_main</font></span>'''</span> <span><font color="#990000">();</font></span>
+
<source lang="c">
-
</tt>
+
gtk_main ();
 +
</source>
And the final return. Control returns here after <code>gtk_main_quit()</code> is called.
And the final return. Control returns here after <code>gtk_main_quit()</code> is called.
-
<tt><span>'''<span><font color="#0000FF">return</font></span>'''</span> <span><font color="#993399">0</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span>
+
<source lang="c">
-
</tt>
+
return 0;
 +
</source>
 +
 
 +
<hr/>
 +
<table width=100%>
 +
<tr>
 +
<td width=30% align=left>
 +
Prev: [[{{BASEPAGENAME}}/Introduction|Introduction]]</td>
 +
<td align=center>Up: [[{{BASEPAGENAME}}|Table of Contents]]</td>
 +
<td width=30% align=right>
 +
Next: [[{{BASEPAGENAME}}/Windows_and_dialogs|Windows and Dialogs]]</td>
 +
</tr></table>

Latest revision as of 08:50, 15 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

Before starting to develop your Hildon applications you need to get, install and properly configure the Maemo SDK. You can download and learn how to use the latest SDK in Maemo SDK Releases.

To begin our introduction to Hildon, we start with the simplest program possible - base.c. This program creates a window and has no way of exiting except to be killed by using the shell.


Example 1.1. Simple Hildon program

#include <hildon/hildon.h>
int main( int   argc,
          char *argv[] )
{
  GtkWidget *window;
  hildon_gtk_init (&argc, &argv);
  g_set_application_name ("Simplest example");
  window = hildon_window_new ();
  gtk_widget_show  (window);
  gtk_main ();
  return 0;
}

To compile the program, use the following command:

gcc base.c `pkg-config hildon-1 --cflags --libs` -o base

All programs include hildon/hildon.h which declares the variables, functions, structures, and so on, that are used in your Hildon application.

The next line is necessary in every program:

hildon_gtk_init (&argc, &argv);

This function replaces a call to gtk_init() and also initializes the Hildon library. This function also performs a call to gtk_init(). For more information on GTK+ initialization and arguments that can be passed to your application on the command line, see GTK+ Reference Manual. The next two lines of code create and display a window.

window = hildon_window_new ();
gtk_widget_show  (window);

The HildonWindow used in this example represents a top-level window in the Hildon framework. It is derived from GtkWindow and provides additional commodities specific to the Hildon framework.

In very simple applications, HildonWindow can be enough. However, in most of the applications, use a HildonStackableWindow.

The gtk_widget_show() shows the widget (makes it visible) that would not be otherwise displayed.

The last line enters the GTK+ main processing loop.

gtk_main  ();

This call exists in every GTK+ application and therefore in every Hildon application. When control reaches this point, GTK+ sleeps waiting for X events (for example, button or key presses), timeouts, or file I/O notifications to occur. In our simple example, however, events are ignored.

[edit] Hello World in Hildon

To begin our introduction to Hildon, we introduce the classic Hello World, Hildon style. This program creates a window with a widget (a button).

Example 1.2. Hildon Hello World program

#include                                        <hildon/hildon.h>
 
/* This is a callback function. The data arguments are ignored
 * in this example. More on callbacks . */
static void hello (GtkWidget *widget,
                   gpointer   data)
{
  g_print ("Hello World!\n");
}
 
int
main                                            (int argc,
                                                 char **argv)
{
  HildonProgram *program;
  GtkWidget *window;
  GtkWidget *button;
 
  /* This is called in all Hildon applications. Arguments are parsed
   * from the command line and are returned to the application. */
  hildon_gtk_init (&argc, &argv);
 
  /* Get an instance of HildonProgram. It is an object used to represent
   * an application running in the Hildon framework.               */
  program = hildon_program_get_instance ();
 
  /* create a new hildon window */
  window = hildon_window_new ();
 
  /* Registers a window as belonging to the program */
  hildon_program_add_window (program, HILDON_WINDOW (window));
 
  /* When the window is given the "delete_event" signal (this is given
   * by the window manager, usually by the "close" option, or on the
   * titlebar), we ask it to call the delete_event () function
   * as defined above. The data passed to the callback
   * function is NULL and is ignored in the callback function. */
  g_signal_connect (G_OBJECT (window), "delete_event",
                    G_CALLBACK (gtk_main_quit), NULL);
 
  /* Create a new hildon button with its title label set to "Hello world!",
   * also size and type of arrangement is set */
  button = hildon_button_new_with_text (HILDON_SIZE_AUTO,
                                        HILDON_BUTTON_ARRANGEMENT_VERTICAL,
                                        "Hello world!",
                                        NULL);
 
  /* When the button is given the "clicked" signal, we ask it to call the
   * hello () function as defined above. The data passed to the callback
   * function is NULL and is ignored in the callback function. */
  g_signal_connect (G_OBJECT (button), "clicked",
                    G_CALLBACK (hello), NULL);
 
  /* This packs the button into the window (a GTK+ container). */
  gtk_container_add (GTK_CONTAINER (window),
                     button);
 
  /* The final step is to display this newly created widget
   * and all widgets it contains. */
  gtk_widget_show_all (GTK_WIDGET (window));
 
  /* All GTK+ applications must have a gtk_main(). Control ends here
   * and waits for an event to occur (like a key press or
   * mouse event). */
  gtk_main ();
 
  return 0;
}

As you can see in this simple example, writing Hildon applications is slightly different from writing standard GTK+ applications. We are going to review these differences through the next chapters.

[edit] Compiling Hello World

To compile, use the following command:

gcc hello-world.c `pkg-config hildon-1 --cflags --libs` -o hello

This uses the program pkg-config, which can be obtained from Freedesktop. The program reads the .pc files which come with Hildon to determine what compiler switches are needed to compile programs that use it. pkg-config hildon-1 -cflags outputs a list of include directories for the compiler to look in, and pkg-config hildon-1 -libs outputs the list of libraries for the compiler to link with and the directories to find them in. Although they could be used separately as `pkg-config hildon-1 -cflags` and `pkg-config hildon-1 -libs`, in the above example they were joined as a single instance because it is easier to understand.

N.B. Note that the type of single quote (back-tick) used in the compile command above is significant.

[edit] Stepping through Hello World

This section explains the Hello World example above step-by-step.

The following lines define the callback function that is called when the button is clicked. We ignore both the widget and the data in this example, but usually developers would need to handle events from them.

static void hello( GtkWidget *widget,
                     gpointer   data )
{
  g_print ("Hello World!\n");
}

The following is the definition of the main function, similar to the standard main function you would find in any C program.

int
main  (int argc, char **argv){

The next lines of code declare pointers to an object of type HildonProgram which represents an application running in the Hildon framework. Pointers to the widgets which show the application are also declared.

HildonProgram *program;
GtkWidget *window;
GtkWidget *button;

To use Hildon, initialize it first. Initialization connects to the window system display, and parses some standard command line arguments.

hildon_gtk_init (&argc, &argv);

Only one HildonProgram can be created per process. Use hildon_program_get_instance() to access it.

program = hildon_program_get_instance ();

In this simple example, a new HildonWindow is created. In cases with nested views, use a HildonStackableWindow.

window = hildon_window_new ();

This call registers a window as belonging to the program. This allows applying program-wide settings to all the registered windows, such as assigning a common menu to all the registered windows by setting it to the program.

hildon_program_add_window (program, HILDON_WINDOW (window));

The following code is an example of connecting a signal handler to an object, in this case, the window. The function gtk_main_quit() is set as a handler to the "delete_event" signal. The function tells GTK+ that it must exit from gtk_main when control is returned to it, making the program terminate.

g_signal_connect (G_OBJECT (window), "delete_event",
                 G_CALLBACK (gtk_main_quit), NULL);

This call creates a new HildonButton. This button allows to set two labels, one main label and another secondary one. You can also set the size of the button and the order of the labels. Notice that you can use GtkButton's in Hildon applications in case you do not need the additional features that Hildon provides.

button = hildon_button_new_with_text (HILDON_SIZE_AUTO,
                                     HILDON_BUTTON_ARRANGEMENT_VERTICAL,
                                     "Hello world!",
                                     NULL);

Here, a signal handler is attached to the newly created button so that when it emits the "clicked" signal, our hello() function is called. The data is ignored, so we simply pass in NULL to the hello() callback function. Obviously, the "clicked" signal is emitted when the button is pressed.

g_signal_connect (G_OBJECT (button), "clicked",
                    G_CALLBACK (hello), NULL);

This packing call tells GTK+ to place the button in the window. For more information, see the Packing Widgets section of the GTK+ 2.0 Tutorial.

gtk_container_add (GTK_CONTAINER (window),
                     button);

When everything is set up with all signal handlers in place and the button placed in the window, we ask GTK to "show" the widgets on the screen.

gtk_widget_show_all (GTK_WIDGET (window));

And of course, we call gtk_main() which waits for events to come from the X server and calls on the widgets to emit signals when these events come.

gtk_main ();

And the final return. Control returns here after gtk_main_quit() is called.

return 0;

Prev: Introduction Up: Table of Contents Next: Windows and Dialogs