# gameList Object

The gameList object represents the program's internal database of games. Methods on this object provide Javascript access to the list of loaded games and their details.

## Event target

gameList is an event target object, so you can use the standard event methods (on(), off(), addEventListener(), etc) to add and remove event listeners. See EventTarget.

gameList serves as the event target for the following event types:

## Properties and methods

The gameList object has the following properties and methods:

gameList.createCategory(name): Creates a new category with the given name.

gameList.createFilter(desc): Defines a custom filter, which selects games for the wheel UI according to a selection rule you define. desc is an object describing the filter. Returns a command ID, automatically assigned as a unique menu command for the filter. You can use the command ID to place the filter on custom menus. See Custom Filters for details and examples.

gameList.createMetaFilter(desc): Creates and installs a custom metafilter. desc is an object describing the new filter. See Metafilters for more details. The return value is an opaque identifier that uniquely identifies the filter, which can be used to later remove the filter via removeMetaFilter().

The new metafilter is placed into effect immediately, and the current game selection list in the wheel UI is refreshed so that the new filter is taken into account.

A metafilter is a "global" filter that's always active in addition to the current user-selected filter, allowing it to further narrow the games selected by the regular filter, or even completely override the decisions of the regular filter. More than one metafilter may be active at once, so creating a new one doesn't replace or remove any others that are already in effect.

gameList.deleteCategory(name): Deletes the given category. The category tag is removed from any games tagged with the given category, and the category is removed from the master list of categories returned by gameList.getAllCategories().

gameList.getAllCategories(): Returns an array with the names of all of the categories currently defined. Categories are arbitrary tags, defined by the user, that can be assigned to games for filtering purposes. Each category implicitly defines a "category filter" that the user can select through the menu system to show only games with the corresponding category tag. This lets the user select subsets of games based on personal criteria beyond the built-in filter options that the system provides.

gameList.getAllFilters(): Returns an array of filter IDs for all available filters. Each element is a FilterInfo object describing the filter.

gameList.getAllGames(): Returns an array consisting of a GameInfo object for each loaded games. The array is arranged in wheel display order, which is alphabetical by the display name of each game. If you need to iterate over all games, this is more efficient than calling getGame() for each game. In addition, the returned array is a snapshot of the complete game list at the time you call this function, so it isn't be affected by subsequent insertions, deletions, or reorderings of the live game list, as getGame() is. This makes it suitable for making edits to the live game list in the course of the iteration, since edits to the live list won't affect the snapshot and thus won't affect the iteration.

gameList.getAllWheelGames(): Returns an array consisting of a GameInfo object for each game on the wheel. That is, each game selected by the currently active filter. The first (0th) element of the array represents the currently selected game. Each subsequent element represents the next game to the right on the wheel. Since the wheel is conceptually circular, the last element is the game displayed in the wheel one position left from the current game.

gameList.getCurFilter(): Returns a FilterInfo object describing the filter currently selected in the wheel UI.

gameList.getFilterInfo(id): Returns a FilterInfo object describing the filter identified by id. The id value is a string with the filter ID. See FilterInfo for details.

gameList.getGameInfo(id): Returns a GameInfo object, which has properties to access most of the details of the specified game. id can be either a config ID string (the permanent identifier for a game, suitable for storing in an external location such as a config file) or a numeric game ID (the internal ID that refers to the in-memory record for a loaded game). If the ID is invalid or refers to a game that's no longer loaded, the function returns null.

gameList.getGame(n): Returns a GameInfo object representing the nth game in the loaded game list. n is an index into the list of all loaded games, ranging from 0 to the number of games in the list minus 1. Returns null if n is out of range. You can get the total number of games currently in the list from getGameCount().

gameList.getGameCount(): Returns the number of games in the list of all loaded games. You can retrieve individual games via getGame(n), where n ranges from 0 to the game count minus 1.

gameList.getWheelGame(n): Returns a GameInfo object representing the game at offset n from the selected game in the wheel. The currently selected game is at offset 0, so gameList.getWheelGame(0) refers to the current game. Offset 1 is the next game to the right of the current game, 2 is the next game to the right of that, and so on; -1 is the game to the left of the current game, -2 is the game to the left of that, and so on. Since the wheel is conceptually a circle, offset N comes back to the currently selected game when N is the number of games showing on the wheel (and by the same token, offset -N, 2N, -2N, etc all wrap back to the current game).

gameList.getWheelCount(): Returns the number of games currently shown in the "wheel" UI. This includes all games selected by the current filter.

gameList.refreshFilter(): Refreshes the filtered game list, as though switching to the current filter anew. This can be used after making any changes to game metadata or other factors that might affect which games are selected by the current filter, to ensure that the updated selections are immediately reflected in the wheel UI.

gameList.renameCategory(oldName, newName): Renames the given category. An error occurs if the category referenced by oldName doesn't exist, or if there's already an existing category with the new name. The category tag is renamed globally, so any games tagged with the old category name are updated to the new name.

gameList.removeMetaFilter(id): Removes the metafilter identified by id, which is an identifier returned from a previous call to createMetaFilter(). This cancels the specified metafilter and removes its effect on the game selection list. The current wheel selection list is updated as a side effect, as though you refreshed the current filter.

gameList.setCurFilter(id): Changes the active filter for the wheel UI. id can a string with the ID of the desired filter, or a number in the range command.FilterFirst to command.FilterLast (see Commands), identifying the filter by its associated menu command. The filterselect event is not fired when you change the filter with this function.