API reference (alpha)

Games found by Pegasus are organized in collections. Games can have metadata and various kinds of assets, and one game may be present in multiple collections.

All data provided by the Core is available in a global QML object called api. It has the following main components. Unless otherwise noted, all fields are read-only.

List of Collections

The list of collections can be accessed trough api.collections. It's an Object with the following members:

PropertyDescription
modelThe array of Collection items; can be used as the model parameter of dynamic layouts.
countThe number of Collection items in model. Positive integer.
indexThe index of the currently selected item of model. Writable, accepted values are positive integers less than count, and -1 (nothing selected). Setting invalid values will be ignored.
currentThe currently selected Collection. If index is -1, its value is null, otherwise equivalent to model[index]. current as a field is read-only, but the Collection itself has writable fields; see below.

Furthermore, it also has the following callable methods:

MethodDescription
incrementIndex()Increments the index by one. If the index was pointing to the last item, it jumps to the first one (ie. wraps around).
decrementIndex()Decrements the index by one. If the index was pointing to the firs item, it jumps to the last one (ie. wraps around).
incrementIndexNoWrap()Increments the index by one, if it's not pointing to the last item already.
decrementIndexNoWrap()Decrements the index by one, if it's not pointing to the first item already.

One Collection

api.currentCollection can be used as a shortcut for api.collections.current. A Collection has the following data members. Properties marked as "optional" might have no value (eg. empty string or empty array).

PropertyDescription
nameThe unique name of the collection, eg. "Nintendo Entertainment System", "Mario Cartridges", etc.
shortName An optional, lowercase short name for the collection. Often an abbreviation, like nes, mame, etc.
gamesObject storing the list of games (see below).

List of Games

Similarly to the list of collections, api.currentCollection.games is an Object with the following members:

PropertyDescription
modelAllThe array of all Game items in this collection; can be used as the model parameter of dynamic layouts.
modelThe array of Game items matching the currently active Filter (see later); can be used as the model parameter of dynamic layouts.
countAllThe number of items in modelAll. Positive integer.
countThe number of items in model. Positive integer.
indexThe index of the currently selected item of model (not modelAll, since you can't select a game you've hide with a filter). Writable, accepted values are positive integers less than count, and -1 (nothing selected). Setting invalid values will be ignored.
currentThe currently selected Game. If index is -1, its value is null, otherwise equivalent to model[index].

Furthermore, it also has the following callable methods:

MethodDescription
incrementIndex()Increments the index by one. If the index was pointing to the last item, it jumps to the first one (ie. wraps around).
decrementIndex()Decrements the index by one. If the index was pointing to the firs item, it jumps to the last one (ie. wraps around).
incrementIndexNoWrap()Increments the index by one, if it's not pointing to the last item already.
decrementIndexNoWrap()Decrements the index by one, if it's not pointing to the first item already.

One Game

api.currentGame can be used as a shortcut for api.collections.current.games.current. A Game is an Object with the following data members. Properties marked as "optional" might have no value (eg. empty string or empty array).

PropertyDescription
titleGame 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 Developers as an array.
publisherList Publishers as an array.
genreList Genres as an array.
summary Short description (2-3 sentence or less)
description Longer description
release Release date as QML date (default: invalid)
year Release year as integer (default: 0)
month Release month as integer (default: 0)
day Release day as integer (default: 0)
players Maximum number of players (default: 1)
rating Floating-point value between and including 0.0 and 1.0 (default: 0.0)
assetsAn Object containing game assets (see below)
favorite Boolean (true/false) value (default: false). Writable.
playCount Positive integer (default: 0)
playTime Play time in seconds, positive integer (default: 0)
lastPlayed As QML date, incl. time (default: invalid)

Game Assets

Every Game has an asset member Object with the following data members. All of them are string URLs, 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.

Launching games

You can select a game by changing api.collections.index and api.currentCollection.games.index. Then call api.launchGame to start the game.

Filtering games

api.filters is an Object with the data members below. Changing these values will automatically update all Collection's model field to include Games that match all filters. All fields are writable.

PropertyDescription
titleMatch games whose titles contain this string. String value. (default: empty)
playerCountMatch games that have at least this many players. Positive integer. (default: 1)
favoriteSetting to true includes only games marked as favorite. Boolean (true/false) value. (default: false)

Note

At the moment, the indices of the game lists reset to 0 or -1 (no hits) when the Filter changes.

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.

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

Info

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.