This tutorial will show you how to write your first GNOME application in JavaScript. You will use JavaScript to write for GNOME the same way you would for the web. Afterwards, you will learn how to use "native" widgets, to write applications that look and feel like other GNOME apps.
Have you gotten GNOME installed on your computer, and gedit set up to write code with? You'll want to do these things first.
Here's some basic HTML, CSS, and JavaScript code. Does this look familiar?
Hello, GNOME!
]]>
Let's save this as
You can run the above code by opening
The best part? We're going to continue to use JavaScript, to write all the parts that make our app work with GNOME. Let's look at the code, and see how it's done!
First, we need to tell GNOME that this is a JavaScript application, which uses gjs. Gjs is GNOME's way of turning your JavaScript code into instructions it understands, so this line always has to go at the start of your applications.
After that, we need to tell GNOME which libraries we want to import.
Just like how add-on libraries like jQuery let us do extra things with JavaScript, each of these libraries gives us new capabilities for our GNOME apps:
And
Now we create the application itself:
This will look familiar to you if you've worked with object-oriented JavaScript before. That's right; our whole application is a class called HelloGNOME. And as you can see, we've given it a property that says what its name is.
Here's some code you will more or less copy-and-paste for every JavaScript application you build. It creates a new Application, and then binds its activate and startup signals to functions that make the window show itself and build its user interface, respectively.
What does that mean? Well, everything in a GNOME application sends out a signal when something important happens. A button might send out the clicked signal when you click on it, for instance. Our job is to connect the signals to functions which handle them, and make the things that we want to have happen occur. We do this using each object's connect method, which takes two arguments: The signal we want to handle, and the Lang.bind function, which we have to use to tell connect which function we want to have handle the signal.
In this case, we want _onActivate to handle the activate signal, and _onStartup to handle the startup signal. _onActivate just tells the window to present itself; so basically, whenever you
When you copy and paste the above code for your own applications, be sure to change the name to a unique one each time.
In the _buildUI function, we're going to tell GNOME about our window and the things inside it, one at a time. After that, we're going to connect everything together and put it all on display.
The first object we create is an ApplicationWindow. It needs a title to go in the title bar, and its application property needs to be the application that we created, above. Beyond that, there are various ways of customizing how it looks, which the ApplicationWindow reference page will go into more detail about. As you can see here, we gave it a default height and width (measured in pixels), and told GNOME we want our window to appear in the center of the screen.
Remember how we imported Webkit right at the start? Here we're creating a new instance of a Webkit class called a WebView, which is more or less a browser window you can put inside of your app. After that, we then give it the URI that we want it to load when the application starts up.
We could just give it a web URI, like http://gnome.org. Instead, here we use a couple of GLib helper functions to tell the WebView where our
Each window can hold one, and only one, widget. Normally, we'd use a container widget like a Grid to put multiple widgets into, then use the window's add function to add the Grid to it. Here, we just need the WebView, so that's all we add to the window. After that, as the last part of the _buildUI function that creates our window, we tell the window to show itself and its contents.
Finally, we create a new instance of our HelloGNOME class, and tell GNOME to run it.
Now that we've created our first GNOME application, it's time to test it out! You don't need to compile your app or install any special software for this; GNOME has gjs built in, to let it run GNOME Shell. Just save
You should see more or less the same screenshot as before, with a button that you can click to make a short message appear.
You can use the terminal command
to navigate between directories inside the Terminal, in order to get to where you saved the files. There is also an extension for Nautilus, GNOME's file manager, which lets you right-click anywhere inside it to open a terminal window right there. Check the app you use to install new software (like Add/Remove Programs or the Software Center) for it.
Continue on to the next tutorial to learn how to build "native" GNOME applications that look and feel like the others, instead of a webview with HTML code inside. Or take a look at some code samples, if you'd like to see example code for each Gtk widget.
Finally, if you want to just build GNOME applications using JavaScript libraries designed for the web, you can basically stop here and go do that! Check out the later tutorials if you'd like to see how to create a .desktop file for your application, which will let it appear in your desktop's Activities menu with all your other apps.