API reference (alpha)

All data provided by Pegasus can be accessed using a global QML object called api. It has the following main components:

• api.collections: the list of all collections
• api.allGames: the list of all games
• api.keys: the keyboard/gamepad configuration of the user
• api.memory: an object that can store theme specific settings
• api.device: information about the user's device

Collections

Games found by Pegasus are organized in collections, and one game may be present in multiple collections. The collections can be accessed trough api.collections, which is an item model (in short, a list of items). Each collection in it has the following properties:

Properties marked as "optional" might have no value (eg. empty string or empty array). All fields are read-only.

Games

Games can have metadata and various kinds of assets. The list of games belonging to a collection can be accessed using a collection's games field (see above). The list of all available games can be accessed through api.allGames. Both are item models. Each game in them has the following properties:

Properties marked as "optional" might have no value (eg. empty string or empty array). Unless otherwise noted, all fields are read-only.

In addition, games have the following callable methods:

Game files

Games can have more than one file to launch (disks, clones, mods, etc). Every game has a files object that contains the files belonging to the game. It has the following properties:

In addition, games have the following callable methods:

Launching a game file may fail, in which case the reason is logged (and in the future, will be shown to the user). If the game starts up successfully, Pegasus minimizes its resource usage and goes to the background while the game runs. On return, the theme will be reloaded -- if you wish it to remember something, you can use api.memory (see later on this page).

Assets

Every game and collection has an asset object that contains the assets that may belong to a game. It has the following properties. All of them are (local or remote) URLs as string, and all of them can be empty.

Multiple assets are also supported for all asset types. For each of the fields above, there is also a field with the suffix List under the asset object (eg. boxFront -> boxFrontList). These are arrays of strings, and as such are usable as eg. model sources. Like the single-value fields, they can also be empty (ie. empty arrays).

Keys

Controls configuration can be queried using the api.keys object, with the functions and members below. For each UI functionality (eg. "accept"), you can check whether a particular key/button is registered to that event, or get all of the registered keys as an array.

In themes, you typically handle keyboard and gamepad key presses/releases using Keys.onPressed and Keys.onReleased (see the Qt documentation). The event object you receive there can be used as the parameter for the functions above. As for the key list querying, the returned array contains simple objects that have key and modifiers fields, like the real QML KeyEvent object (but nothing else).

Example:

Keys.onPressed: {
    if (api.keys.isAccept(event)) {
        event.accepted = true;

        // do something
    }
}

Memory

Themes often want to remember data like custom options or the index of the last launched game or collection. To store the settings belonging to your theme, you can use api.memory. This is an object that contains key-value pairs (like a Map), and can be modified using the following methods:

key must be a string in all methods above, while value can be any JSON-compatible JavaScript type.

Good places to use api.memory for example is when your theme loads (Component.onCompleted), unloads (Component.onDestruction) or the user starts a game. For example:

ListView {
    id: mygamelist

    model: api.allGames
    delegate: Rectangle {
        MouseArea {
            anchors.fill: parent
            onClicked: launchGame(modelData)
        }
    }
}


Component.onCompleted: {
    mygamelist.currentIndex = api.memory.get('gameIndex') || 0;
}

function launchGame(game) {
    api.memory.set('gameIndex', mygamelist.currentIndex);
    game.launch();
}

Device

Some themes might want to display information about the real world, like current time or battery status. The api.device object provides some fields for that. However, as Pegasus is available for a number of various devices, note that not all features may be available on all platforms.

Theme utilities

Item models

Item models are list of objects that support custom sorting and filtering, and can be used as the model property of QML Views (eg. ListView or PathView). See the Qt documentation for more details. For convenience, the modelData role is also provided for all item models mentioned in this documentation.

Sometimes you may want to access the items of an item model manually, in which case you can use the following members:

Sorting and filtering

Item models can be sorted and filtered using SortFilterProxyModel. Please see the samples in the linked documentation for usage tips. The list of all available sorters and filters can be found here.

For example, to get the list of all games ordered by play time, you could write a code similar to this:

import SortFilterProxyModel 0.2

...

SortFilterProxyModel {
    id: mysorter
    sourceModel: api.allGames
    sorters: RoleSorter { roleName: "playTime" }
}

ListView {
    model: mysorter
    ...
}

Fonts

Pegasus comes with a sans-serif and a sans-serif condensed font face, which are used in the main menu. If you want to use the same font families in your theme, you can access them using a global QML object called global.fonts. This has the following properties:

You can use them as the value for font.family members of Text items, eg. font.family: global.fonts.sans.

The default fonts currently in use are Roboto and Roboto Condensed.