Applications

Applications — Start here with your application

Functions

Properties

GFile * config-dir Read
GFile * image-attribution-file Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── GApplication
        ╰── GtkApplication
            ╰── EosApplication

Implemented Interfaces

EosApplication implements GActionGroup and GActionMap.

Description

The EosApplication class is where you start when programming your application. You should create a class that extends EosApplication.

You also need to think up an application ID. This takes the form of a reverse domain name, and it should be unique. This ID is used to make sure that only one copy of your application is running at any time; if a user tries to start a second copy, then the first copy is brought to the front.

To set up your application's data and window, override the “startup” function, like this example do-nothing application,

Smoke Grinder:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const Lang = imports.lang;
const Endless = imports.gi.Endless;

const SmokeGrinder = new Lang.Class ({
    Name: 'SmokeGrinder',
    Extends: Endless.Application,

    vfunc_startup: function() {
        this.parent();
        this._window = new Endless.Window({application: this});
        this._window.show_all();
    },
});

let app = new SmokeGrinder({ application_id: "com.example.smokegrinder",
                             flags: 0 });
app.run(ARGV);

You can specify attribution for images used in your application. This is important if you use images that require you to credit the original author, or Creative Commons-licenses. The attribution takes the form of a JSON file, an array of objects with the properties listed in Table 1, “Allowed properties of the objects in the image attribution JSON file”. See “image-attribution-file”.

Table 1. Allowed properties of the objects in the image attribution JSON file

Property Required? Type Description
thumb_uri Yes string A URI to show in the dialog. (e.g. resource:///com/endlessm/...)
uri No string URI where the original image is to be found: e.g., a Flickr link.
license * string Text identifying the license under which you are using this image. This field is not free-form; the allowed values are listed in Table 2, “Allowed values for the license property in the image attribution JSON file”. If the license is not listed there, leave this field blank and clarify the license in the comment field.
license_uri * string URI linking to the text of the image license. If you use the license field, this field may be automatically filled in, so you can leave it blank. If you do specify a value, then your value will override any automatic value. Note that you will then lose any localization from the automatic value; localization of this field is planned for later.
credit * string The name or username of the author of the image. This is appropriate when the terms of use specify that the author is to be credited when the image is used.
credit_contact No string URI at which the author can be contacted. (If this is an e-mail address, prefix it with mailto: so that it is a valid URI.)
copyright_holder * string Copyright holder of the image.
copyright_year No integer Copyright year of the image. This will be displayed along with the copyright holder.
permission No boolean Whether the image is used with permission. If this is specified, a string such as Used with permission may be displayed.
comment No string Any other comments about the image license, terms of use, or source.
*At least one of these properties is required.

Table 2. Allowed values for the license property in the image attribution JSON file


Functions

eos_application_new ()

EosApplication *
eos_application_new (const gchar *application_id,
                     GApplicationFlags flags);

Create a new application. For the application ID, use a reverse domain name, such as com.endlessm.weather. See g_application_id_is_valid() for the full rules for application IDs.

Parameters

application_id

a unique identifier for the application, for example a reverse domain name.

 

flags

flags to apply to the application; see GApplicationFlags.

 

Returns

a pointer to the application.


eos_application_get_config_dir ()

GFile *
eos_application_get_config_dir (EosApplication *self);

Gets a GFile pointing to the application-specific user configuration directory. This directory is located in XDG_USER_CONFIG_DIR, which usually expands to ~/.config. The directory name is the same as the application's unique ID (see “application-id”.)

You should use this directory to store configuration data specific to your application and specific to one user, such as cookies.

Calling this function will also ensure that the directory exists and is writable. If it does not exist, it will be created. If it cannot be created, or it exists but is not writable, the program will abort.

Parameters

self

the application

 

Returns

A GFile pointing to the user config directory.

[transfer none]


eos_application_get_image_attribution_file ()

GFile *
eos_application_get_image_attribution_file
                               (EosApplication *self);

Gets a GFile pointing to a JSON file containing credits for images included in the app's resources. See “image-attribution-file”.

Parameters

self

the application

 

Returns

A GFile pointing to the image attribution file, or NULL if one has not been set.

[transfer none][allow-none]

Since: 0.2


eos_application_set_image_attribution_file ()

void
eos_application_set_image_attribution_file
                               (EosApplication *self,
                                GFile *file);

You can provide attribution and credit for images included in the application by giving this function a JSON file with image credits. See “image-attribution-file” for the JSON file's required format.

Parameters

self

the application

 

file

a GFile pointing to a file in the proper format, or NULL to unset.

[allow-none]

Since: 0.2

Types and Values

struct EosApplication

struct EosApplication;

This class structure contains no public members.

Property Details

The “config-dir” property

  “config-dir”               GFile *

A directory appropriate for storing per-user configuration information for this application. Accessing this property guarantees that the directory exists and is writable. See also eos_application_get_config_dir() for more information.

Owner: EosApplication

Flags: Read


The “image-attribution-file” property

  “image-attribution-file”   GFile *

A GFile handle to a file for storing attribution information for the images included in this application's resource file.

This attribution file must be a JSON file. Here is an example of the required format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[
  {
    "resource_path": "/com/example/smokegrinder/image1.jpg",
    "license": "Public domain",
    "uri": "http://www.photos.com/photos/12345",
    "comment": "No known copyright restrictions"
  },
  {
    "resource_path": "/com/example/smokegrinder/image2.jpg",
    "license_uri": "http://example.com/image-license",
    "uri": "http://www.photos.com/photos/54321",
    "credit": "Edward X. Ample",
    "credit_contact": "http://www.photos.com/users/example"
  },
  {
    "resource_path": "/com/example/smokegrinder/image3.jpg",
    "copyright_holder": "Jane Q. Hacker",
    "copyright_year": 2014,
    "permission": true
  }
]

The JSON object is an array of objects that each contain information about one image. The only required property is resource_path, which is the path to the image in the resource file.

The recognized properties are shown in Table 1, “Allowed properties of the objects in the image attribution JSON file”.

Nothing is guaranteed about how the application uses this information. It can display it to the user or make it available to other programs.

Currently, pressing Control+Shift+A brings up a credits dialog. This is liable to change in future versions.

Owner: EosApplication

Flags: Read / Write

Since: 0.2