## Applications

Applications — Start here with your application

## Functions

EosApplication * | eos_application_new ()
GFile * | eos_application_get_config_dir ()
GFile * | eos_application_get_image_attribution_file ()
void | eos_application_set_image_attribution_file ()

## Properties

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

## Types and Values

struct | EosApplication

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

String | Description
--- | ---
Public domain | Public domain
CC0 1.0 | CC0 1.0 Universal (Public domain)
CC BY 2.0 | Creative Commons Attribution 2.0
CC BY 3.0 | Creative Commons Attribution 3.0
CC BY-SA 2.0 | Creative Commons Attribution-ShareAlike 2.0
CC BY-SA 3.0 | Creative Commons Attribution-ShareAlike 3.0
CC BY-ND 2.0 | Creative Commons Attribution-NoDerivs 2.0
CC BY-ND 3.0 | Creative Commons Attribution-NoDerivs 3.0

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