Tutorial 1: Hello Elementary

This post is the first in a series I am going to be publishing about using elementary and python to develop applications. The source code for all of the examples I am providing can be found in a GitHub repository here. Looking to get help with development? - We have started a programming focused section of the Bodhi Linux forums here. Other great resources for getting help are the Enlightenment devel mailing list as well as #e on freenode IRC. I've also added the python elementary API documentation to the Bodhi website here.

Example 1:
Since most people (myself included) learn best through examples, let's dive right into the code. To start, we are going to be creating a simple window that displays some text to us. It will look something like this:

Including my comments explaining what each line of code does, it takes us less than 50 lines of code to get the above window on our screen. Let's take a look (you can also find the source code for this lesson here):

#Import the elementary library so we can use it
import elementary

#Import evas, used for resizing things
import evas

#A function that creates and shows an elementary window
def hello_elementary():
    #Creates a "Standard" elementary window. The first argument is the name of our window. The second argument is the title displayed on the window bar
    window = elementary.StandardWindow("hello world", "Hello Elementary")

    #callback_delete_request_add tells our window what to do when it's "close" button is pressed
    window.callback_delete_request_add(lambda o: elementary.exit())

    #Content for our window. Creates a "Label" object which display text in our window. Whenever we create an elementary object we must provide a parent window as input
    windytax = elementary.Label(window)

    #Tells our label object to change size based on the size of our window
    windytax.size_hint_weight_set(evas.EVAS_HINT_EXPAND, evas.EVAS_HINT_EXPAND)
    windytax.size_hint_align_set(evas.EVAS_HINT_FILL, evas.EVAS_HINT_FILL)

    #Define what text our window should display
    windytax.text = 'Hello Elementary!'

    #If we want to see our object we need to tell it to be shown
    windytax.show()

    #resize_object_add adds our Label object "windytax" to the window
    window.resize_object_add(windytax)

    #resize takes an ordered pair as input for the size for our window, the dimenions are pixel by pixel
    window.resize(300,300)

    #Finally lets tell our window object to show up just like we did with our label
    window.show()

#Runs when our script is run
if __name__ == "__main__":
    #Runs our function which creates our window
    hello_elementary()

    #Starts an elementary event loop which displays all elementary objects we've created. Our code stays at this point until elementary.exit() is called
    elementary.run()

    #Once elementary is done running lets shut everything off to finish the application
    elementary.shutdown()

In this example we create two elementary objects: A StandardWindow and a Label. The StandardWindow as you can guess is the window we are creating, while the Label is a child object that we add to our window to display.

Example 2:
We want our application to do much more than just display text (most of the time). So let's go ahead and add a couple more objects to our Hello Elementary application. Let's add a button that closes our application:

The full code for this application can be found here. I will now highlight what is different from our previous example.

def hello_elementary():
    ...

    #Create an elementary button object
    button = elementary.Button(window)

    #Set some text for our button
    button.text = "Goodbye Elementary"

    #callback_pressed_add tells our button a callback to run when our button is pressed, the first argument is the function run and the following arguments are things to pass to the callback
    button.callback_pressed_add(button_pressed, "argument1", "argument2")

    #Show our button
    button.show()

    #Since we now have multiple objects we want to display on our window, we can position these objects using an elementary box which is a container object that you can "pack" items into.

    #Create a box
    box = elementary.Box(window)

    #Tell our box to fill all open space in our window
    box.size_hint_weight_set(evas.EVAS_HINT_EXPAND, evas.EVAS_HINT_EXPAND)
    box.size_hint_align_set(evas.EVAS_HINT_FILL, evas.EVAS_HINT_FILL)
    
    #Show our box
    box.show()

    #Lets pack our label and then button into our box!
    box.pack_end(windytax)
    box.pack_end(button)

    #This time lets use our box  instead of just our label
    window.resize_object_add(box)

#Our callback when the button is pressed. The first argument for this function will be the elementary button object. The rest of the arguments are the custom things we passed above
def button_pressed(button, arg1, arg2):
    #Show the content of our arguments in terminal
    print arg1, arg2

    #Lets have our button close the application, so run:
    elementary.exit()

Example 2 adds two more elementary objects to our application - a Box and a Button. A Box is an elementary object that we use to hold other elementary objects to they are positioned how we want them inside our application window. You "pack" items into a box that is either vertical (default) or horizontal. A Button is an object that can have text and/or images displayed on it that can fire a callback when pressed.

Resources for this Lesson:

• Hello Elementary
• StandardWindow
• Label
• Box
• Button

~Jeff Hoogland