PyMaemo/UI tutorial/Getting started

(add link to C documentation)
 
(3 intermediate revisions not shown)
Line 1: Line 1:
-
=Getting started=
+
{{main|Legacy Maemo 5 Documentation/Graphical UI Tutorial/Getting started}}
 +
 
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.py. This program creates a window and has no way of exiting except to be killed by using the shell.
+
==Introduction==
 +
To begin our introduction to Hildon, we start with the simplest program possible - <code>base.py</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'''
 +
<source lang="python">
 +
# Based on C code from:
 +
# "Hildon Tutorial" version 2009-04-28
 +
# Example 1.1, "Simple Hildon program"
-
    # Based on C code from:
+
import gtk
-
     # "Hildon Tutorial" version 2009-04-28
+
import hildon
-
    # Example 1.1, "Simple Hildon program"
+
 
 +
def main():
 +
     gtk.set_application_name("Simplest example")
      
      
-
     import gtk
+
     window = hildon.Window()
-
     import hildon
+
     window.show()
      
      
-
     def main():
+
     gtk.main()
-
        gtk.set_application_name("Simplest example")
+
   
-
       
+
if __name__ == "__main__":
-
        window = hildon.Window()
+
    main()
-
        window.show()
+
</source>
-
       
+
-
        gtk.main()
+
-
       
+
-
    if __name__ == "__main__":
+
-
        main()
+
-
 
+
To run the program you can use:
To run the program you can use:
-
    run-standalone.sh python2.5 base.py
+
run-standalone.sh python2.5 base.py
-
 
+
All programs will import <code>hildon</code> which declares the variables, functions, structures, etc. that will be used in your Hildon application.
-
All programs will import hildon which declares the variables, functions, structures, etc. that will be used in your Hildon application.
+
The next two lines of code create and display a window.
The next two lines of code create and display a window.
-
 
+
<source lang="python">
     window = hildon.Window()
     window = hildon.Window()
     window.show()
     window.show()
 +
</source>
 +
The <code>hildon.Window</code> used in this example represents a top-level window in the Hildon framework. It is derived from <code>gtk.Window</code> and provides additional commodities specific to the Hildon framework.
-
The hildon.Window used in this example represents a top-level window in the Hildon framework. It is derived from gtk.Window and provides additional commodities specific to the Hildon framework.
+
In very simple applications, <code>hildon.Window</code> could be enough. However, in most of the applications a <code>hildon.StackableWindow</code> should be used. Next chapters will clarify this.
-
In very simple applications, hildon.Window could be enough. However, in most of the applications a hildon.StackableWindow should be used. Next chapters will clarify this.
+
The <code>show()</code> shows the widget (makes it visible) that would not be otherwise displayed.
-
 
+
-
The show() shows the widget (makes it visible) that would not be otherwise displayed.
+
The last line enters the GTK+ main processing loop.
The last line enters the GTK+ main processing loop.
-
 
+
<source lang="python">
     gtk.main();
     gtk.main();
-
 
+
</source>
This call can be found in every GTK+ application and therefore, in every Hildon application. When control reaches this point, GTK+ will sleep waiting for X events (such as button or key presses), timeouts, or file IO notifications to occur. In our simple example, however, events are ignored.
This call can be found in every GTK+ application and therefore, in every Hildon application. When control reaches this point, GTK+ will sleep waiting for X events (such as button or key presses), timeouts, or file IO notifications to occur. In our simple example, however, events are ignored.
Line 56: Line 57:
'''Example 1.2. Hildon Hello World program'''
'''Example 1.2. Hildon Hello World program'''
 +
<source lang="python">
 +
# Based on C code from:
 +
# "Hildon Tutorial" version 2009-04-28
 +
# Example 1.2, "Hildon Hello World program"
-
    # Based on C code from:
+
import gtk
-
    # "Hildon Tutorial" version 2009-04-28
+
import hildon
-
    # Example 1.2, "Hildon Hello World program"
+
-
   
+
-
    import gtk
+
-
    import hildon
+
-
   
+
-
    # This is a callback function. The data arguments are ignored in this example.
+
-
    def hello(widget, data):
+
-
        print "Hello World!"
+
-
   
+
-
    def main():
+
-
        # 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()
+
-
   
+
-
        # Registers a window as belonging to the program
+
-
        program.add_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 None and is ignored in the callback
+
-
        # function.
+
-
        window.connect("delete_event", gtk.main_quit, None)
+
-
   
+
-
        button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")
+
-
   
+
-
        # 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 None and is ignored in the callback function.
+
-
        button.connect("clicked", hello, None)
+
-
   
+
-
        # This packs the button into the window (a GTK+ container).
+
-
        window.add(button)
+
-
   
+
-
        # The final step is to display this newly created widget and all widgets it
+
-
        # contains.
+
-
        window.show_all()
+
-
   
+
-
        # 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()
+
-
   
+
-
    if __name__ == "__main__":
+
-
        main()
+
 +
# This is a callback function. The data arguments are ignored in this example.
 +
def hello(widget, data):
 +
    print "Hello World!"
-
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.
+
def main():
 +
    # Get an instance of HildonProgram. It is an object used to represent an
 +
    # application running in the Hildon framework.
 +
    program = hildon.Program.get_instance()
-
==Running Hello World ==
+
    # create a new hildon window
 +
    window = hildon.Window()
-
To run use:
+
    # Registers a window as belonging to the program
 +
    program.add_window(window)
-
     run-standalone.sh python2.5 hello-world.py
+
     # 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 None and is ignored in the callback
 +
    # function.
 +
    window.connect("delete_event", gtk.main_quit, None)
-
==Stepping through Hello World ==
+
    button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")
-
This section explains the Hello World example above step-by-step.
+
    # 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 None and is ignored in the callback function.
 +
    button.connect("clicked", hello, None)
-
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.
+
    # This packs the button into the window (a GTK+ container).
 +
    window.add(button)
-
     def hello(widget, data):
+
     # The final step is to display this newly created widget and all widgets it
-
        print "Hello World!"
+
    # contains.
 +
    window.show_all()
 +
    # 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()
-
Here starts the definition of the main function like it is usually done in programs written in Python.
+
if __name__ == "__main__":
 +
    main()
 +
</source>
-
    if __name__ == "__main__":
+
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.
-
        main()
+
-
Before using Hildon, it is needed to import it. This import connects to the window system display.
+
===Running Hello World===
-
  import hildon
+
To run use:
-
Only one HildonProgram can be created per process. Use <code>hildon.Program.get_instance()</code> to access it.
+
run-standalone.sh python2.5 hello-world.py
-
    program = hildon.Program.get_instance()
+
===Stepping through Hello World===
-
In this simple example, a new HildonWindow is created. In cases with nested views, use a HildonStackableWindow.  
+
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.
 +
<source lang="python">
 +
def hello(widget, data):
 +
    print "Hello World!"
 +
</source>
 +
Here starts the definition of the main function like it is usually done in programs written in Python.
 +
<source lang="python">
 +
if __name__ == "__main__":
 +
    main()
 +
</source>
 +
Before using Hildon, it needs to be imported. This import connects to the window system display.
 +
<source lang="python">
 +
import hildon
 +
</source>
 +
Only one <code>HildonProgram</code> can be created per process. Use <code>hildon.Program.get_instance()</code> to access it.
 +
<source lang="python">
 +
    program = hildon.Program.get_instance()
 +
</source>
 +
In this simple example, a new <code>HildonWindow</code> is created. In cases with nested views, use a <code>HildonStackableWindow</code>.
 +
<source lang="python">
     window = hildon.Window()
     window = hildon.Window()
-
 
+
</source>
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.
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.
-
 
+
<source lang="python">
     program.add_window(window)
     program.add_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. This function tells GTK+ that it must exit from <code>gtk.main()</code> 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 gtk.main_quit() is set as a handler to the “delete_event” signal. This function tells GTK+ that it must exit from gtk.main() when control is returned to it, making the program terminate.
+
<source lang="python">
-
 
+
   window.connect("delete_event", gtk.main_quit)
   window.connect("delete_event", gtk.main_quit)
-
 
+
</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 do not 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.
-
 
+
<source lang="python">
     button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")
     button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")
-
 
+
</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 "clicked" 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 "clicked" signal is emitted when the button is pressed.
-
 
+
<source lang="python">
     button.connect("clicked", hello, None)
     button.connect("clicked", hello, None)
-
 
+
</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/pygtk/stable/] 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/pygtk/stable/] Tutorial.
-
 
+
<source lang="python">
     window.add(button)
     window.add(button)
-
 
+
</source>
-
 
+
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.
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.
-
 
+
<source lang="python">
     window.show_all()
     window.show_all()
-
 
+
</source>
-
 
+
And of course, we call <code>gtk_main()</code> which waits for events to come from the X server and will call on the widgets to emit signals when these events come.
-
And of course, we call gtk_main() which waits for events to come from the X server and will call on the widgets to emit signals when these events come.
+
<source lang="python">
-
 
+
     gtk.main()
     gtk.main()
 +
</source>
[[Category:Python]]
[[Category:Python]]

Latest revision as of 10:54, 7 October 2010

Main article: Legacy Maemo 5 Documentation/Graphical UI Tutorial/Getting started


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.

Contents

[edit] Introduction

To begin our introduction to Hildon, we start with the simplest program possible - base.py. 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

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 1.1, "Simple Hildon program"
 
import gtk
import hildon
 
def main():
    gtk.set_application_name("Simplest example")
 
    window = hildon.Window()
    window.show()
 
    gtk.main()
 
if __name__ == "__main__":
    main()

To run the program you can use:

run-standalone.sh python2.5 base.py

All programs will import hildon which declares the variables, functions, structures, etc. that will be used in your Hildon application.

The next two lines of code create and display a window.

    window = hildon.Window()
    window.show()

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

In very simple applications, hildon.Window could be enough. However, in most of the applications a hildon.StackableWindow should be used. Next chapters will clarify this.

The 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 can be found in every GTK+ application and therefore, in every Hildon application. When control reaches this point, GTK+ will sleep waiting for X events (such as button or key presses), timeouts, or file IO 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 will create a window with a widget (a button).

Example 1.2. Hildon Hello World program

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 1.2, "Hildon Hello World program"
 
import gtk
import hildon
 
# This is a callback function. The data arguments are ignored in this example.
def hello(widget, data):
    print "Hello World!"
 
def main():
    # 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()
 
    # Registers a window as belonging to the program
    program.add_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 None and is ignored in the callback
    # function.
    window.connect("delete_event", gtk.main_quit, None)
 
    button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")
 
    # 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 None and is ignored in the callback function.
    button.connect("clicked", hello, None)
 
    # This packs the button into the window (a GTK+ container).
    window.add(button)
 
    # The final step is to display this newly created widget and all widgets it
    # contains.
    window.show_all()
 
    # 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()
 
if __name__ == "__main__":
    main()

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] Running Hello World

To run use:

run-standalone.sh python2.5 hello-world.py

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

def hello(widget, data):
    print "Hello World!"

Here starts the definition of the main function like it is usually done in programs written in Python.

if __name__ == "__main__":
    main()

Before using Hildon, it needs to be imported. This import connects to the window system display.

import hildon

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

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.

    program.add_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. This function tells GTK+ that it must exit from gtk.main() when control is returned to it, making the program terminate.

   window.connect("delete_event", gtk.main_quit)

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 GtkButtons in Hildon applications in case you do not need the additional features that Hildon provides.

    button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")

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.

    button.connect("clicked", hello, None)

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

    window.add(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.

    window.show_all()

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

    gtk.main()