📝Hello world

The first app we’ll create will be a basic and generic “Hello World”. We’ll walk through the steps of creating folders to store our source code, compiling our first app, and pushing the project to a Git branch. Let’s begin.

Setting Up

Apps on elementary OS are organized into standardized directories contained in your project's "root" folder. Let's create a couple of these to get started:

1. Create your root folder called "gtk-hello"

2. Create a folder inside that one called "src". This folder will contain all of our source code.

Later on, We'll talk about adding other directories like "po" and "data". For now, this is all we need.

Gtk.Application

Now what you've been waiting for! We're going to create a window that contains a button. When pressed, the button will display the text "Hello World!" To do this, we're going to use a widget toolkit called GTK+ and the programming language Vala. Before we begin, we highly recommend that you do not copy and paste. Typing each section manually will help you to practice and remember. Let's get started:

Create a new file in Code and save it as "Application.vala" inside your "src" folder

In this file, we're going to create a special class called a Gtk.Application. Gtk.Application is a class that handles many important aspects of a Gtk app like uniqueness and the ID you need to identify your app to the notifications server. If you want some more details about Gtk.Application, check out Valadoc. For now, type the following in "Application.vala".

public class MyApp : Gtk.Application {
    public MyApp () {
        Object (
            application_id: "com.github.yourusername.yourrepositoryname",
            flags: ApplicationFlags.FLAGS_NONE
        );
    }

    protected override void activate () {
        var main_window = new Gtk.ApplicationWindow (this) {
            default_height = 300,
            default_width = 300,
            title = "Hello World"
        };
        main_window.show_all ();
    }

    public static int main (string[] args) {
        return new MyApp ().run (args);
    }
}

You'll notice that most of these property names are pretty straightforward. Inside MyApp () we set a couple of properties for our Gtk.Application object, namely our app's ID and flags. The naming scheme we used for our app's ID is called Reverse Domain Name Notation and will ensure that your app has a unique identifier. The first line inside the activate method creates a new Gtk.ApplicationWindow called main_window. The fourth line sets the window title that you see at the top of the window. We also must give our window a default size so that it does not appear too small for the user to interact with it. Then in our main () method we create a new instance of our Gtk.Applicationand run it.

Ready to test it out? Fire up your terminal and make sure you're in "~/Projects/gtk-hello/src". Then execute the following commands to compile and run your first Gtk+ app:

valac --pkg gtk+-3.0 Application.vala
./Application

Do you see a new, empty window called "Hello World"? If so, congratulations! If not, read over your source code again and look for errors. Also check the output of your terminal. Usually there is helpful output that will help you track down your mistake.

Now that we've defined a nice window, let's put a button inside of it. Add the following to your application at the beginning of the activate () function:

var button_hello = new Gtk.Button.with_label ("Click me!") {
    margin = 12
};

button_hello.clicked.connect (() => {
    button_hello.label = "Hello World!";
    button_hello.sensitive = false;
});

Then add this line right before main_window.show_all ():

main_window.add (button_hello);

Any ideas about what happened here?

• We've created a new Gtk.Button with the label "Click me!"

• Then we add a margin to the button so that it doesn't bump up against the sides of the window.

• We've said that if this button is clicked, we want to change the label to say "Hello World!" instead.

• We've also said that we want to make the button insensitive after it's clicked; We do this because clicking the button again has no visible effect

• Finally, we add the button to our Gtk.ApplicationWindow and declare that we want to show all of the window's contents.

Compile and run your application one more time and test it out. Nice job! You've just written your first Gtk+ app!

If you're having trouble, you can view the full example code here on GitHub

Pushing to GitHub

After we do anything significant, we must remember to push our code. This is especially important in collaborative development where not pushing your code soon enough can lead to unintentional forks and pushing too much code at once can make it hard to track down any bugs introduced by your code.

First we need to create a new repository on GitHub. Visit the new repository page and create a new repository for your code.

Open Terminal and make sure you're in your project's root directory "~/Projects/gtk-hello", then issue the following commands

git init
git add src/Application.vala
git commit -m "Create initial structure. Create window with button."
git remote add origin [e-mail]:yourusername/yourrepositoryname.git
git push -u origin master

With these commands:

• We've told git to track revisions in this folder

• That we'd like to track revisions on the file "Application.vala" specifically

• We've committed our first revision and explained what we did in the revision

• Then we've told git to push your code to GitHub.

Remember to replace "yourusername" with your GitHub username and "yourrepositoryname" with the name of the new repository you created

Victory!

Let's recap what we've learned to do in this first section:

• We created a new project containing a "src" folder

• We created our main vala file and inside it we created a new Gtk.Window and Gtk.Button

• We built and ran our app to make sure that everything worked properly

• Finally, we committed our first revision and pushed code to GitHub

Feel free to play around with this example. Make the window a different size, set different margins, make the button say other things. When you're comfortable with what you've learned, go on to the next section.

A Note About Libraries

Remember how when we compiled our code, we used the valac command and the argument --pkg gtk+-3.0? What we did there was make use of a "library". If you're not familiar with the idea of libraries, a library is a collection of methods that your program can use. So this argument tells valac to include the GTK+ library (version 3.0) when compiling our app.

In our code, we've used the Gtk "Namespace" to declare that we want to use methods from GTK (specifically, Gtk.Window and Gtk.Button.with_label). Notice that there is a hierarchy at play. If you want to explore that hierarchy in more detail, you can check out Valadoc.

Hello (again) World!

To create our first real app, we're going to need all the old stuff that we used in the last example. But don't just copy and paste! Let's take this time to practice our skills and see if we can recreate the last example from memory. Additionally, now that you have the basics, we're going to get a little more complex and a little more organized:

1. Create a new folder inside "~/Projects" called "hello-again".Then, go into "hello-again" and create our directory structure including the "src" folder.

2. Create "Application.vala" in the "src" folder. This time we're going to prefix our file with a small legal header. Make sure this header matches the license of your code and assigns copyright to you. More info about this later.

   /*
    * SPDX-License-Identifier: GPL-3.0-or-later
    * SPDX-FileCopyrightText: 2021 Your Name <[e-mail]>
    */

3. Now, let's create a Gtk.Application, a Gtk.ApplicationWindow, and set the window's default properties. Refer back to the last chapter if you need a refresher.

4. For the sake of time let's just put a Gtk.Label instead of a Gtk.Button. We don't need to try to make the label do anything when you click it.

   var label = new Gtk.Label ("Hello Again World!");

   Don't forget to add it to your window and show the window's contents:

   main_window.add (label);
   main_window.show_all ();

5. Build "Application.vala" just to make sure it all works. If something goes wrong here, feel free to refer back to the last chapter and remember to check your terminal output for any hints.

6. Initialize the branch, add your files to the project, and write a commit message using what you learned in the last chapter. Lastly, make sure you've created a new repository for your project on GitHub push your first revision with git:

   git remote add origin [e-mail]:yourusername/yourrepositoryname.git
   git push -u origin master

Everything working as expected? Good. Now, let's get our app ready for other people to use.

License

Since we're going to be putting our app out into the wild, we should include some information about who wrote it and the legal usage of its source code. For this we need a new file in our project's root folder: the LICENSE file. This file contains a copy of the license that your code is released under. For elementary OS apps this is typically the GNU General Public License (GPL). Remember the header we added to our source code? That header reminds people that your app is licensed and it belongs to you. GitHub has a built-in way to add several popular licenses to your repository. Read their documentation for adding software licenses and add a LICENSE file to your repository.