GNOME App Developer's Guide
Contents
The GNOME App Developer's Guide project will create a complete guide for people of all ages, who love GNOME and know the basics of JavaScript, to write apps for their favourite Free Software desktop. Whether you're a 50-year-old hacker veteran or a 15-year-old Girl Scout, all you'll need to do is take one of these free online JavaScript tutorials and you'll be all set to continue on to the App Developer's Guide.
The App Developer's Guide will show you how to use the most common features of the most basic Gtk+ widgets and GNOME libraries. That means you'll be able to write complete apps, which look and feel like the other GNOME apps you're used to and have the sort of features you'd expect, like being able to save files and talk to web pages. By the end of the tutorial, you will have created a complete app of your own, which you can modify however you want. You will also learn how to write GNOME Shell extensions, which change the way that GNOME itself behaves.
The Guide started out as a project by Taryn Fox, an intern brought in for the mid-2012 GNOME Outreach Program for Women. Her project was to improve GNOME's existing JavaScript developer documentation, with an eye toward making it accessible to new developers; this page shows her and the other interns' progress. The goal for this phase of the project is to build on that work and create a complete, start-to-finish guide in time for the next round of the OPW, so that interns can work on creating new GNOME games and apps from scratch if they like.
Beginner tutorials outline
These cover the basics of writing and publishing a GNOME app.
Hello, GNOME! A complete walkthrough of building a basic GNOME app, from writing the code to creating a .desktop file for your app, so that you can run it straight from GNOME Shell. External links will show you how to create an icon, and package your app for your distro. Many thanks to Tiffany Antopolski for writing the first draft of this tutorial!
Welcome to the Grid. An introduction to Gtk+ widgets, like Labels and Images. You'll learn how to use Grids to arrange them, and how to set their properties in order to customize them. You'll also learn how to use GNOME's stock icons.
Getting the Signal. Some widgets, like Buttons and Switches, send out signals when you click on them. You'll learn how to write callback functions, which handle these signals and do whatever you want in response.
On the Menu. The App Menu is the menu that pops up when you click on the name of the application you're using, in the upper-left screen corner next to "Activities." You'll learn how to create an App Menu for your app, as well as an About dialog and a pop-up message asking if you're sure you want to close the app.
Making a List. You'll learn how put any kind of information you want in a ListStore, and then use a TreeView widget to let you scroll through and interact with it all. You'll also learn how to create ComboBox widgets that let you select options from a drop-down menu, which gets its options (and/or icons) from a ListStore.
Putting it all Together. You'll create a full working application, complete with a toolbar with tooltips and an involved Dialog that acts like a personality quiz. Your results will be saved to a TreeView widget in a sidebar pane, and clicking on any of them will show its details in the larger part of the window.
Advanced tutorials outline
These teach you how to use GNOME libraries, which are feature packages that let your apps do new and interesting things.
Gstreamer. Continuing on from the beginner tutorial, you'll learn how to record from your webcam and microphone, and how to play back sound and movie files from inside your app.
Telepathy. Want to have your friends take the quiz, and record their pictures and results? GNOME gives your app telepathic powers, and lets it contact them over instant messaging the same way you would.
Gio and Gsettings. You'll learn how to make your app load and save its list of results, and how to make it open up web pages or email addresses. You'll also learn how to create a Preferences menu, and save your app's settings.
Tracker and Folks. You don't have to save your quiz results as files. Instead, you can save them to Tracker, GNOME's "central repository of user information", so that other apps can access them and you won't have to worry about where to put things. You'll also learn how to access other apps' data, including your list of Folks, or contacts.
Libsoup and JsonGlib. Want to save your quiz results to your blog or personal website? JsonGlib lets you save your results in JSON format, which many websites will recognize, and Libsoup will let your app talk to websites and post anything online.
Libstatus and the notification area. GNOME apps can create notifications that pop up from the bottom of the screen, and let you interact with them or dismiss them. They can also put icons in the notification area, which pops up when you mouse into (or touch) the lower-right screen corner. This tutorial will show you how to do that.
Bonus tutorials
These are basically standalone, and don't depend on any of the others. They cover important parts of GNOME development literacy which aren't strictly tied to the "learn to write apps in JavaScript" theme.
GNOME Shell and App Themes. If you know CSS, the web's popular language for styling text and websites, you can use a library called GtkCSSProvider to create your own themes for GNOME Shell, restyling it however you want. You'll also learn how to style your own apps.
GNOME Shell Extensions. This tutorial will show you how to write your own, still using JavaScript.
Creating Help Files. Every good app needs a good help file. You'll learn how to use the Mallard markup language to write your app's help file, and what you should cover in what ways. You'll also learn how to make your app launch its Help file, from the menu or by pressing F1.
Webkit. Want to embed a JavaScript canvas or web app? Whether you want to write your GNOME app using web technologies only, or embed a website's login page so you can authenticate with them, you'll use Webkit, which is like a web browser inside your app.
Clutter. GNOME has its own library of shiny animations that you can use, called Clutter. Learning how to use them could take up a whole book, but this guide will show you the basics.
App Guide FAQ
If you have a question, feel free to either edit this page and add it or mail it to Taryn at <jewelfox AT SPAMFREE fursona DOT net>!
Why this guide?
Because right now, there is no one place to look if you want to learn how to write apps for GNOME. There are a lot of scattered resources, but there is no equivalent to, say, Android or iOS's developer documentation. Both of those platforms have many more apps than GNOME has, and one reason is how easy it is to get started writing for them. The App Developer's Guide aims to change that.
Why the focus on newbies?
GNOME efforts like the Outreach Program for Women are all about encouraging new contributors to participate in GNOME development. An App Developer Guide written with newbies' struggles in mind will not only help when it's time to put fingers to keyboard, but it will also help reduce potential contributors' anxiety and show them this is something that they can do.
Why JavaScript?
Of the four languages supported by the existing GNOME Developer Center, Python and JavaScript are the most newbie-friendly. Of the two, JavaScript is the one used more extensively both inside and outside of GNOME. GNOME Shell itself is written in JavaScript, and you can write extensions for it in JavaScript as well. Finally, my internship was for writing the JavaScript docs, and I'm more personally interested in them.
Resources
A page with examples of what other platforms' app developer guides are like.
The Beginner Tutorials' page for the 2012 OPW program explains in detail how to contribute to GNOME's developer documentation, although its list of completed widgets is out of date.
Still to do
- Write a style guide, with Mallard code snippets and instructions on where and when to use them. Include screenshots.
- Create a whiteboard, showing which parts of the tutorials still need to be finished.