...
 
Commits (1)
......@@ -52,8 +52,8 @@ module.exports = {
'10-building-app',
'11-packaging',
'12-app-dev',
'13-templates',
'14-ui',
'13-ui',
'14-templates',
'15-saving-data',
'16-settings',
'17-dialogs',
......
......@@ -4,7 +4,7 @@ date: 2018-07-25 16:10:11
---
# GJS GTK+ Application Packaging Specification
This page details the built-in packaging specifiction for Javascript applications using GJS and GObject Introspection.
This page details the built-in packaging specification for Javascript applications using GJS and GObject Introspection.
*Users should refer to [the GJS application template](https://github.com/gcampax/gtk-js-app) for a complete, up-to-date example.*
......
......@@ -8,4 +8,17 @@ While we now have the ability to create applications, we are limited to one scri
*You can read more about the GJS GTK+ Application Specification [here]().*
The specification is quite long and complex; luckily applications have already implemented it for you!
\ No newline at end of file
The specification is quite long and complex; luckily applications have already implemented it for you! In the next guide we will be explaining how to use GNOME Builder to create a packaged application.
## Setting dependencies with packaging
Before using any import from `imports.gi` you should set which version you expect to use.
```js
pkg.require({
'Gtk': '3.0',
'Gio': '2.0'
});
```
`pkg` is a global utility object to access the packaging tools GJS provides. `pkg.require()` receives an object mapping dependency names to version strings. Always declare this before you use or import a library, ideally at the start of the file. This replaces `imports.gi.versions`.
\ No newline at end of file
......@@ -2,19 +2,23 @@
title: Setting Up Your Application Development Environment
---
For developing packaged applications in GJS we highly recommend [GNOME Builder](). GNOME Builder can download the latest GJS version for you and provides support for developing secure, structured GNOME applications.
For developing packaged applications in GJS we highly recommend [GNOME Builder](https://wiki.gnome.org/Apps/Builder). GNOME Builder can download the latest GJS version for you and provides support for developing secure, structured GNOME applications.
If you do not have GNOME Builder installed you can get it [here]().
If you do not have GNOME Builder installed you can get it [here](https://flathub.org/apps/details/org.gnome.Builder).
## Using GNOME Builder
### Creating a New GJS GTK+ Application Project
Open GNOME Builder's application menu and select `New Project`.
<img :src="$withBase('/assets/img/builder-01.png')" />
Select JavaScript as the language and GNOME Application as the type.
First open GNOME Builder and select `New...` to create a new project.
Click Create.
<img :src="$withBase('/assets/img/builder-02.png')" />
Choose `JavaScript` and `GNOME Application` so GNOME Builder correctly configures and creates a template for you to build your first project from.
<img :src="$withBase('/assets/img/builder-03.png')" />
### Configuring the Runtime Environment
......@@ -28,23 +32,24 @@ If you are working in another IDE is possible but more complicated.
### Download the Template
First, download the application template [here]() (or use git clone [link])
First, download the application template [here](TODO.localhost) (or use git clone [link])
### Install GJS
Install GJS from any of the packages below.
- Ubuntu 18.04
- Debian Stretch
- Arch Linux
- more at [pkgs.org]()
- [Ubuntu 18.04](https://packages.ubuntu.com/bionic/gjs)
- [Fedora 28](https://fedora.pkgs.org/28/fedora-x86_64/gjs-1.52.2-1.fc28.x86_64.rpm.html)
- [Debian](https://packages.debian.org/buster/gjs) *Warning: Out of Date In Stretch*
- [Arch Linux](https://www.archlinux.org/packages/extra/x86_64/gjs/)
- more at [pkgs.org](https://pkgs.org/download/gjs)
### Verifying Your GJS Version
Verify your system has a recent version of GJS. Type...
gjs --version
...into a terminal. You can see the features your version of GTK+ supports [here](). If your version is below 1.48.x it is recommended you use [GNOME Builder]() or build GJS from source.
...into a terminal. You can see the features your version of GTK+ supports [here](../../gjs/features-across-versions.html). If your version is below 1.50.x it is recommended you use [GNOME Builder](https://flathub.org/apps/details/org.gnome.Builder) or build GJS from source.
### Building GJS From Source
......
---
title: Templates in GJS
date: 2018-07-25 16:10:11
---
# GTK+ Templates & GJS
## Loading the template
In GJS it is quite simple to load a GTK+ template.
<table>
<tr>
<th>
Static Accessor
</th>
<th>
Registration Parameter
</th>
</tr>
<tr>
<td>
<pre><code>/* imports */
class X extends GObject.Object {
/* template accessor */
static get [Gtk.template] {
return 'url://templateurl';
}
}</code></pre>
</td>
<td>
<pre><code>/* imports */
GObject.registerClass({
Template: 'url://templateurl'
}, class X extends GObject.Object {
/* implementation */
});</code></pre>
</td>
</tr>
</table>
## Registering template children
To access children, you must provide them as an array to GObject when your class is created.
<table>
<tr>
<th>
Static Accessor
</th>
<th>
Registration Parameter
</th>
</tr>
<tr>
<td>
<pre><code>/* imports */
class X extends GObject.Object {
/* template accessor */
static get [Gtk.internalChildren] {
return ['label'];
}
}</code></pre>
</td>
<td>
<pre><code>/* imports */
GObject.registerClass({
InternalChildren: ['label']
}, class X extends GObject.Object {
/* implementation */
});</code></pre>
</td>
</tr>
</table>
## Accessing template children
Once registered, all template children are accessible with the pattern `this._[childName]`.
_Note the prefixed underscore!_
......@@ -4,22 +4,18 @@ title: Creating A User Interface
# Creating A User Interface
## Creating a GNOME Builder project
Until now we have been creating GTK+ widgets with JavaScript code like this:
<img :src="$withBase('/assets/img/builder-01.png')" />
```js
const button = new Button();
```
First open GNOME Builder and select `New...` to create a new project.
While this syntax is frequently used it is much easier and maintainable to build most of your application using a user interface file. A user interface file is an [XML]() file containing all of your widgets' positioning and properties.
<img :src="$withBase('/assets/img/builder-02.png')" />
Choose `JavaScript` and `GNOME Application` so GNOME Builder correctly configures and creates a template for you to build your first project from.
<img :src="$withBase('/assets/img/builder-03.png')" />
Your GNOME Builder project should contain a file named `window.ui`. We can use [Glade]() to edit this file.
## Using Glade
Your new project should contain the above files, specifically `window.ui`.
<img :src="$withBase('/assets/img/glade-tutorial-step-00.png')" />
Open `Glade`, make sure you have version 3.22.x+ and not an outdated version. The newest version of `Glade` can be found on FlatHub [here](https://flathub.org/apps/details/org.gnome.Glade).
......
---
title: Loading User Interface Files In GJS
date: 2018-07-25 16:10:11
---
# Loading User Interface Files In GJS
The user interface file you have created, `window.ui`, is a template for your application. To use this template and its widgets we need to load it.
*Before you continue make sure you've read [Extending GObject Classes in GJS]()*
## Loading the template
Luckily, in GJS it is quite simple to load a user interface template.
```js
/* imports */
var X = GObject.registerClass({
Template: 'url://templateurl'
}, class X extends Gtk.ApplicationWindow {
/* implementation */
});
}
```
You will find the above code in your project's `window.js` file. This code tells GTK+ to register the class and apply a GTK+ user interface template to it.
## Registering template widgets
We now have the template, but how do we access the widgets?
Before we had variables like this:
```js
const button = new Button();
button.do_something();
```
So it was easy to call functions and manipulate the button. To achieve a similar system with templates you have to tell GTK+ what widgets you want to use by passing a list of their IDs to `InternalChildren`.
```js
/* imports */
GObject.registerClass({
Template: 'url://templateurl',
InternalChildren: ['button']
}, class X extends GObject.Object {
/* implementation */
});
```
## Accessing template children
Now you can access the button like this:
```js
this._button.do_something();
```
All template widgets listend in `InternalChildren` are accessible with the pattern `this._[childName]`.
_Note the prefixed underscore!_
---
title: Saving Application Data
---
\ No newline at end of file
---
# Saving Application Data
We now have a full GTK+ application working! For many applications, though, storing user data is critical for functionality. A common example might be reopening the data or file that was in use before the application previously exited.
## Converting Data
Let's start with a simple data object. This will store the last used file by the user.
```js
let lastUsedFile = {
fileName: "/file/path/is/here",
fileDescription: "this is a description of the file"
};
```
We first need to convert it to [JSON]() for storage. GJS has built-in functions for this:
```js
let dataJSON = JSON.stringify(lastUsedFile);
```
## Locating Where To Save Data
Now we need to save `dataJSON`. Applications typically store data in their local configuration directory. You may know this as `~/.config/example-application/` but it varies on some systems so we should always use GLib's APIs to find it.
```js
let dataDir = GLib.get_user_config_dir();
```
Now that we have the directory, we can build the storage path.
```js
let destination = GLib.build_filenamev([dataDir, 'example-application', 'lastFile.json']);
```
This code builds the destination path string. We use `GLib.build_filenamev` to handle special cases where simple `/` strings don't work!
*Always look for official APIs to handle file names!*
## Saving Data To A File
Now let's finish up by actually writing to the file.
```js
let destinationFile = Gio.File.new_for_path(destination);
if (GLib.mkdir_with_parents(destinationFile.get_parent().get_path(), PERMISSIONS_MODE) === 0) {
let [success, tag] = file.replace_contents(dataJSON, null, false, Gio.FileCreateFlags.REPLACE_DESTINATION, null);
if(success) {
/* it worked! */
} else {
/* it failed */
}
} else {
/* error */
}
```
This code comes from [GJS Basic File Operations](../../gjs/basic-file-operations.html).
***And it is saved!***
---
title: Application Settings
---
\ No newline at end of file
---
# Application Settings
WIP
We just learned how to save application data to configuration files. This is appropriate for storing data relevant to the user's activities and any user-generated content. For application-level settings, however, you should utilize the built-in GSettings APIs.
\ No newline at end of file
......@@ -2,6 +2,10 @@
title: Dialogs
---
# Dialogs
WIP
### Creating a dialog
To create the dialog we'll use `GtkMessageDialog`. GtkMessageDialog
......
---
title: Localization
---
\ No newline at end of file
---
# Localization
WIP
\ No newline at end of file