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:

# project name, programming language, and required meson version
project('io.github.yourusername.yourrepositoryname',
    'vala', 'c',
    meson_version: '>= 0.56.0'
)

# Create a new executable, list the files we want to compile, list the dependencies we need, and install
executable(
    meson.project_name(),
    'src' / 'Application.vala',
    dependencies: [
        dependency('gtk4')
    ],
    install: true
)

# Install our .desktop file so the Applications Menu will see it
install_data(
    'data' / 'hello-again.desktop',
    install_dir: get_option('datadir') / 'applications',
    rename: meson.project_name() + '.desktop'
)

# Install our .metainfo.xml file so AppCenter will see it
install_data(
    'data' / 'hello-again.metainfo.xml',
    install_dir: get_option('datadir') / 'metainfo',
    rename: meson.project_name() + '.metainfo.xml'
)

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:

meson setup build --prefix=/usr

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:

cd build
ninja
ninja install

Uninstalling the application

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

sudo ninja 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.

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

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

9. Now we can use the 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 ());

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

Git

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

1. Open the Terminal and 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
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

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:

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:

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:

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

In the previous chapter, we created a "Hello World!" app to show off our Vala and Gtk skills. But what if we wanted to share our new app with a friend? They'd have to know which packages to include with the valac command we used to build our app, and after they'd built it they'd have to run it from the build directory like we did. Clearly, we need to do some more stuff to make our app fit for people to use, to make it a real app.

Hello (Again) World!

1. Create a new project folder, including a new "src" folder and an Application.vala file

2. Create a Gtk.Application class with a Gtk.ApplicationWindow in the activate () function.

3. Add a new Gtk.Label to the window with the text "Hello Again World!"

4. Finally, 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.

The results should look like this:

Initialize a git 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:

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

License

Next, we need a way to create a listing in AppCenter and a way to tell the interface to show our app in the Applications menu and dock: let's write some Metadata.

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.

Does this guide cover design principles?

Do I need to read this guide in order?

Where I can get help?

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

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

<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!

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

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.

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.

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/*

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

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:

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:

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

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.

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

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.

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:

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.

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 LICENSE, .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:

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

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.

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 will prompt you to remove your application.

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

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.

executable(
    meson.project_name(),
    'src' / 'Application.vala',
    dependencies: [
        dependency('granite-7'),
        dependency('gtk4')
    ],
    install: true
)

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.

var main_window = new Gtk.ApplicationWindow (this) {
    titlebar = new Gtk.Grid () { visible = false }
};

var paned = new Gtk.Paned (Gtk.Orientation.HORIZONTAL) {
    resize_start_child = false,
    shrink_end_child = false,
    shrink_start_child = false
};

var main_window = new Gtk.ApplicationWindow (this) {
    child = paned,
    titlebar = new Gtk.Grid () { visible = false }
};

var start_header = new Gtk.HeaderBar () {
    show_title_buttons = false
};
start_header.add_css_class (Granite.STYLE_CLASS_FLAT);
start_header.pack_start (new Gtk.WindowControls (Gtk.PackType.START));

var start_box = new Gtk.Box (Gtk.Orientation.VERTICAL, 0);
start_box.append (start_header);

var paned = new Gtk.Paned (Gtk.Orientation.HORIZONTAL) {
    start_child = start_box,
    resize_start_child = false,
    shrink_end_child = false,
    shrink_start_child = false
};

var main_window = new Gtk.ApplicationWindow (this) {
    child = paned,
    titlebar = new Gtk.Grid () { visible = false }
};

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

var start_header = new Gtk.HeaderBar () {
    show_title_buttons = false
};
start_header.add_css_class (Granite.STYLE_CLASS_FLAT);
start_header.pack_start (new Gtk.WindowControls (Gtk.PackType.START));

var start_box = new Gtk.Box (Gtk.Orientation.VERTICAL, 0);
start_box.append (start_header);

var end_header = new Gtk.HeaderBar () {
    show_title_buttons = false
};
end_header.add_css_class (Granite.STYLE_CLASS_FLAT);
end_header.pack_end (new Gtk.WindowControls (Gtk.PackType.END));

var end_box = new Gtk.Box (Gtk.Orientation.VERTICAL, 0);
end_box.append (end_header);

var paned = new Gtk.Paned (Gtk.Orientation.HORIZONTAL) {
    start_child = start_box,
    end_child = end_box,
    resize_start_child = false,
    shrink_end_child = false,
    shrink_start_child = false
};

var main_window = new Gtk.ApplicationWindow (this) {
    child = paned,
    titlebar = new Gtk.Grid () { visible = false }
};

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:

public class MyApp : Gtk.Application {
    public MyApp () {
        Object (
            application_id: "io.github.myteam.myapp",
            flags: ApplicationFlags.FLAGS_NONE
        );
    }

    protected override void activate () {
        var start_header = new Gtk.HeaderBar () {
            show_title_buttons = false,
            title_widget = new Gtk.Label ("")
        };
        start_header.add_css_class (Granite.STYLE_CLASS_FLAT);
        start_header.pack_start (new Gtk.WindowControls (Gtk.PackType.START));

        var start_box = new Gtk.Box (Gtk.Orientation.VERTICAL, 0);
        start_box.append (start_header);

        var end_header = new Gtk.HeaderBar () {
            show_title_buttons = false
        };
        end_header.add_css_class (Granite.STYLE_CLASS_FLAT);
        end_header.pack_end (new Gtk.WindowControls (Gtk.PackType.END));

        var end_box = new Gtk.Box (Gtk.Orientation.VERTICAL, 0);
        end_box.add_css_class (Granite.STYLE_CLASS_VIEW);
        end_box.append (end_header);

        var paned = new Gtk.Paned (Gtk.Orientation.HORIZONTAL) {
            start_child = start_box,
            end_child = end_box,
            resize_start_child = false,
            shrink_end_child = false,
            shrink_start_child = false
        };

        var main_window = new Gtk.ApplicationWindow (this) {
            child = paned,
            default_height = 300,
            default_width = 300,
            titlebar = new Gtk.Grid () { visible = false },
            title = "Hello World"
        };
        main_window.present ();
    }

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

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;
    }
}

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

# 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

Gtk.HeaderBar

protected override void activate () {
    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "Actions",
        titlebar = headerbar
    };
    main_window.present ();
}

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.

protected override void activate () {
    var button = new Gtk.Button.from_icon_name ("process-stop");
    button.add_css_class (Granite.STYLE_CLASS_LARGE_ICONS);

    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };
    headerbar.pack_start (button);
    
    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "Actions",
        titlebar = headerbar
    };
    main_window.present ();
}

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:

protected override void startup () {
    base.startup ();

    var quit_action = new SimpleAction ("quit", null);

    add_action (quit_action);
    set_accels_for_action ("app.quit",  {"<Control>q", "<Control>w"});
    quit_action.activate.connect (quit);
}

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:

    var button = new Gtk.Button.from_icon_name ("process-stop") {
        action_name = "app.quit"
    };

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:

executable(
    meson.project_name(),
    'src' / 'Application.vala',
    dependencies: [
        dependency('granite-7'),
        dependency('gtk4')
    ],
    install: true
)

var button = new Gtk.Button.from_icon_name ("process-stop") {
    action_name = "app.quit",
    tooltip_markup = Granite.markup_accel_tooltip (
        get_accels_for_action ("app.quit"),
        "Quit"
    )
};

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

Gtk.Popover

protected override void activate () {
    var menu_button = new Gtk.MenuButton () {
        icon_name = "open-menu",
        primary = true,
        tooltip_markup = Granite.markup_accel_tooltip ({"F10"}, "Menu")
    };
    menu_button.add_css_class (Granite.STYLE_CLASS_LARGE_ICONS);

    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };
    headerbar.pack_end (menu_button);

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "MyApp",
        titlebar = headerbar
    };
    main_window.present ();
}

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.

protected override void activate () {
    var quit_button = new Gtk.Button () {
        action_name = "app.quit",
        child = new Granite.AccelLabel.from_action_name ("Quit", "app.quit")
    };
    quit_button.add_css_class (Granite.STYLE_CLASS_MENUITEM);

    var popover = new Gtk.Popover () {
        child = quit_button
    };
    popover.add_css_class (Granite.STYLE_CLASS_MENU);

    var menu_button = new Gtk.MenuButton () {
        icon_name = "open-menu",
        popover = popover,
        primary = true
    };
    menu_button.add_css_class (Granite.STYLE_CLASS_LARGE_ICONS);

    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };
    headerbar.pack_end (menu_button);

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "MyApp",
        titlebar = headerbar
    };
    main_window.present ();
}

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.

protected override void activate () {
    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };

    var menu = new Menu ();
    menu.append ("Quit", "app.quit");

    var popover_menu = new Gtk.PopoverMenu.from_model (menu) {
        halign = Gtk.Align.START,
        has_arrow = false,
        position = Gtk.PositionType.BOTTOM
    };

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "MyApp",
        titlebar = headerbar
    };
    main_window.present ();
}

protected override void activate () {
    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };

    var menu = new Menu ();
    menu.append ("Quit", "app.quit");

    var popover_menu = new Gtk.PopoverMenu.from_model (menu) {
        halign = Gtk.Align.START,
        has_arrow = false,
        position = Gtk.PositionType.BOTTOM
    };

    var secondary_click_gesture = new Gtk.GestureClick () {
        button = Gdk.BUTTON_SECONDARY
    };

    var main_window = new Gtk.ApplicationWindow (this) {
        default_height = 300,
        default_width = 300,
        title = "MyApp",
        titlebar = headerbar
    };
    main_window.present ();

    secondary_click_gesture.released.connect ((n_press, x, y) => {
        var rect = Gdk.Rectangle () {
            x = (int) x,
            y = (int) y
        };

        popover_menu.pointing_to = rect;
        popover_menu.popup ();
    });
}

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

protected override void activate () {
    var headerbar = new Gtk.HeaderBar () {
        show_title_buttons = true
    };

    var menu = new Menu ();
    menu.append ("Quit", "app.quit");

    var popover_menu = new Gtk.PopoverMenu.from_model (menu) {
        halign = Gtk.Align.START,
        has_arrow = false,
        position = Gtk.PositionType.BOTTOM
    };

    var secondary_click_gesture = new Gtk.GestureClick () {
        button = Gdk.BUTTON_SECONDARY
    };

    var box = new Gtk.Box (Gtk.Orientation.HORIZONTAL, 0);
    box.add_controller (secondary_click_gesture);
    popover_menu.set_parent (box);

    var main_window = new Gtk.ApplicationWindow (this) {
        child = box,
        default_height = 300,
        default_width = 300,
        title = "MyApp",
        titlebar = headerbar
    };
    main_window.present ();

    secondary_click_gesture.released.connect ((n_press, x, y) => {
        var rect = Gdk.Rectangle () {
            x = (int) x,
            y = (int) y
        };

        popover_menu.pointing_to = rect;
        popover_menu.popup ();
    });
}

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.

Current API support:

Setting Up

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.

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.

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.

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:

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

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

Create a New Release

Submit for Review

To submit your app to AppCenter, you'll need to create a new JSON file describing your app release in the AppCenter Reviews repository on Github:

Name the file using your app's id with the json file extension. Fill in the contents of the file with the link to your git repository, the commit hash from your latest release, and the version number of that release:

{
  "source": "https://github.com/danirabbit/harvey.git",
  "commit": "45dd52660c0069207fa4b0c1fcf7ac6d7157d34b",
  "version": "1.0.1"
}

Once you've submitted the new file as a pull request to the AppCenter Reviews repository, your app will now be in the review queue!

Wait for Testing

Resolve Issues

Your app will go through an automated build process when it has been accepted by a reviewer. It will need to pass the Parse and Build steps listed in GitHub CI at the bottom of the pull request. If either of those steps fail, please inspect the build log to resolve issues.

If any questions or requested changes come up during the review process, the reviewer will use the conversation on the pull request and may mark it as "Changes Requested". You will need to correct these issues, create a new release of your app, and update the pull request with your new release.

The reviewer may also make some suggestions for best practices, inform you of new features, or link you to documentation.

Available on AppCenter

When your app passes automated testing and human review, it will become available in AppCenter in elementary OS.

Publishing Updates

Updating Screenshots

Screenshots are uploaded to the AppCenter screenshot server at publication time. The URL referenced in your MetaInfo file will be automatically replaced during publication and any changes you make to images hosted at the remote URL will not be reflected in AppCenter.

Release Notes

Release notes show up in AppCenter both on your app info page and on the updates page.

• You must add an accurate release tag to your MetaInfo file when publishing an update.

• The version in your release tag should match the latest version submitted to AppCenter.

• Previous release tags can remain in your MetaInfo file forever, and we encourage it; AppCenter may use them to show changes across multiple releases of your app

Descriptions

The contents of the description tag should be written for the people who use your app. Avoid technical language and developer-facing changes and focus more on what people can expect to see in this update.

✅️ Good Example

<release version="1.1.0 date="2023-05-21">
  <description>
    <p>Now with support for WebP images and an option to maintain aspect ratio when cropping! Plus, the main view now loads twice as fast.</p>
    <p>Other improvements:</p>
    <ul>
      <li>🇫🇷️ Updated French translations</li>
      <li>⚙️ Cleaner code with improved stability</li>
    </ul>
  </description>
</release>

❌️ Poor Example

<release version="1.1.0 date="2023-05-21">
  <description>
    <p>Fix bug #1234; rewrote method to be async</p>
    <p>Linted all the code, removed trailing whitespace</p>
    <p>Refactored utils</p>
    <p>Updated VAPIs</p>
  </description>
</release>

Issues

You can also list issues from your issue tracker (e.g. GitHub) that have been resolved in this release as a way for you to close the feedback loop that began when someone opened an issue on your tracker. Issue tags will be presented as links below a release description in AppCenter. Showing that you are responsive to feedback is a powerful tool in building a community around your app.

For now only the generic issue type is supported, and you must provide the url property. The value of the tag should be the title of the issue that it links to. For example:

<release version="1.1.0 date="2023-05-21">
  <description>
    <p>Now with support for WebP images and an option to maintain aspect ratio when cropping! Plus, the main view now loads twice as fast.</p>
  </description>
  <issues>
    <issue url="https://github.com/myteam/myapp/issues/28">Crash when opening corrupt JPEG</issue>
    <issue url="https://github.com/myteam/myapp/issues/31">Image gets pixelated after rotating</issue>
  </issues>
</release>

GitHub User/Org Name Changes

AppCenter does not support changing your GitHub username or organization name, as we rely on the unique RDNN of your app to avoid conflicts—and there is not an automated way to change the RDNN throughout the whole stack from AppCenter Dashboard down to the .deb files built and hosted in the AppCenter repository. If you change your GitHub username or organization name associated with your app, you will no longer be able to publish updates to your app without changing its name and branding. If you have ended up in this situation, you will receive an issue filed against your app with more details and with some options.

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 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 Flatpak manifest must use the elementary runtime. Manifests using for example the GNOME runtime will faill to build since that runtime is not available in the AppCenter remote.

Your sandbox holes must be reasonable as decided by app reviewers. Generally you should aim for your app to be as tightly sandboxed as possible and provide an explanation for any sandbox holes your app requires. AppCenter will warn about sandbox holes when downloading your app.

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

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.

Marking Your App for Monetization

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.

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:

protected override void activate () {
    var gtk_settings = Gtk.Settings.get_default ();
    gtk_settings.gtk_application_prefer_dark_theme = true;
}

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:

executable(
    meson.project_name(),
    'src/Application.vala',
    dependencies: [
        dependency('granite-7'),
        dependency('gtk4')
    ],
    install: true
)

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.

protected override void activate () {
    // First we get the default instances for Granite.Settings and Gtk.Settings
    var granite_settings = Granite.Settings.get_default ();
    var gtk_settings = Gtk.Settings.get_default ();

    // Then, we check if the user's preference is for the dark style and set it if it is
    gtk_settings.gtk_application_prefer_dark_theme = granite_settings.prefers_color_scheme == Granite.Settings.ColorScheme.DARK;

    // Finally, we listen to changes in Granite.Settings and update our app if the user changes their preference
    granite_settings.notify["prefers-color-scheme"].connect (() => {
        gtk_settings.gtk_application_prefer_dark_theme = granite_settings.prefers_color_scheme == Granite.Settings.ColorScheme.DARK;
    });
}

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

[![Get it on AppCenter](https://appcenter.elementary.io/badge.svg)](https://appcenter.elementary.io/io.github.USER.REPO)

HTML

<a href="https://appcenter.elementary.io/io.github.USER.REPO"><img src="https://appcenter.elementary.io/badge.svg" alt="Get it on AppCenter"></a>

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.

Default Action

You may have noticed that when you click on a new notification, a new window pops up. This is happening because the notification has a default action that is executed when the user clicks on it. If you don't set it, it will activate your application, where we create a new window and present it.

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:

Debug

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

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:

public class MyClass : Object {
    public int foo { get; construct; }

    public MyClass (int foo) {
        Object (foo: foo);
    }

    construct {
        if (foo > 0) {
            // Do stuff
        } else {
            // Do other stuff
        }
    }
}

Construction Properties

public int foo { get; construct; }

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

public MyClass (int foo) {
    Object (foo: foo);
}

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

construct {
    if (foo) {
        // Do stuff
    } else {
        // Do other stuff
    }
}

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

public class Row : Object {
    public string name { get; construct; }
    public Icon icon { get; construct; }

    public Row (string name, Icon icon) {
        Object (
            name: name,
            icon: icon
        );
    }

    public Row.from_device (Device device) {
        Object (
            name: device.name,
            icon: device.icon
        );
    }

    construct {
        var icon = new Gtk.Image.from_gicon (icon, Gtk.IconSize.DND);
        var label = new Gtk.Label (name);
    }
}

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

public Row (string name, Icon icon) {
    Object (
        name: name,
        icon: icon
    );
}

public Row.from_device (Device device) {
    Object (
        name: device.name,
        icon: device.icon
    );
}

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.

construct {
    var icon = new Gtk.Image.from_gicon (icon);
    var label = new Gtk.Label (name);
}

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

See also