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

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:

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.

Content Warnings

We use the 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 :

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.

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 .

Releases

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

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:

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:

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!

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!

To create our first real app, we're going to re-use what we learned in the last chapter and build on that example.

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.

The results should look like this:

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

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

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

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.

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.

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

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

Marking Your App for Monetization

At any time, you can select the "$" icon in your dashboard to link your Stripe account 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.

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:

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:

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

   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:

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.

   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:

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:

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:

   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

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:

   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:

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.

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

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

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

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!

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

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.

Create a New Release

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.

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 .

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

If you'd like you can always read .

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, . For now, type the following in "Application.vala".

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 . The naming scheme we used for our app's ID is called 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:

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.

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

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

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

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 .

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.

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:

You can find out more about the Gtk.UriLauncher in .

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

while app specific ones are:

• Granite.SettingsUri.PERMISSIONS, where are managed

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

• Granite.SettingsUri.NOTIFICATIONS

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:

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

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:

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— 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:

Add the box to a window using the child property:

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:

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.

You can also use attach_next_to to place a widget next to another one on . 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

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.

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 GLib.Settings. 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:

You can read more about , but for now this will bind the active property of the switch to the value of useless-setting in GSettings. When one changes, the other will stay in sync to reflect it.

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.

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

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

❌️ Poor Example

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:

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.

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:

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.

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.

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.

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

Then create a new Gtk.Paned and set that as the child of the ApplicationWindow. A Paned is a resizable widget that can contain two children. There are various properties you can set to control the widgets behavior when the AppliactionWindow is resized; For the purposes of this tutorial we want the first pane to stay a fixed size and we don't want someone to be able to make the window smaller than the contents of both sides of the Paned.

Next, let's create a new Gtk.HeaderBar and hide its title buttons. Then, we're going to pack our own that only contain the buttons for one side of the Window. And finally, we'll put that HeaderBar in a Box and set that as the start_child of the Paned.

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:

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

Begin by creating a Gtk.Application

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 .

Create a new MenuButton and add it to the end of the HeaderBar. Use the icon-name property to give it an icon, and add Granite.STYLE_CLASS_LARGE_ICONS to make it bigger just like we did in the section with our image Button. You can also set the primary property to true which will make this menu open when pressing the keyboard shortcut F10. Finally, add a tooltip to make the keyboard shortcut more discoverable.

Now create a new Button with the action app.quit, but instead of giving it a label, set a as its child; this will allow us to show the associated keyboard shortcut for the menu item. Finally, add Granite.STYLE_CLASS_MENUITEM so that the button shows as a borderless menu item.

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

You can also create Popover menus automatically from Actions. In this section we'll be creating a with a and opening it with a secondary click.

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.

Now let's add a new and set Gdk.BUTTON_SECONDARY as the button it responds to. Then at the end of the activate () function, we'll connect to the release () signal of that gesture.

When the GestureClick is released, it tells us the coordinates of where that gesture took place in our app, which we'll store in a . Then we can set the pointing_to property of our popover to that rectangle, and open it with the popup () function.

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.

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

Create a new Gtk.Application

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:

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