Writing QML themes for QMC2 Arcade

From BATCOM-IT Services Wiki
Jump to: navigation, search

A guide to creating themes for QMC2 Arcade

WIP This page is still under construction!

Introduction

QMC2 Arcade is our new, purely graphical (non-desktop) approach to a MAME/MESS/UME front-end, using the declarative QML language (part of Qt Quick) for implementing all scene-graphics, effects, animations and user-interactions -- which is what we call a theme.

This page is about writing your own themes for (and integrating them in) QMC2 Arcade, it's not about learning QML / Qt Quick. However, although we make the assumption that you're already familiar with it, you shouldn't hesitate to ask (see contact information), preferably via our development mailing-list. After all, we also learned QML by just doing this stuff ;)...

In any case, contributing a new theme to QMC2 Arcade will be greatly appreciated! It's your opportunity to support us and at the same time give something back to the emulation community fairly quickly, without reinventing the wheel by investing years to create a neat and stable front-end. The main thing that's required is your creativity, and some basic idea of how the new theme should to look like and respond to user-interaction.

The Qt/C++ back-end

QMC2 Arcade's Qt/C++ back-end is the heart of the front-end. Its main responsibility is to set up the environment to run the QML theme. Additionally, it exposes an easy-to-use run-time QML interface to access the game-/machine-list and through which it provides the theme with the available images and textual info data for a given system. It also manages the global and theme-specific settings and launches the actual emulator instances when the theme requests it. So basically it hides all the dirty stuff from the QML themes which should thus concentrate on the look'n'feel and use its JavaScript-based logic scripting mainly for this purpose. However, it's totally up to the author of the theme to decide what his/her theme should do exactly, how it does it and which of the possible features it shall support.

Adding the new theme to the back-end

One of the first things you should decide for is which emulators to support with your theme: MAME, MESS, UME or even all? QMC2 Arcade has been designed to support all emulators that QMC2's main GUI supports, all in one binary. But the emulator mode that it's currently running in may restrict the use of certain themes. So you have to tell QMC2 Arcade what your theme supports and make it generally known.

Add your theme in main.cpp, let's say it's a MESS-only theme and we call it Machinery:

...
int main(int argc, char *argv[])
{
    ...
    arcadeThemes << "ToxicWaste" << "darkone" << "Machinery";
    mameThemes << "ToxicWaste" << "darkone";
    messThemes << "Machinery";
    umeThemes << "ToxicWaste" << "darkone";
    ...
}

Add an index constant for your theme to macros.h:

...
 // indexed QML themes
 #define QMC2_ARCADE_THEME_TOXICWASTE  0
 #define QMC2_ARCADE_THEME_DARKONE     1
 #define QMC2_ARCADE_THEME_MACHINERY   2
 ...
 

Notes:

  • The index specified here must correspond to the position that the theme's name has in the arcadeThemes string-list!
  • Theme indexes enable us to use switch rather than if-else-if-else-... clauses for nicer back-end code.

Enabling property restoration for the theme

...

Defining theme-specific key-sequences

...

The QML theme

...

QtQuick 1.1 (Qt 4.8) vs. QtQuick 2.0 (Qt 5)

...

Accessing the game-/machine-list

...

Requesting images

...

Requesting game-/machine- and emulator-info records

...

Launching games/machines

...

Launching software

(for future use)

Viewer method reference

...