API reference (alpha)

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

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:

PropertyDescription
nameThe unique name of the collection, eg. "Nintendo Entertainment System", "Mario Cartridges", etc.
shortName A short name for the collection, often an abbreviation like nes, mame, etc. Always in lowercase. If not set, defaults to the value of name.
summary Short description (typically 2-3 sentences).
description Longer description.
gamesThe list of games belonging to this collection; see "Games" below. All available collections are guaranteed to have at least one game.
assetsAn object containing the default assets (see later).

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:

PropertyDescription
titleThe game's title
developer Developer(s) as a string. If there are more than one, they are separated with ,.
publisher Publisher(s) as a string. If there are more than one, they are separated with ,.
genre Genre(s) as a string. If there are more than one, they are separated with ,.
developerList The list of developers as an array.
publisherList The list of publishers as an array.
genreList The list of genres as an array.
summary Short description (typically 2-3 sentences).
description Longer description.
release Release date as QML date. If not set, defaults to an invalid date.
year Release year as integer. Defaults to 0.
month Release month as integer. Defaults to 0.
day Release day as integer. Defaults to 0.
players Maximum number of players. If not set, defaults to 1.
rating Floating-point value between and including 0.0 and 1.0 (ie. 0% and 100%). If not set, defaults to 0.0.
favorite Boolean (true/false) value. If not set, defaults to false. This field is writable.
playCount The number of times this games was launched. Defaults to 0.
lastPlayed The last time this game was launched. A QML date value with time information. Defaults to an invalid date.
playTime Play time in seconds, as a positive integer value. Defaults to 0.
filesAn object containing the game's launchable files (see below).
assetsAn object containing the game's assets (see later).

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:

MethodDescription
launch()Launch this game. If the game has more than one launchable file, the default file selector of Pegasus will appear.

Game files

Experimental

This section is experimental and may change in the future.

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:

PropertyDescription
nameThe pretty name of this file.
pathThe path to this file.
playCountThe number of times this file was launched. Defaults to 0.
lastPlayedThe last time this file was launched. A QML date value with time information. Defaults to an invalid date.
playTimePlay time in seconds, as a positive integer value. Defaults to 0.

Note

At the moment name comes from the filename of the file. In the future, this could be set in the metadata format.

In addition, games have the following callable methods:

MethodDescription
launch()Launch this game file.

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.

PropertyDescription
boxFrontThe front of the game box
boxBackThe back of the game box
boxSpineThe spine (side) of the game box
boxFullFull size box art (front + back + spine)
cartridgeImage of the game medium (cartridge, floppy, disk, etc.)
logoThe game's logo, usually the title art over a transparent background

box-related assets

PropertyDescription
marqueeA wide (often over 3:1) artwork on the top of arcade machines
bezelDecoration around a game's screen on an arcade machine or emulator
panelControl panel of the arcade machine
cabinetLeftLeft side of the arcade machine
cabinetRightRight side of the arcade machine

box-related assets

PropertyDescription
tileA square-sized image (not the desktop icon)
bannerAn image in 16:9 aspect ratio
steamSteam grid icon, 460:215 ratio (most often 460x215, some people use 920x430)
posterAdvertisement poster, usually with 2:3 aspect ratio (in general a portrait-aligned image)
backgroundA background image, eg. artwork or selected screenshot
musicBackground music

box-related assets

In addition, the following members can have multiple values, and as such usable as eg. model sources. All of them can be empty.

PropertyDescription
screenshotsArray of strings, each a URL to an image.
videosArray of strings, each a URL to a video source.

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.

PurposeCheck functionArray
accept/selectisAccept(keyevent)accept
cancel/backisCancel(keyevent)cancel
detailsisDetails(keyevent)details
filtersisFilters(keyevent)filters
next pageisNextPage(keyevent)nextPage
previous pageisPrevPage(keyevent)prevPage
page upisPageUp(keyevent)pageUp
page downisPageDown(keyevent)pageDown

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

Warning

For regular navigation (ie. up/down/left/right), the QML KeyNavigation can be used (documentation here). Navigation keys (arrows/dpad/left stick) cannot be changed at the moment.

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:

MethodDescription
set(key, value)Sets the value belonging to key. If key already exists, its value will be overwritten.
get(key)Returns the value belonging to key, if there is any, otherwise returns undefined.
has(key)Returns true if key is set (has value), otherwise returns false.
unset(key)Removes key and its value.

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();
}

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. To query the number of items in the model, you can check its count property (eg. api.allGames.count), while to get a single item of it, you can use the get(index) method (eg. api.allGames.get(5)).

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 globalFonts. This has the following properties:

PropertyDescription
sansThe sans-serif font
condensedThe sans-serif condensed font

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

The fonts currently in use are Roboto and Roboto Condensed.