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: "io.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.present ();
    }

    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 gtk4 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_top = 12,
    margin_bottom = 12,
    margin_start = 12,
    margin_end = 12
};

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

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

main_window.child = button_hello;

Any ideas about what happened here?

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

• Then we add margins 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 the window.

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

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 git@github.com: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.

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 gtk4? 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 4) 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.

Now that you've learned about Meson, the next step is to make your app able to be translated to different languages. The first thing you need to know is how to mark strings in your code as translatable. Here's an example:

stdout.printf ("Not Translatable string");
stdout.printf (_("Translatable string!"));

string normal = "Another non-translatable string";
string translated = _("Another translatable string");

See the difference? We marked the string as translatable by adding _() around it. Go back to your project and make all your strings translatable by adding _().

Now we have to make some changes to our Meson build system and add a couple new files to describe which files we want to translate and which languages we want to translate into.

1. Open up your "meson.build" file and add these lines below your project declaration:

   Copy

   # Include the translations module
   i18n = import('i18n')
   
   # Set our translation domain
   add_global_arguments('-DGETTEXT_PACKAGE="@0@"'.format (meson.project_name()), language:'c')

2. Remove the lines that install your .desktop and metainfo files and replace them with the following:

   Copy

   #Translate and install our .desktop file
   i18n.merge_file(
       input: 'data' / 'hello-again.desktop.in',
       output: meson.project_name() + '.desktop',
       po_dir: meson.project_source_root() / 'po',
       type: 'desktop',
       install: true,
       install_dir: get_option('datadir') / 'applications'
   )
   
   #Translate and install our .metainfo file
   i18n.merge_file(
       input: 'data' / 'hello-again.metainfo.xml.in',
       output: meson.project_name() + '.metainfo.xml',
       po_dir: meson.project_source_root() / 'po',
       install: true,
       install_dir: get_option('datadir') / 'metainfo'
   )

   The merge_file method combines translating and installing files, similarly to how the executable method combines building and installing your app. You might have noticed that this method has both an input argument and an output argument. We can use this instead of the rename argument from the install_data method.

3. Still in this file, add the following as the last line:

   Copy

   subdir('po')

4. You might have noticed in step 2 that the merge_file method has an input and output. We're going to append the additional extension .in to our .desktop and .metainfo.xml files so that this method can take the untranslated files and produce translated files with the correct names.

   Copy

   git mv data/hello-again.desktop data/hello-again.desktop.in
   git mv data/hello-again.metainfo.xml data/hello-again.metainfo.xml.in

   We use the git mv command here instead of renaming in the file manager or with mv so that git can keep track of the file rename as part of our revision history.

5. Now, Create a directory named "po" in the root folder of your project. Inside of your po directory you will need to create another "meson.build" file. This time, its contents will be:

   Copy

   i18n.gettext(meson.project_name(),
       args: '--directory=' + meson.project_source_root(),
       preset: 'glib'
   )

6. Inside of "po" create another file called "POTFILES" that will contain paths to all of the files you want to translate. For us, this looks like:

   Copy

   src/Application.vala
   data/hello-again.desktop.in
   data/hello-again.metainfo.xml.in

7. We have one more file to create in the "po" directory. This file will be named "LINGUAS" and it should contain the two-letter language codes for all languages you want to provide translations for. As an example, let's add German and Spanish

   Copy

   de
   es

8. Now it's time to go back to your build directory and generate some new files using Terminal! The first one is our translation template or .pot file:

   Copy

   ninja io.github.yourusername.yourrepositoryname-pot

   After running this command you should notice a new file in the po directory containing all of the translatable strings for your app.

9. Now we can use this template file to generate translation files for each of the languages we listed in the LINGUAS file with the following command:

   Copy

   ninja io.github.yourusername.yourrepositoryname-update-po

   You should notice two new files in your po directory called de.po and es.po. These files are now ready for translators to localize your app!

10. Last step. Don't forget to add all of the new files we created in the po directory to git:

    Copy

    git add src/Application.vala meson.build po/ data/
    git commit -am "Add translations"
    git push

That's it! Your app is now fully ready to be translated. Remember that each time you add new translatable strings or change old ones, you should regenerate your .pot and po files using the -pot and -update-po build targets from the previous two steps. If you want to support more languages, just list them in the LINGUAS file and generate the new po file with the -update-potarget. Don't forget to add any new po files to git!

Translators Comments

Sometimes detailed descriptions in the context of translatable strings are necessary for disambiguation or to help in the creation of accurate translations. For these situations use /// TRANSLATORS: comments.

/// TRANSLATORS: The first %s is search term, the second is the name of default browser
title = _("Search for %s in %s").printf (query, get_default_browser_name ());

While having a build system is great, our app still isn't ready for regular users. We want to make sure our app can be built and installed without having to use Terminal. What we need to do is package our app. To do this, we use Flatpak on elementary OS. This section will teach you how to package your app as a Flatpak, which is required to publish apps in AppCenter. This will allow people to install your app and even get updates for it when you publish them.

Practice Makes Perfect

If you want to get really good really fast, you're going to want to practice. Repetition is the best way to commit something to memory. So let's recreate our entire Hello World app again from scratch:

1. Create a new branch folder "hello-packaging"

2. Set up our directory structure including the "src" and "data" folders.

3. Add your Copying, .desktop, .metainfo.xml, icons, and source code.

4. Now set up the Meson build system and translations.

5. Test everything!

Did you commit and push to GitHub for each step? Keep up these good habits and let's get to packaging this app!

Flatpak Manifest

The Flatpak manifest file describes your app's build dependencies and required permissions. Create a io.github.yourusername.yourrepositoryname.yml file in your project root with the following contents:

# This is the same ID that you've used in meson.build and other files
app-id: io.github.yourusername.yourrepositoryname

# Instead of manually specifying a long list of build and runtime dependencies,
# we can use a convenient pre-made runtime and SDK. For this example, we'll be
# using the runtime and SDK provided by elementary.
runtime: io.elementary.Platform
runtime-version: '7.2'
sdk: io.elementary.Sdk

# This should match the exec line in your .desktop file and usually is the same
# as your app ID
command: io.github.yourusername.yourrepositoryname

# Here we can specify the kinds of permissions our app needs to run. Since we're
# not using hardware like webcams, making sound, or reading external files, we
# only need permission to draw our app on screen using either X11 or Wayland.
finish-args:
  - '--share=ipc'
  - '--socket=fallback-x11'
  - '--socket=wayland'

# This section is where you list all the source code required to build your app.
# If we had external dependencies that weren't included in our SDK, we would list
# them here.
modules:
  - name: yourrepositoryname
    buildsystem: meson
    sources:
      - type: dir
        path: .

To run a test build and install your app, we can use flatpak-builder with a few arguments:

flatpak-builder build io.github.yourusername.yourrepositoryname.yml --user --install --force-clean

This tells Flatpak Builder to build the manifest we just wrote into a clean build folder the same as we did for Meson. Plus, we install the built Flatpak package locally for our user. If all goes well, congrats! You've just built and installed your app as a Flatpak.

That wasn't too bad, right? We'll set up more complicated packaging in the future, but this is all that is required to submit your app to AppCenter Dashboard for it to be built, packaged, and distributed. If you'd like you can always read more about Flatpak.

Uninstalling the application

Ninja and Flatpak both provide commands to uninstalling the application. It is recommended to use the provided method in both cases.

To remove our application with Flatpak, we will use Flatpak's remove command:

flatpak remove io.github.yourusername.yourrepositoryname

Flatpak will prompt you to remove your application.

flatpak uninstall io.github.yourusername.yourrepositoryname --delete-data


        ID                                                          Branch           Op
 1.     io.github.yourusername.yourrepositoryname                   master           r
 2.     io.github.yourusername.yourrepositoryname.Locale            master           r

Proceed with these changes to the user installation? [Y/n]:

Note: You can append -y to the command to bypass the dialog confirmation prompt

If you'd like you can always read more about Flatpak remove.

Now that you know how to code, build, and package an app using Vala, Gtk, Meson, and Flatpak, it’s time to learn a little bit more about how to build out your app into something really useful. The first thing we need to learn is how to lay out widgets in our window. But we have a fundamental problem: We can only add one widget (one “child”) to Gtk.Window. So how do we get around that to create complex layouts in a Window? We have to add a widget that can contain multiple children. The most common widgets for creating layouts are Boxes and Grids.

Gtk.Box

A Box is a widget that can contain multiple children in a single row or column. We create a new Gtk.Box like this:

var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 6);

Remember that Gtk.Button and Gtk.Label accept an argument (a String) in the creation method (that’s the stuff in parentheses and quotes). As shown above, Gtk.Box accepts two arguments in the creation method—orientation and spacing. Here, we’ve declared that when we add widgets to our box, they should stack vertically.

Let’s add some stuff to the Box:

var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 6);
box.append (new Gtk.Label (_("Label 1")));
box.append (new Gtk.Label (_("Label 2")));

Add the box to a window using the child property:

var box = new Gtk.Box (Gtk.Orientation.VERTICAL, 6);
box.append (new Gtk.Label (_("Label 1")));
box.append (new Gtk.Label (_("Label 2")));

var main_window = new Gtk.ApplicationWindow (this) {
    child = box
};

Now build your app and see what it looks like. Since we’ve given our box a Gtk.Orientation of VERTICAL the labels stack up on top of each other. Try creating a Gtk.Box with horizontal orientation.

Gtk.Grid

While we can use Gtk.Box to create single row or single column layouts with the append method, we can't use it to create row-and-column-based layouts. Instead, we can use Gtk.Grid:

// First we create all the widgets we want to lay out in our grid
var hello_button = new Gtk.Button.with_label (_("Hello"));
var hello_label = new Gtk.Label (_("Label 1");

var goodbye_button = new Gtk.Button.with_label (_("Goodbye"));
var goodbye_label = new Gtk.Label (_("Label 2"));

// Then we create a new Grid and set its spacing properties
var grid = new Gtk.Grid () {
    column_spacing = 6,
    row_spacing = 6
};

// Finally, we attach those widgets to the Grid. Attach first row of widgets
grid.attach (hello_button, 0, 0, 1, 1);
grid.attach (hello_label, 1, 0, 1, 1);

// Attach second row of widgets
grid.attach (goodbye_button, 0, 1);
grid.attach_next_to (goodbye_label, goodbye_button, Gtk.PositionType.RIGHT, 1, 1);

var main_window = new Gtk.ApplicationWindow (this) {
    child = grid
};

Notice that the attach method takes 5 arguments:

1. The widget that you want to attach to the grid.

2. The column number to attach to starting at 0.

3. The row number to attach to starting at 0.

4. The number of columns the widget should span.

5. The number of rows the widget should span.

You can also use attach_next_to to place a widget next to another one on all four sides. Note also that providing the number of rows and columns the widget should span is optional. If you supply only the column and row numbers, Gtk will assume that the widget will span 1 column and 1 row.

Review

Let’s recap what we learned in this section:

• We packed multiple children into a Window using Gtk.Box and Gtk.Grid

• We set the properties of Gtk.Grid including its spacing

• We added multiple widgets into a single Gtk.Grid using the attach method to create complex layouts containing Buttons and Labels.

Now that you understand more about Boxes and Grids, try packing other kinds of widgets into a window like an Image. Don’t forget to play around with the attach method and widgets that span across multiple rows and columns. Remember that Valadoc is super helpful for learning more about the methods and properties associated with widgets.

Continuous integration testing (also called CI), is a way to automatically ensure that your app builds correctly and has the minimum necessary configuration to run when it's installed. Setting up CI for your app can save you time and give you reassurance that when you submit your app for publishing it will pass the automated testing phase in AppCenter Dashboard. Keep in mind however, that there is also a human review portion of the submission process, so an app that passes CI may still need fixing before being published in AppCenter. Now that you have an app with a build system, metadata files, and packaging, we can configure CI using GitHub Actions.

1. Navigate to your project's page on GitHub and select the "Actions" tab.

2. Select "set up a workflow yourself". You'll then be shown the main.yml file with GitHub's default CI configuration. Replace the default workflow with the following:

name: CI

# This workflow will run for any pull request or pushed commit
on: [push, pull_request]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "flatpak"
  flatpak:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # This job runs in a special container designed for building Flatpaks for AppCenter
    container:
      image: ghcr.io/elementary/flatpak-platform/runtime:7.2
      options: --privileged

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so the job can access it
    - uses: actions/checkout@v3

      # Builds your flatpak manifest using the Flatpak Builder action
    - uses: flatpak/flatpak-github-actions/flatpak-builder@v6
      with:
        # This is the name of the Bundle file we're building and can be anything you like
        bundle: MyApp.flatpak
        # This uses your app's RDNN ID
        manifest-path: io.github.yourusername.yourrepositoryname.yml

        # You can automatically run any of the tests you've created as part of this workflow
        run-tests: true

        # These lines specify the location of the elementary Runtime and Sdk
        repository-name: appcenter
        repository-url: https://flatpak.elementary.io/repo.flatpakrepo
        cache-key: "flatpak-builder-${{ github.sha }}"

1. Select "Start commit" in the top right corner of the page to commit this workflow to your repository.

That's it! The Flatpak CI workflow will now run on your repository for any new commits or pull requests. You'll be able to see if the build succeeded or failed, and any reasons it might have failed. Configuring this CI workflow will help guide you during the development process and ensure that everything is working as intended.

This workflow will also produce a Flatpak Bundle file using GitHub Artifacts that you can download and install with Sideload. Using this bundle file, you can test feature or bug fix branches with your team, contributors, or community before merging the proposed fix into your main git branch.

GitHub Actions can be used to configure many more types of CI or other automation. For more information, check out the GitHub Actions website.

Internally, elementary uses the following code style guide to ensure that code is consistently formatted both internally and across projects. Consistent and easily-legible code makes it easier for newcomers to learn and contribute. We'd like to recommend that in the spirit of Open Source collaboration, all Vala apps written in the wider ecosystem also follow these guidelines.

Whitespace

White space comes before opening parentheses or braces:

public string get_text () {}
if (a == 5) {
    return 4;
}

for (i = 0; i < maximum; i++) {}
my_function_name ();
var my_instance = new Object ();

An exception is admitted for Gettext-localized strings, where no space should go between the underscore and the opening parenthese:

// Space before parentheses since it's normal method:
button.label = set_label_string ();
// No space before parentheses since it's gettext-localized string:
button.tooltip_text = _("Download");

Whitespace goes between numbers and operators in all math-related code.

c = (n * 2) + 4;

Lines consisting of closing brackets (} or )) should be followed by an empty line, except when followed by another closing bracket or an else statement.

if (condition) {
    // ...
} else {
    // ...
}

// other code

Indentation

Vala

Vala code is indented using 4 spaces for consistency and readability.

In classes, functions, loops and general flow control, the first brace is on the end of the first line ("One True Brace Style"), followed by the indented code, and a line closing the function with a brace:

public int my_function (int a, string b, long c, int d, int e) {
    if (a == 5) {
        b = 3;
        c += 2;
        return d;
    }

    return e;
}

On conditionals and loops, always use braces even if there's only one line of code:

if (my_var > 2) {
    print ("hello\n");
}

Cuddled else and else if:

if (a == 4) {
    b = 1;
    print ("Yay");
} else if (a == 3) {
    b = 3;
    print ("Not so good");
}

If you are checking the same variable more than twice, use switch/case instead of multiple else/if:

switch (week_day) {
   case "Monday":
       message ("Let's work!");
       break;
   case "Tuesday":
   case "Wednesday":
       message ("What about watching a movie?");
       break;
   default:
       message ("You don't have any recommendation.");
       break;
}

Markup

Markup languages like HTML, XML, and YML should use two-space indentation since they are much more verbose and likely to hit line-length issues sooner.

<component type="desktop">
  <name>Calendar</name>
  <description>
    <p>A slim, lightweight calendar app that syncs and manages multiple calendars in one place, like Google Calendar, Outlook and CalDAV.</p>
  </description>
  <releases>
    <release version="5.0" date="2019-02-28" urgency="medium">
      <description>
        <p>Add a search entry for calendars</p>
      </description>
    </release>
  </releases>
  <screenshots>
    <screenshot type="default">
      <image>https://raw.githubusercontent.com/elementary/calendar/master/data/screenshot.png</image>
    </screenshot>
  </screenshots>
</component>

Classes and Files

A file should only contain one public class.

All files have the same name as the class in them. For example, a file containing the class AbstractAppGrid should be called "AbstractAppGrid.vala"

Classes should be named in a descriptive way, and include the name of any parent classes. For example, a class that subclasses Gtk.ListBoxRow and displays the names of contacts should be called ContactRow.

Comments

Comments are either on the same line as the code they reference or in a special line.

Comments are indented alongside the code, and obvious comments do more harm than good.

/* User chose number five */
if (c == 5) {
    a = 3;
    b = 4;
    d = -1;  // Values larger than 5 are undefined
}

Sometimes detailed descriptions in the context of translatable strings are necessary for disambiguation or to help in the creation of accurate translations. For these situations use /// TRANSLATORS: comments.

/// TRANSLATORS: The first %s is search term, the second is the name of default browser
title = _("Search for %s in %s").printf (query, get_default_browser_name ());

Variable, Class, and Function Names

Variable and function names are all lower case and separated by underscores:

var my_variable = 5;

public void my_function_name () {
   do_stuff ();
}

Classes and enums are Upper Camel Case (aka Pascal Case):

public class UserListBox : Gtk.ListBox {
    private enum OperatingSystem {
        ELEMENTARY_OS,
        UBUNTU
    }
}

Constants and enum members should be all uppercase and separated by underscores:

public const string UBUNTU = "ubuntu";

private enum OperatingSystem {
    ELEMENTARY_OS,
    UBUNTU
}

The values of constant strings (such as when used with GLib.Action) should be lowercase and separated with dashes:

public const string ACTION_GO_BACK = "action-go-back";

Casting

Avoid using as keyword when casting as it might give null as result, which could be forgotten to check.

/* OK */
((Gtk.Entry) widget).max_width_chars

/* NOT OK as this approach requires a check for null */
(widget as Gtk.Entry).max_width_chars

Prefer Properties Over Get/Set Methods

In places or operations where you would otherwise use get or set , you should make use of = instead.

For example, instead of using

set_can_focus (false);

you should use

can_focus = false;

Initialize Objects with Properites

This is especially clearer when initializing an object with many properties. Avoid the following

var label = new Gtk.Label ("Test Label");
label.set_ellipsize (Pango.EllipsizeMode.END);
label.set_valign (Gtk.Align.END);
label.set_width_chars (33);
label.set_xalign (0);

and instead do this

var label = new Gtk.Label ("Test Label") {
    ellipsize = Pango.EllipsizeMode.END,
    valign = Gtk.Align.END,
    width_chars = 33,
    xalign = 0
};

Create Classes with Properties

This goes for creating methods inside of classes as well. Instead of

private int _number;

public int get_number () {
    return _number;
}

public void set_number (int value) {
    _number = value;
}

you should use

public int number { get; set; }

or, where you need some extra logic in the getters and setters:

private int _number;
public int number {
    get {
        // We can run extra code here before returning the property. For example,
        // we can multiply it by 2
        return _number * 2;
    }
    set {
        // We can run extra code here before/after updating the value. For example,
        // we could check the validity of the new value or trigger some other state
        // changes
        _number = value;
    }
}

Preferring properties in classes enables the use of GLib.Object.bind_property () between classes instead of needing to create signals and handle changing properties manually.

Vala Namespaces

Referring to GLib is not necessary. If you want to print something instead of:

GLib.print ("Hello World");

You can use

print ("Hello World");

String Formatting

Avoid using literals when formatting strings:

var string = @"Error parsing config: $(config_path)";

Instead, prefer printf style placeholders:

var string = "Error parsing config: %s".printf (config_path);

Warnings in Vala use printf syntax by default:

critical ("Error parsing config: %s", config_path);

GTK events

Gtk widgets are intended to respond to click events that can be described as "press + release" instead of "press". Usually it is better to respond to toggle and release events instead of press.

Columns Per Line

Ideally, lines should have no more than 80 characters per line, because this is the default terminal size. However, as an exception, more characters could be added, because most people have wide-enough monitors nowadays. The hard limit is 120 characters.

Splitting Arguments Into Lines

For methods that take multiple arguments, it is not uncommon to have very long line lengths. In this case, treat parenthesis like brackets and split lines at commas like so:

var message_dialog = new Granite.MessageDialog.with_image_from_icon_name (
    "Basic Information and a Suggestion",
    "Further details, including information that explains any unobvious consequences of actions.",
    "phone",
    Gtk.ButtonsType.CANCEL
);

EditorConfig

If you are using elementary Code or your code editor supports EditorConfig, you can use this as a default .editorconfig file in your projects:

# EditorConfig <https://EditorConfig.org>
root = true

# elementary defaults
[*]
charset = utf-8
end_of_line = lf
indent_size = tab
indent_style = space
insert_final_newline = true
max_line_length = 80
tab_width = 4

# Markup files
[{*.html,*.xml,*.xml.in,*.yml}]
tab_width = 2

Before we even think about writing code, you'll need a certain basic setup. This chapter will walk you through the process of getting set up. We will cover the following topics:

• Creating an account on GitHub and importing an SSH key

• Setting up the Git version control system

• Getting and using the elementary developer "SDK"

We’re going to assume that you’re working from a clean installation of elementary OS 5.1 Hera or later. This is important as the instructions you’re given may reference apps that are not present (or even available) in other GNU/Linux based operating systems like Ubuntu. It is possible to apply the principles of this guide to Ubuntu development, but it may be more difficult to follow along.

GitHub

GitHub is an online platform for hosting code, reporting issues, tracking milestones, making releases, and more. If you're planning to publish your app through AppCenter, you'll need a GitHub account. If you already have an account, feel free to move on to the next section. Otherwise, sign up for a GitHub account and return when you're finished.

Git

To download and upload to GitHub, you'll need the Terminal program git. Git is a type of version control system that allows multiple developers to collaboratively develop and maintain code while keeping track of each version along the way.

If you're ready, let's get you set up to use Git:

1. Open the Terminal and install Git

   Copy

   sudo apt install git

2. We need to inform Git who we are so that when we upload code it is attributed correctly. Inform Git of your identity with the following commands

   Copy

   git config --global user.name "Your Name"
   git config --global user.email "You@email.com"

3. To authenticate and transfer code securely, you’ll need to generate an SSH key pair (a kind of fingerprint for your computer) and import your public key to GitHub. Type the following in Terminal:

   Copy

   ssh-keygen -t ed25519 -C "your_email@example.com"

4. When prompted, press Enter to accept the default file name for your key. You can choose to protect your key with a password or press Enter again to use no password when pushing code.

5. Now we're going to import your public key to GitHub. View your public SSH key with the following command, then copy the text that appears

   Copy

   cat ~/.ssh/id_ed25519.pub

6. Visit your SSH keys page and click the green button in the upper right-hand corner that says "New SSH key". Paste your key in the "Key" box and give it a title.

We're all done! Now you can download source code hosted on GitHub and upload your own code. We'll revisit using git in a bit, but for now you're set up.

Developer "SDK"

At the time of this writing, elementary OS doesn't have a full SDK like Android or iOS. But luckily, we only need a couple apps to get started writing code.

Code

The first piece of our "SDK" is Code. This comes by default with elementary OS. It comes with some helpful features like syntax highlighting, auto-save, and a Folder Manager. There are other extensions for Code as well, like the Outline, Terminal, Word Completion, or Devhelp extensions. Play around with what works best for you.

Terminal

We’re going to use Terminal in order to compile our code, push revisions to GitHub (using git), and other good stuff. Throughout this guide, we’ll be issuing Terminal commands. You should assume that any command is executed from the directory “Projects” in your home folder unless otherwise stated. Since elementary OS doesn’t come with that folder by default, you’ll need to create it.

Open Terminal and issue the following command:

mkdir Projects

Development Libraries

In order to build apps you're going to need their development libraries. We can fetch a basic set of libraries and other development tools with the following terminal command:

sudo apt install elementary-sdk

Flatpak

On elementary OS you will already have the required Flatpak remote and platform pre-installed. On other Linux OSes, you can add the remote and install the Flatpak platform and SDK:

flatpak install -y appcenter io.elementary.Sdk

flatpak remote-add --if-not-exists --system appcenter https://flatpak.elementary.io/repo.flatpakrepo
flatpak install -y appcenter io.elementary.Platform io.elementary.Sdk

And with that, we're ready to dive into development! Let's move on!

Every app comes with two metadata files that we can generate using an online tool. Open AppStream Metainfo Creator and fill out the form with your app's info:

Don't worry about generating Meson snippets, as we'll cover that in the next section. After you select "Generate", you should have two resulting files that you can copy.

MetaInfo

First is a MetaInfo file. This file contains all the information needed to list your app in AppCenter. It should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>io.github.myteam.myapp</id>

  <name>My App</name>
  <summary>Proves that we can use Vala and Gtk</summary>

  <metadata_license>CC-BY-4.0</metadata_license>
  <project_license>GPL-3.0-or-later</project_license>

  <description>
    <p>
      A quick summary of your app's main selling points and features. Just a couple sentences per paragraph is best
    </p>
  </description>

  <launchable type="desktop-id">io.github.myteam.myapp.desktop</launchable>
</component>

In your project's root, create a new folder called "data", and save your MetaInfo to a new file called "hello-again.metainfo.xml".

Screenshots

For the purposes of this tutorial, screenshots are optional, but they are required for publishing in AppCenter. Screenshots should only show your app on a transparent background and not contain any additional text or illustrations. You can use the caption tag to provide translatable and accessible descriptions of your screenshots.

<screenshots>
  <screenshot type="default">
    <caption>The most important feature of my app</caption>
    <image>https://raw.githubusercontent.com/myteam/myapp/1.0.0/data/screenshot.png</image>
  </screenshot>
</screenshots>

Content Warnings

We use the Open Age Rating Service (OARS) standard to describe sensitive content that may be present in your app so that people using it can be informed and actively consent to seeing that content. OARS data is required and can be generated by taking a short survey:

Branding

You can also specify a brand color for your app by adding the branding tag inside the component tag. Colors must be in hexadecimal, starting with #. The background will automatically be given a slight gradient in your app's banner.

<branding>
  <color type="primary">#f37329</color>
</branding>

Monetization

If you want to monetize your app, you will need to add two keys inside a custom tag inside the component tag. Suggested prices should be in whole USD. You also must include your app's AppCenter Stripe key. This is a unique public key for each app and is not the same as your Stripe account's regular public key. You can connect your app to Stripe and receive a new key on the AppCenter Dashboard.

<custom>
  <value key="x-appcenter-suggested-price">5</value>
  <value key="x-appcenter-stripe">pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</value>
</custom>

Releases

Your app must have a release tag for every version you wish to publish in AppCenter, including the initial release.

<releases>
  <release version="1.0.0" date="2022-09-08">
    <description>
      <p>Initial release, includes features such as:</p>
      <ul>
        <li>Application can be launched</li>
      </ul>
    </description>
  </release>
</releases>

Desktop Entry

This file contains all the information needed to display your app in the Applications Menu and in the Dock. The one generated from AppStream Metainfo Creator looks something like this:

[Desktop Entry]
Version=1.0
Type=Application

Name=My App
Comment=Proves that we can use Vala and Gtk
Categories=Development;Education;

Icon=io.github.myteam.myapp
Exec=io.github.myteam.myapp
Terminal=false

Copy the contents of your Desktop Entry and save it to the data folder you created earlier. Name this new file "hello-again.desktop".

Mark Your Progress

Each time we add a new file or make a significant change it's a good idea to commit a new revision and push to GitHub. Keep in mind that this acts as a backup system as well; when we push our work to GitHub, we know it's safe and we can always revert to a known good revision if we mess up later.

Add all of these files to git and commit a revision:

git add data/
git commit -am "Add Metadata files"
git push

Now that we've got all these swanky files laying around, we need a way to tell the computer what to do with them. Ready for the next chapter? Let's do this!

Do I need to know Vala?

The examples in this documentation use Vala, but the libraries and concepts used to build apps for elementary OS also work with a number of popular languages like C, Python, Go, Rust, etc. We don't assume extensive expertise in Vala in this guide, but basic programming knowledge and experience with object-oriented programming languages will be valuable.

If you're not familiar with Vala and want to learn, there are great resources available on the Vala website

Does this guide cover design principles?

Design is covered in the Human Interface Guidelines (HIG). We reference the HIG throughout this guide and it's important you grasp the concepts proposed there, but this guide is focused primarily on code.

Do I need to read this guide in order?

We recommend to at least skim "The Basic Setup" first, but sections are generally written to be standalone tutorials and will reference other parts of the guide where necessary.

Where I can get help?

We use GitHub discussions for Q&A as well as a place to submit ideas or show off what you're working on! Join the community

The last thing we need for a minimum-viable-app is to provide app icons. Apps on elementary OS provide icons hinted in 6 sizes: 16px, 24px, 32px, 48px, 64px, and 128px. These icons will be shown in many places throughout the system, such as those listed below:

Place your icons in the data directory and name them after their pixel sizes, such as32.svg, 64.svg, etc. The file structure should look like this:

hello-again
    data
        16.svg
        24.svg
        32.svg
        48.svg
        64.svg
        128.svg

Now that you have icon files in the data directory, add the following lines to the end of meson.build to install them .

# Install our icons in all the required sizes
icon_sizes = ['16', '24', '32', '48', '64', '128']

foreach i : icon_sizes
    install_data(
        'data' / i + '.svg',
        install_dir: get_option('datadir') / 'icons' / 'hicolor' / i + 'x' + i / 'apps',
        rename: meson.project_name() + '.svg'
    )
    install_data(
        'data' / i + '.svg',
        install_dir: get_option('datadir') / 'icons' / 'hicolor' / i + 'x' + i + '@2' / 'apps',
        rename: meson.project_name() + '.svg'
    )
endforeach

You'll notice the section for installing app icons is a little more complicated than installing other files. In this example, we're providing SVG icons in all of the required sizes for AppCenter and, since we're using SVG, we're installing them for both LoDPI and HiDPI. If you're providing PNG icons instead, you'll need to tweak this part a bit to handle assets exported for use on HiDPI displays.

If you cannot see your new icon in the Applications Menu or the Dock once you've reinstalled your app, refresh your system's icon cache using the following command:

sudo update-icon-caches /usr/share/icons/*

Gtk.Popover

Popovers are a very flexible container widget that can contain any other widgets, just like your main window. In this section we'll be opening a popover by clicking on a .

Next create a Popover and set the quit Button as its child. Adding Granite.STYLE_CLASS_MENU will automatically set up some margins and sizing for us. Finally, set the popover property of the MenuButton to point to our Popover.

Build and run your app. Notice that you can open and close the Popover automatically by activating the MenuButton with your pointer or by using the keyboard shortcut F10. The Popover is styled correctly as a menu and clicking the quit Button closes your app.

GLib.Menu

Start by creating a new Menu and add an item "Quit" with the action name "app.quit". Then create a new PopoverMenu with the Menu we just created as its model. We can position and halign the PopoverMenu so that it appears where we expect in relation to the pointer, and we'll set has_arrow to false, since this menu won't be pointing to a button.

There's just one more thing to do for our secondary click menu, and that's to add a widget that will be the parent of our PopoverMenu and receive the GestureClick. Add a Box to the main window, connect the GestureClick using add_controller (), and parent the PopoverMenu with set_parent ().

Build and run your app, then use a secondary click to open the PopoverMenu at your pointer. You'll notice that the keyboard shortcut is shown automatically in the menu, everything is styled correctly without having to manually add any style classes, and clicking the menu item closes your app.

The next thing we need is a build system. The build system that we're going to be using is called . We already installed the meson program at the beginning of this book when we installed elementary-sdk. What we're going to do in this step is create the files that tell Meson how to install your program. This includes all the rules for building your source code as well as correctly installing your icons, .desktop, and metainfo files and the binary app that results from the build process.

Create a new file in your project's root folder called "meson.build". We've included some comments along the way to explain what each section does. You don't have to copy those, but type the rest into that file:

Notice that in each of our install_data methods, we rename our files using our project name. By using our project name—and its RDNN scheme—we will ensure that our files are installed under a unique name that won't cause conflicts with other apps.

And you're done! Your app now has a real build system. This is a major milestone in your app's development!

Building and Installing with Meson

Now that we have a build system, let's try it out. Configure the build directory using the Meson command in Terminal:

This command tells Meson to get ready to build our app using the prefix "/usr" and that we want to build our app in a clean directory called "build". The meson setup command defaults to installing our app locally, but we want to install our app for all users on the computer.

Change into the build directory and use ninja to build. Then, if the build is successful, install with ninja install:

Uninstalling the application

To uninstall your application, change into the build directory and we will use ninja once again to uninstall:

Review

Let's review all we've learned to do:

• Create a new Gtk app using Gtk.Window, Gtk.Button, and Gtk.Label

• Keep our projects organized into branches

• License our app under the GPL and declare our app's authors in a standardized manner

• Create a .desktop file using RDNN that tells the computer how to display our app in the Applications Menu and the Dock

• Set up a Meson build system that contains all the rules for building our app and installing it cleanly

• Uninstall our application cleanly

That's a lot! You're well on your way to becoming a bona fide app developer for elementary OS. Give yourself a pat on the back, then take some time to play around with this example. Change the names of files and see if you can still build and install them properly. Ask another developer to clone your repo from GitHub and see if it builds and installs cleanly on their computer. If so, you've just distributed your first app! When you're ready, we'll move onto the next section: Translations.

Apps should automatically save their state in elementary OS, allowing a user to re-open a closed app and pick up right where they left off. To do so, we utilize GSettings via . GSettings allows your app to save certain stateful information in the form of booleans, strings, arrays, and more. It's a great solution for window size and position as well as whether certain modes are enabled or not. Note that GSettings is ideal for small amounts of configuration or stateful data, but user data (i.e. documents) should be stored on the disk.

For the simplest example, let's create a switch in your app, and save its state.

Define Settings Keys

First, you need to define what settings your app will use so they can be accessed by your app. In your data/ folder, create a new file named gschema.xml. Inside it, let's define a key for the switch:

The schema's path and id attributes are your app's ID (path in a / format while id is the standard dot-separated format). Note the key's name and type attributes: the name is a string to reference the setting, while in this case type="b" defines the setting as a boolean. The key's summary and description are developer-facing and are exposed in developer tools like dconf Editor.

Use The Settings Object

In order to interact with the settings key we just defined, we need to create a GLib.Settings object in our application. Building on previous examples, you can create a Gtk.Switch, add it to your window, create a Settings object, and bind the switch to a settings key like so:

Install and Compile Schemas with Meson

We need to add the new GSchema XML file to our build system so it is included at install time. Create a file data/meson.build and type the following:

This ensures your gschema.xml file is installed, and renames it with your app's ID to avoid filename conflicts.

Be sure to add the following lines to the end of the meson.build file in your source root so that Meson will compile the installed schemas:

Compile and install your app to see it in action!

To see the state saving functionality in action, you can open your app, toggle the switch, close it, then re-open it. The switch should retain its previous state. To see it under the hood, open dconf Editor, navigate to your app's settings at io.github.yourusername.yourrepositoryname, and watch the useless-setting update in real time when you toggle your switch.

One way to debug apps is by logging information in the code. This enables seeing which code was run when a problem occurred and what the value of variables were. You can directly call or use the convenience functions listed below.

Debug

Debug logs usually give detailed information on the flow through the system and are not printed to Terminal or logs by default.

Log functions, like debug use style formatting and can be called like this:

Info

Use info log level to log informational messages as well as interesting runtime events. These logs are also immediately visible on a status console, and should be kept to a minimum.

Message

Use the message log level to output a message.

Warning

The warning log level outputs messages that warn of, for example, use of deprecated APIs, 'almost' errors, or runtime situations that are undesirable or unexpected, but not necessarily "wrong". These logs are immediately visible on a status console.

Critical

Critical log level is used when there is a severe application failure that should be investigated immediately.

Error

Error log level includes logs for runtime errors or unexpected conditions. These errors are immediately visible on a status console and cause your app to exit.

When creating a new class, prefer GObject-style construction. This type of class construction separates handling arguments from the main logic of your class. It also ensures that information passed in during construction is still available later, and makes your class more likely to be compatible with GLib's functions like property binding.

A simple class written with GObject-style construction looks like this:

Construction Properties

In the above example, MyClass has a public property foo whose type is int, but we've also declared it as { get; construct; }. This shorthand declares the type of access for this property's get and set functions. Since we declared the property as public, get is also public, but we've declared the set function as construct, which means we can only assign its value as a constructor argument.

We want construction arguments to be public to ensure that we can later get information out of a class that was used to construct it, if need be. But it's important to declare limited set access on properties for future maintainability. Since there is no handling for changes in this property in the construct block, setting this property after the class is constructed would have no effect, even if we allowed it by declaring { get; construct set; }.

Constructors

MyClass also contains a constructor; it describes what arguments are required to construct the class. We've declared here that in order to construct MyClass, we need an int passed in when we initialize a new object such as with var new_class = new MyClass (5);

Inside the constructor, we have a special Object () call, in which we specify a property and its value, Object (foo: foo);. This sets the value of the integer property foo defined earlier to the value received as an argument. It is equivalent to saying this.foo = foo;.

The Construct Block

When using GObject-style construction, a constructor should only contain code that parses arguments and sets property values with the Object () call. All other class construction logic happens in the construct block. Code in the construct block runs every time an instance of this object is created, regardless of the constructor used.

Declaring Multiple Constructors

To see how this style of class construction scales and keeps code organized, let's look at a more complex example. Say we want to display a list of devices. Each device lives in its own row, which is denoted by the class Row. In this example, sometimes we have access to a Device object which stores the name and icon properties of the device, but for some devices we have to pass in those properties manually to construct our row. We can achieve this by declaring two constructors:

• a default constructor that takes two arguments: string name and Icon icon

• a separate, named constructor which takes one argument: a Device object

Note that in both cases, we handle the arguments in the constructor, while the actual logic of creating UI widgets lives in the common construct block.

This way, we can have multiple constructors without having to repeat the initialization logic.

See also

Applications can show additional information in the dock as well as the application menu. This makes the application feel more integrated into the system and give user it's status at a glance. See for what you should do and what you shouldn't.

For this integration you can use the . Since it uses the same D-Bus path as the , the API can work across many different distributions as it is widely supported by third party applications.

Current API support:

Setting Up

Before writing any code, you must add the library to your build system. We already installed this library during when we installed elementary-sdk. Open your meson.build file and add the new dependency to the executable method.

Your app must also be a Gtk.Application with a correctly set application_id as we previously set up in .

Though we haven't made any changes to our source code yet, change into your build directory and run ninja to build your project. It should still build without any errors. If you do encounter errors, double check your changes and resolve them before continuing.

Once you've set up granite in your build system and created a new Gtk.Application with an application_id, it's time to write some code.

Badges

Showing a badge in the dock and Applications Menu with the number 12 can be done with the following lines:

Keep in mind you have to set the set_badge_visible property to true, and use an int64 type for the set_badge property. The suffix .begin is required here since these are asynchronous methods.

Progress Bars

The same goes for showing a progress bar, here we show a progress bar showing 20% progress:

As you can see, the method set_progress takes a double value type and is a range between 0 and 1: from 0% to 100%. As with badges, Don't forget that set_progress_visible must be true and .begin is required for asynchronous methods.

Actions

Actions are specific functions your app can perform without already being open; think of them as alternate and more specific entry points into your app. Actions appear in the context menu of your app icon in the Applications Menu and Dock, and are searchable by name from the Applications Menu.

D-Bus activation

Your app needs to support D-Bus activation in order to use actions as entry points. This does not require any changes to the application source code. All that is needed is a service file which is not unlike the .desktop file that you are already familiar with. Create a new .service file in the data directory:

To install the service add the following to your meson.build file:

Lastly, update the .desktop file by adding the DBusActivatable line to the Desktop Entry group:

Declaring actions

Then use a dedicated group, named after the unique action name, to define the details of each action:

The Icon line is optional and should be an icon which represents the action that will be performed. The Exec line should be specified, but is used only for backwards compatibility in case your app ever runs in an environment without D-Bus activation support.

The action name should not include your app's name, as it will always be displayed alongside your app. The action icon should also not be your app icon, as it may be shown in the menu for your app icon, or badged on top of the app icon.

When using GResource, custom resource files will be compiled into your app's binary, ensuring they're available and loaded when your app launches. Regardless of which type of resource you'd like to include, you'll need to create a gresource.xml file and include it in your build system.

Make sure to start with a Gtk.Application as described in the . In the data directory, create a new file called gresource.xml like the one below. Then update your meson build file to include steps to build the resource into your binary. Make sure to update the resource prefix to match your app's RDNN.

Now that we have a gresource.xml file and have included it in the build system, we can add files and reference them in our app.

Icons

You can provide custom icons and have your app automatically refer to them by name and choose the correct size by adding them your Gresource file under the namespace /icons. For this to work properly, your resource path must match your application's ID.

Add a custom icon to the data directory, and then update your gresource.xml file to reference it:

If you want to use the same icon name in multiple sizes in your app, you can alias the icon to paths in and GTK will automatically load the correct version when its size is referenced:

The last step is to create a Gtk.Image or Gtk.Button using your custom icon and add it to the main window:

elementary OS ships with two styles for app widgets: a dark style and a light style. By default, your app will use the light style, but by using Gtk.Settings and Granite.Settings you can choose to always use a dark style or to follow the user's preference.

Setting a Dark Style

Some apps, like photo or video editors, benefit from reducing the contrast between their content and the app's UI by always choosing to be displayed using a dark style. You can set the dark style for your app by using Gtk.Settings and setting the property gtk_application_prefer_dark_theme. In your Application class, add the following lines to your activate function:

Here, we get the default Gtk.Settings object and then we set this property to instruct GTK to use the dark style. Build your app and run it and notice that it now uses a dark style instead of a light style.

Using The User's Preference

Many apps will be usable in either a light or dark style. In this case, apps should respect the user's style preference and adapt when it is changed.

First, make sure you've included Granite in the build dependencies declared in your meson.build file:

Now, you can read and respond to the user's style preference with Granite.Settings and then use Gtk.Settings to set it in your app's activate function.

By now you've probably already seen the notification bubbles that appear on the top right of the screen. Notifications are a way to provide updates about the state of your app. For example, they can inform you that a long running background process has been completed or a new message has arrived. In this section we are going to show you just how to get them to work in your app.

Making Preparations

In your .desktop file, add the line X-GNOME-UsesNotifications=true to the end of the file. This is what will make your app appear in System Settings so that notification preferences can be set.

Sending Notifications

Now build and run your app, and click the "Notify" button. Congratulations, you've learned how to send notifications!

Badge Icons

Notifications will automatically contain your app's icon, but you can add additional context by setting a badge icon. Right after the line containing var notification = New Notification, add:

Build and run your app again, and press the "Notify" button. As you can see, the notification now has a smaller badged icon placed over your app's icon. Using this method, you can set the icon to any of the named icons shipped with elementary OS.

Buttons

Now, we can add a button to the notification with a label and the action ID.

Build and run your app again, and press the "Notify" button. Notice that the notification now has a button with the label "Quit" and clicking it will close your app.

Priority

Replace

Make a new button with the label "Replace" that sends a new notification, this time with an ID. This button will replace a notification with a matching ID when clicked, instead of sending a new notification.

Build and run your app again. Click on the buttons, first on "Notify", then "Replace". See how the "Notify" button sends a new notification each time it's clicked, but the "Replace" button replaces the contents of the same notification when it's clicked.

Review

Let's review what all we've learned:

GTK and GLib have a powerful API called which can be used to define the primary actions of your app, assign them keyboard shortcuts, use them as entry points for your app and tie them to widgets like Buttons and Menu Items. In this section, we're going to create a Quit action for your app with an assigned keyboard shortcut and a Button that shows that shortcut in a tooltip.

Gtk.HeaderBar

Since we're using this HeaderBar as our app's main titlebar, we need to set show_title_buttons to true so that GTK knows to include window controls. We can then override our Window's built-in titlebar with the titlebar property.

Build and run your app. You can see that it now has a custom HeaderBar with a big red icon in it. But when you click on it, nothing happens.

GLib.SimpleAction

Define a new Quit action and register it with Application from inside the startup method:

You'll notice that we do a few things here:

• Set the "accelerators" (keyboard shortcuts) for "app.quit" to <Control>q and <Control>w. Notice that the action name is prefixed with app; this refers to the namespace of the ActionMap built in to Gtk.Application

Now we can tie the action to the HeaderBar Button by assigning the action_name property of our Button:

Build and run your app again and see that you can now quit the app either through the defined keyboard shortcuts or by clicking the Button in the HeaderBar.

Granite.markup_accel_tooltip

First, make sure you've included Granite in the build dependencies declared in your meson.build file, then set the tooltip_markup property of your HeaderBar Button:

Build and run your app and then hover over the HeaderBar Button to see its description and associated keyboard shortcuts.

So far, you've created apps with a single HeaderBar, but what about creating an app with a multi-pane layout like Mail or Tasks?

Before we begin, make sure you've included Granite in the build dependencies of your "meson.build" file. We'll be using it later for a couple of style classes.

Start with a new Gtk.Application, but this time set the titlebar property of the ApplicationWindow to an invisible grid. This will replace the default HeaderBar of the window since we'll be creating our own HeaderBars inside the paned layout.

Do the same thing again for the end_child of the Paned: create a HeaderBar with END WindowControls, inside a vertical Box.

Finally, make a few small tweaks:

1. Set an empty label as the title_widget in the start header

2. Add Granite.STYLE_CLASS_VIEW to the end box

3. Set the default size and title properties of the ApplicationWindow

The final result should look like this:

Some of the features of your application may depend on system level settings or services, such as Internet connectivity or app level access to the network. While your app cannot directly change those settings, it can prompt users to change them by linking to specific panes in the System Settings.

elementary OS implements a special settings:// URI scheme for linking to System Settings. The links lead to specific settings panes. You can find most commonly used ones in the Granite.SettingsUri namespace in the Granite library.

Opening a link

First, make sure you've included recent enough version of Granite and Gtk in the build dependencies declared in your meson.build file. You can get those dependencies by using the elementary Flatpak runtime version 7.2 or newer:

Then you can open Network settings by launching Granite.SettingsUri.NETWORK:

Use cases

There are roughly two categories of settings that you can prompt users to change: general purpose and app specific. General ones include:

• Granite.SettingsUri.NETWORK, where connection to the Internet can be enabled

• Granite.SettingsUri.ONLINE_ACCOUNTS, where users can add their CalDAV and IMAP accounts

• Granite.SettingsUri.SOUND_INPUT, where microphone input can be enabled

while app specific ones are:

• Granite.SettingsUri.LOCATION, where access to location data can be granted

• Granite.SettingsUri.NOTIFICATIONS, where presentation of app notifications can be customized

• Granite.SettingsUri.SHORTCUTS, where global keyboard shortcuts can be added

Marking Your App for Monetization

At any time, you can select the "$" icon in your dashboard to link your and enable payments for your app in AppCenter. However, this change will only apply to your app when a new release is submitted; to link a new account or unlink an account you will need to create a new release and submit it for publishing.

Why Monetize?

Monetizing your app allows you to accept payments from users when they download your app. AppCenter displays the suggested price as the download button, along with a dropdown where users can choose their own price.

Even if you want to give your app away for free, you should consider monetizing and setting the suggested price to $0. This lists your app as free throughout AppCenter, but allows users to send you optional payments when installing and from your app's listing.

Platform Fees

Each payment is split between you and elementary 70/30, with a minimum payment to elementary of $0.50 to cover distribution and payment processing. For example: with a $10 payment, $3 is paid to elementary and $7 is paid to you. For a $1 payment, $0.50 is paid to elementary to cover distribution and payment processing while $0.50 is paid to you.

There are no enrollment fees or subscription costs to publish your app in AppCenter.

We have a few requirements and suggestions for publishing your app to AppCenter. For a quick intro on writing apps for elementary OS, check out our guide. For more developer-oriented tips, see the .

Hard Requirements

The following are hard requirements for all apps submitted to AppCenter. Both automated and human reviews will check these requirements before each app and app update is approved and released to users.

Technical Requirements

Your app must be hosted in a . AppCenter Dashboard works by importing source code from a GitHub repository and building it in a clean environment. To ensure reproducible builds, transparency, and auditability, binaries cannot be uploaded or included alongside the source code to be installed on users' devices.

Your app may be written in any language, but the front-end must be a native Gtk3 or Gtk4 app. Web, Electron, Qt, Java, and other non-native app front-ends will be rejected during the review process. A game may be excepted from this requirement so long as it uses native window decorations and is generally usable on both loDPI and HiDPI displays.

Your app must not attempt to modify, replace, or append software sources on the target system.

Your app must not attempt to modify other apps or system programs.

Packaging

Your app must come with . elementary OS uses Flatpak packages to manage software installation and updates. Your app cannot be downloaded without it.

Extensions & Plugins

AppCenter supports publishing apps that meet these requirements; extensions or plugins (eg. to the Panel, System Settings, or other apps) are not currently supported.

Metadata Requirements

In general, your app's metadata should not refer to "elementary" or "elementary OS" in user-facing strings—it is assumed that all apps submitted to AppCenter are designed for elementary OS, and users don't need to be reminded of this. If there is a rare, legitimate reason for mentioning elementary, it must abide by the .

MetaInfo and OARS

Your metainfo.xml file must contain a screenshot tag that references a screenshot of your app with elementary OS default settings including the GTK stylesheet, icons, window button position, etc. Screenshots referenced in your MetaInfo should not contain marketing copy, illustrations, or other elements aside from a full-window screenshot of your app in use.

Desktop File

Your .desktop file must not contain NoDisplay=true or anything else that prevents it from showing up in the applications launcher.

Icons

Your app must install icons to /usr/share/icons/hicolor in 32px, 48px, 64px, and 128px. These are the icon sizes that will be displayed in the Applications menu's search, grid, and category views, Multitasking View, the dock, and in AppCenter.

Legal Requirements

You must have permission to redistribute any software you attempt to publish through AppCenter. If you are not the copyright holder or the source code is not openly licensed, you likely do not have permission to redistribute the software.

You must have permission to use any trademarks in your software or its metadata. You may not publish your app using trademarks reserved by others.

Your app must comply with all applicable laws as well as the terms of any services your app utilizes.

Other Publishing Requirements

Naming

To protect both users and developers, your app's name must not be the same as or confusingly similar to an existing app in AppCenter or another brand, as determined by app reviewers.

Your app should not be named generically like "Web Browser" or "File Manager".

Your app should not use "elementary", "Pantheon", or other elementary brand names in its naming scheme. It should also not be formatted with a leading lowercase "e", such as "eApp".

Launching

Your app should display its own graphical user interface on launch; it should not open another app or system component without user interaction inside your app UI. For example, if your app operates on a given file, it should display its own UI with an "Open File" button (or similar) before throwing an Open File dialog. If your app can request elevated permissions for certain actions, those permissions should be requested after your app's UI is shown and preferably only on-demand when actions requiring those permissions are performed.

App Stores

Your app cannot be an "app store," as ultimately determined by app reviewers. This includes but is not limited to apps that look and function confusingly similarly to AppCenter, provide software from other sources, link to an online app store, and/or facilitate payments for apps in the system repositories.

Duplicate Apps

Each app submission from a developer should be genuine and unique as determined by app reviewers. Submissions that are overly similar to existing apps from the same developer or are a a fork of an existing app with little to no changes may be rejected.

Suggestions

For the best experience, we strongly suggest the following before you publish your app:

Use a GitHub Organization

Once your app is submitted you cannot change the GitHub account that it is linked to. We recommend you use a GitHub organization as the owner of the repository so it can be transferred in the future if you so choose. This also makes it easier to manage community contributions.

Note that anyone with access to the GitHub organization will be able to manage releases and monetization.

Repository and App ID

While AppCenter Dashboard supports repositories with dashes and underscores, it vastly simplifies things to omit them from your GitHub repository name and subsequently your app ID. Some components in the desktop require workarounds for ID matching with dashes and underscores, so it is typically simpler to stick to all lowercase with no dashes or underscores.

Human Interface Guidelines

Tips for Games

If your game UI properly scales when the window is resized, one way to support both HiDPI and loDPI (even if the engine doesn't out of the box) is to launch your game maximized. That way the UI will scale up no matter the resolution or scaling factor of the display.

elementary provides badges, e.g. for your GitHub README. Badges will open to your app's page on the AppCenter website where users can learn more about your app, see screenshots, and decide to download it. They look like this:

Markdown

HTML