### README - v0.38, 11-JAN-2013

### Contents

1. What is the M.A.M.E./M.E.S.S./U.M.E. Catalog / Launcher II?

2. Build and installation instructions

3. Command line arguments and configuration

4. Game/machine list statistics, ROM status and the ROMAlyzer

5. GUI style plugins and Qt style sheets

6. Short cuts, GUI control keys and joystick support

7. External tools and tool argument syntax

8. Multi-platform support

9. Contact

10. Contributing

11. License and copyright

12. Legal notice

### 1. What is the M.A.M.E./M.E.S.S./U.M.E. Catalog / Launcher II?

M.A.M.E./M.E.S.S./U.M.E. Catalog / Launcher II -- also referred to as QMC2 -- is the successor of one of the first UNIX MAME GUI front ends available on this planet called QMamecat (derived from MAMECAT, which was text-only).

QMamecat was based upon Qt 2; its development was frozen in 2003. QMC2 has been rebuilt from scratch as a Qt 4 project. Parts of the design and code were inspired by its predecessor, but it's not just a remake. We tried to make the new design as flexible as possible to minimize dependencies from front end and CLI related MAME changes, which was a major deficiency of QMamecat. QMC2 now uses a template based emulator configuration scheme, which can easily be enhanced with additional command line options (defined in an XML template file).

As a result of this flexible design, QMC2 can be used for multiple emulators today. On UNIX and Mac OS X we currently support SDLMAME, SDLMESS & SDLUME, on Windows you have the choice between the original variants of MAME, MESS & UME.

QMC2's current major features include:

- Extremely fast drawing of game/machine images, optionally smoothly scaled (PNG images, buffered in a resizable LRU-cache)
- Support for game/machine icons -- historically only PNG images, but when stored in ZIPs, nowadays also ICO format is supported
- Icons and all game/machine images can either be stored as individual files in respective directories or they can be combined and compressed in ZIP archives
- Easily extensible template-based emulator configuration scheme (defined through an external XML file)
- Cool editor for configuration of global and game/machine-specific emulator options, including a search function
- Support for all emulation-related extra information available through the emulator (displayed in a tree)
- Fast search function with automatic wildcard pattern matching
- All emulator targets: selectable sort criteria and order for game/machine lists (description, name/ID, ROM state, year, manufacturer and ROM types)
- Straightforward process management to control emulator processes
- Clear and full logging (separate front end and emulator logs)
- Cached ROM state verification, indicated as colored spheres in front of each game/machine description
- Verification of sample sets
- Game/machine image checks (icons, previews & flyers)
- Online display of current game/machine list and search result statistics
- All emulator targets: two different views of the game/machine list: full detail and parent/clone hierarchy
- Optional additional category-oriented (MAME/MESS/UME) and version-oriented (MAME/UME) views when catver.ini and/or MESS category.ini support is enabled
- The GUI will always remain interactive even if heavy background processing is running
- Time-consuming background tasks can be stopped on demand at (nearly) any time
- Optional auto-save/restore of window layout and game/machine selection
- Multi-platform support (Linux/UNIX, Mac OS X and Windows)
- Fully multi-language capable -- right now, translations exist (or are being worked on) for English (us), French (fr), German (de), Greek (el), Italian (it), Polish (pl), Portuguese (pt), Romanian (ro), Spanish (es) and Swedish (sv)
- Game/machine favorites management and play-history
- Online HTML documentation and browser
- Designed to be used for multiple emulators: SDLMAME/SDLMESS/SDLUME on UNIX and Mac OS X, MAME/MESS/UME on Windows -- plus support for additional foreign emulators on all platforms
- Built-in support for GUI styles and Qt style sheets (.qss)
- Automatic caching of analysed game/machine data to speed up processing
- Import & export of emulator configuration files (i. e. mame.ini/mess.ini)
- All short cuts and GUI control keys can be remapped
- Removal of obsolete samples and image files (stored in directories or ZIP archives)
- Automatic caching of XML output from the emulator
- Built-in ROMAlyzer to deeply analyze a game's/machine's ROMs (including repair- and rewrite-functionality for zipped sets) and CHDs -- inspired by Carsten Engel's ROMAlyzer script (see scripts/romalyzer.pl in source distribution)
- Optional use of OpenGL features (currently only for image painting)
- Support for direct GUI control via analog and digital joysticks through SDL (Simple Directmedia Layer)
- Detailed game/machine information from MAME's history.dat game information database and MESS' sysinfo.dat machine information database (the UME variant goes the MAME route here)
- Basically the same for mameinfo.dat as MAME's emulator information database and messinfo.dat in case of MESS (again, the UME variant acts like the MAME variant here)
- Support for output notifications via a named pipe on UNIX and Mac OS X (see emulator control panel)
- Built-in audio- and (YouTube-)video-players based on the Phonon API
- ROM status export to clipboard or file as ASCII, CSV or HTML
- Integrated MESS device configuration with support for mapping of files to device instances & machine slots, as well as an easy-to-use file chooser for simple file-to-device mapping
- All (SDL)MAME, (SDL)MESS and (SDL)UME variants of QMC2 supported on the respective target platform can launch each other
- Freely adjust the order and visibility of available game/machine details
- MAWS web lookup for all MAME variants, including automatic caching of all successfully loaded MAWS ROM set pages
- MAWS quick download: when visiting a game's MAWS page, automatically download available image data usable by QMC2
- ProjectMESS system search for all MESS & UME variants
- X11 and Windows platforms: optional / on-demand embedding of emulator windows
- Freely adjustable layout of the main widget's major sub-widgets
- MAME/UME targets only: demo mode to run random games for a specific period of time (in a mode suitable for demo purposes)
- Support for software-lists, including favorites management, search feature and sneak previews in-game/run-time snap-shots, plus an extra software-detail widget with a scaling preview image, a ProjectMESS software look-up and a WYSIWIG editor for personal rich-text notes
- Dock-able/floating software-detail widget with a separate snapshot-browser, a ProjectMESS software-lookup feature, and an HTML editor/viewer for personal rich-text software-notes
- Item tagging and related 'batch-mode' operations
- A QML based standalone graphical arcade mode binary (QMC2 Arcade) which utilizes the cached data of its bigger brothers to quickly display and launch emulators and get you "straight into the games" :)

### 2. Build and installation instructions

Please see this FAQ section for instructions on specific distributions.

Software requirement | Where to get
All: Qt 4.7.0+ (Qt 4.8.4+ recommended) | http://releases.qt-project.org/qt4/source/
UNIX & Mac OS X: GNU make 3.80+ | http://ftp.gnu.org/gnu/make/
Mac OS X: Xcode 3.2+ | http://developer.apple.com/technologies/xcode.html
Windows: VC++ 2010 | http://www.microsoft.com/visualstudio/eng/products/visual-studio-2010-express
Windows: MinGW MAME dev-tools | http://mamedev.org/tools
All: MAME/MESS/UME 0.147+ | http://mamedev.org/release.html http://www.mess.org/download.php
Additional tools (optional) All: zip 2.32+ (3.0+ recommended) UNIX and Mac OS X: common rm command Windows: built-in shell command del | http://www.info-zip.org http://ftp.gnu.org/gnu/coreutils/
Joystick support (optional) All: SDL 1.2.13+ Windows: DirectX SDK Mac OS X: SDL 1.2.15+ recommended | http://www.libsdl.org http://www.microsoft.com/downloads/en/details.aspx?displaylang=en&FamilyID=3021d52b-514e-41d3-ad02-438a3ba730ba&pf=true http://www.libsdl.org/release/SDL-1.2.15.dmg
Video codecs (optional) Linux: usually included Windows: W7 Codec Pack Mac OS X: QuickTime 7 | Required at run-time: Linux Phonon back-ends like xine, gstreamer or VLC should include everything you need. http://www.windows7codecs.com/ Qt comes with a back-end plugin for QuickTime 7: http://www.apple.com/quicktime/download/

Building the QMC2 binary on UNIX and Mac OS X

Uncompress and untar the source distribution archive, then cd into the source directory:

    $ bzip2 -d qmc2-<version>.tar.bz2
    $ tar xvf qmc2-<version>.tar
    $ cd qmc2

Side note: at this point, you may have to create (or adjust) an OS-dependent configuration file, if your platform should not be in the list of tested operating environments; if applicable, see section 8. for more details.

Usually, you should be able to just start the build process by calling make, which (among other things) will call qmake to create a tailored makefile (Makefile.qmake) for the target system and call a second make job with that file as input:

    $ make

The default build configuration assumes that the qmake command is part of your search path for executable files (see the PATH environment variable). If you want/need to use a different qmake (i.e. to use a separately installed Qt version), you have to specify QMAKE=<path-to-qmake> on the make command line. For example:

    $ make QMAKE=/usr/local/lib/qt-4.8.4/bin/qmake

If you have an SMP system, you may want to run make in job-server mode. This is completely safe and usually much faster:

    $ make -j3

(replace "3" with "#CPUs + 1")

QMC2 is generally prepared to support multiple emulators. However, you have to choose which target emulator you're going to build it for. SDLMAME is the default emulator on UNIX and Mac OS X. To build QMC2 for other potential emulators, use the EMULATOR make option:

    $ make [-jX] EMULATOR=<emulator-name>

Joystick support is optional (but enabled by default) and requires SDL - the Simple Directmedia Layer. If you would like to disable it, for example because SDL is not supported on your OS (huh?), you could use the JOYSTICK make command line option to do so:

    $ make [-jX] JOYSTICK=0

The QMC2 build system will automatically enable the use of Qt's Phonon integration for some multimedia functionality (built-in audio & video players). This feature is completely optional though, and as it requires a working Phonon environment -- especially a working back-end such as gstreamer, VLC or xine -- you can disable it at compile time. Use the PHONON make command line option to accomplish that:

    $ make [-jX] PHONON=0

QMC2's Phonon features include the support for game/machine attached YouTube videos, which may require additional codecs to be installed (see table above for recommended video codecs). Since we can't be sure there's sufficient back-end support everywhere, we made this sub-feature completely optional, and you can even disable the YouTube video player at compile-time (when PHONON=0 is set, this will be done automatically):

    $ make [-jX] YOUTUBE=0

Note that nearly all* of the supported make command line options can be freely combined when make is called, and non-string build options can alternatively be set as environment variables.

See

    $ make help

for a list of make targets and configuration options.

*: The only exceptions are DISTCC and CCACHE which cannot be enabled at the same time. However, on a correctly set up icecream cluster for example, you can omit the DISTCC option and thus use CCACHE at the same time.

IMPORTANT NOTE

Pease never ever run qmake standalone -- when qmake is called directly, important settings may be missing in the resulting Makefile.qmake file. If you see strange errors like undeclared MAJOR / MINOR variables, this simply means you've run qmake yourself -- prior to version 0.2.b6 this even destroyed QMC2's Makefile, but that's at least avoided now by forcing qmake's output to be stored as Makefile.qmake in the project definition.

We've been asked about this so many times that we thought it would be necessary to make it absolutely clear that everything is controlled by make rules and thus you should only call make and nothing else!

Ending the rant here :).

Instead, qmake will be called by make and it will pass a lot of important arguments to qmake which depend on the local situation. On a clean source tree you'll see what's passed to qmake in the first line of the output (that is, if not called with QUIET=1). If you'd call qmake exactly this way it would work, though.

Installation on UNIX and Mac OS X

As soon as QMC2 has been compiled and linked completely, it's ready for use. There is basically no need to explicitly install QMC2 as it has been designed to work fully self-contained. Even the data-directory can be kept locally, which works well.

However, it's still advisable to install QMC2 system-wide (you have to do this as root). The user's configuration and his data will be kept locally (in $HOME/.qmc2/ on most *NIX or ~/Library/Application Support/qmc2/ on OS X):

    $ su
    Password:
    # make install [EMULATOR=<emulator-name>]
    # exit

The QMC2 binary will be named as qmc2-emulator (i.e. qmc2-sdlmame or qmc2-sdlmess), depending on the value of the EMULATOR make option. However, a symbolic link named qmc2 will created in the binary installation directory on make install which links to the binary file that was last installed.

The system-wide default configuration will be installed to /etc/qmc2/qmc2.ini or /etc/qmc2/qmc2.ini.new (if an older version of that file already exists). In case of an update, you should check /etc/qmc2/qmc2.ini.new for any new settings and add them to /etc/qmc2/qmc2.ini manually!

Note that in order to use the QMC2 variant launcher -- one QMC2 variant can launch (or switch to) the other -- it's required that all binaries are in your search path (including the runonce launcher wrapper)!

Building the QMC2 binary on Windows

The build steps on Windows using Visual C++ are completely different than the ones on UNIX and Mac OS X. However, since v0.2.b20 we also support MinGW builds on Windows which is more or less the same process as on UNIX and Mac OS X (see MinGW below).

Using Visual C++ 2010:

1. Install all software requirements mentioned above.
2. Extract all contents from the QMC2 source distribution archive into a directory (or use the code from the SVN repo: TortoiseSVN is a nicely working SVN client for Windows which we use ourselves).
3. For correct embedding of static images that QMC2 uses (mostly icons) it's necessary to copy all image files from data\img\classic\ to data\img\, overwriting the existing symbolic links (this is due to the fact that we are relinking the images on UNIX and Mac OS X, but on Windows this doesn't work). If you'd like to exchange some images with those in other image sets (see sub-directories below data\img\, i. e. crazy\ or crazy-black\), copy these files over the ones that are in data\img\ now.
4. Edit the batch script scripts\generate-vcprojects.bat and adjust the path variables at the beginning of the script. Note that the script requires sed for Windows (and optionally TortoiseSVN when using code from the SVN repo).
5. Make sure the current working directory is the top-level path of where you extracted the QMC2 sources and run scripts\generate-vcprojects.bat. This will create two additional sub-directories (debug\ and release\) and generate six VC++ project files: qmc2-mame[-x64].vcxproj, qmc2-mess[-x64].vcxproj and qmc2-ume[-x64].vcxproj.
6. Open one (or all) of the project files in Visual C++ 2010 (double-clicking the .vcxproj files should also work).
7. For 64-bit, be sure to adjust the project's (or solution's) target-architecture to x64!
8. Select Build from the project's context menu to create the front-end executable, which you will find in the release\ sub-directory after it has been successfully built.
9. If you're going to build both variants, don't forget to clean up the project before you start the second build process!

Using the MinGW (GCC) compiler:

1. Get and install the latest MAME dev-tools.
2. Call 'make' as usual, that is like on UNIX or Mac OS X.
3. If you want to run make in jobserver-mode (to utilize multiple CPUs during compilation), you have to run 'make configure' followed by 'make -j <#CPUs + 1> -f Makefile.qmake.Release'.

Installation on Windows

Provided that all necessary DLLs are included in paths pointed to by %PATH%, an installation isn't really required on Windows. As on UNIX and Mac OS X, you can simply start the executable (release\qmc2-<emulator>.exe), just make sure the current working directory is the top-level QMC2 source path to make it find its data files automatically (most -- if not all -- default paths are relative to the build directory).

If you would like to create binary packages, all you'd have to do is copy the relevant files (binaries/DLLs and data) into a directory which you package as an archive afterwards (using zip or rar, for example). The installation at a user's end would then just be to extract this archive. That's it! There's nothing like a script to support you in that, though.

Besides the VC runtime DLLs (if built with MSVC), the required DLLs include:

    imageformats\*.dll
    phonon_backend\phonon_ds94.dll
    phonon4.dll
    QtCore4.dll
    QtGui4.dll
    QtNetwork4.dll
    QtOpenGL4.dll
    QtSql4.dll
    QtTest4.dll
    QtXml4.dll
    QtXmlPatterns4.dll
    QtWebKit4.dll
    sqldrivers\qsqlite4.dll
    SDL.dll

Note that variant launching on Windows generally assumes that both QMC2 variants (qmc2-mame.exe & qmc2-mess.exe) can be found in the same directory. It will usually not search in any other path than the one it was launched from initially! However, due to popular demand by our Windows users, we've added support to allow for customizing this as well. See Q2.11 in the FAQ for more information!

The QMC2-dev team is releasing binary packages for Win32 in exactly this way since v0.2.b8 (only final versions, though). These official packages also include an installer for the VC runtime DLLs (vcredist\vcredist_x86.exe).

### 3. Command line arguments and configuration

Usage:

    $ qmc2[-emulator] [-qmc2_config_path <alternate_configuration_path>] [-cc] [qt4_arguments]

Arguments in detail:

- -qmc2_config_path: See configuration path below!
- -cc: When this CLI option is specified, all emulator caches will be cleared (removed) before the application actually starts up. This is useful whenever the emulator version doesn't change and QMC2 can't figure out that it's time to update the caches because of this (so this mainly applies to those users that are often updating their MAME/MESS/UME installation from the public SVN repository).
- qt4_arguments: See the QApplication class reference for details on what Qt 4 arguments are available (note, however, that some of these arguments are useless since QMC2 will overwrite them with its saved ini-settings).

Configuration path

When the -qmc2_config_path option is specified on the command line, QMC2 will use this directory instead of the default 'dot-path' (see configuration notes below). Note that it's in your responsibility to copy/move the data to its desired place prior to starting QMC2 when this option is set, otherwise QMC2 will start over (which may be wanted behavior, though). Also, any settings that may have inherited the previous dot-path will have to be changed manually (probably by editing qmc2.ini, but take care).

Notes on the configuration of QMC2

UNIX and Mac OS X:

- The user's configuration file will be stored as ~/.qmc2/qmc2.ini on UNIX, or as ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X.
- A system-wide default configuration can be used to pre-configure QMC2 for your users (common paths: /etc/qmc2/qmc2.ini on UNIX, or /Library/Application Support/qmc2/qmc2.ini on Mac OS X).

Windows:

- The user's configuration file will be stored as %USERPROFILE%\.qmc2\qmc2.ini on Windows.
- A system-wide default configuration for all users isn't supported (yet).
- All paths need to be specified POSIX-like, that is backslashes ("\", Windows) become slashes ("/", POSIX) within QMC2 -- so don't be surprised when you see paths like C:/some/directory (instead of C:\some\directory) in QMC2, because that's how it's supposed to look like :)! The only exception is the command displayed on the emulator control panel (and in the front end log) because it may be copied to clipboard and reused on the command line directly (which wouldn't work with slashes in path names).

All platforms:

- If no configuration can be found for a specific option, hard-coded default values will be used for all front end settings (see code); default values for the emulator configuration are read from the current XML template (default paths: /usr/local/share/qmc2/opt/<EMULATOR>/template.xml on UNIX, /Library/Application Support/qmc2/opt/<EMULATOR>/template.xml on Mac OS X, and data\opt\<EMULATOR>\template.xml on Windows).
- If the path to the emulator's executable file has not been set (yet), QMC2 will assume that you are starting it for the first time (your setup is considered incomplete as long as this option hasn't been set).
- Although it is recommended to edit the configuration with the built-in setup dialog, you may change it manually with any editor at your own risk -- only do this if QMC2 is not currently running, though!

### 4. Game/machine list statistics, ROM status and the ROMAlyzer

Game/machine list statistics are shown in the lower-left corner of the main widget, below the game/machine list. The letters - and their colors - have the following meanings:

Letter | Color | Icon | Meaning / Description
L | black | -- | Number of Listed games/machines This is the overall number of games/machines the emulator supports.
C* | green |  | Number of Correct games/machines All dumps exist emulator-wise; they also exist in your local collection, and their header checksums are the expected ones. The game/machine will most likely work fine (provided its driver is mature enough).
M* | yellow-green |  | Number of Mostly correct games/machines One or more dumps are missing or bad (emulator-wise), but your collection has all (correct) dumps that are available. The game/machine may not work (as expected), but most of the time it will run fine (provided its driver is mature enough).
I* | red |  | Number of Incorrect games/machines One or more dumps in your collection are bad (there may also be missing or bad dumps emulator-wise). The game/machine may not work, and most of the time it won't.
N* | grey |  | Number of games/machines which were Not found One or more required dumps are missing in your collection (there may also be missing or bad dumps emulator-wise). The game/machine will not work.
U | blue |  | Number of games/machines with an Unknown ROM status The ROM state of the respective game/machine hasn't been checked yet (or something went wrong during the check, or the check was prematurely interrupted).
S | chocolate | -- | Number of game/machine-matches for the current Search-pattern (if any)
T | sandybrown | -- | Number of sets currently Tagged

*: These numbers are only available when the ROM state has been checked.

If any statistical number is yet undetermined, a question mark (?) is shown instead.

Individual ROM states are displayed in the game/machine list itself, indicated by colored sphere icons in front of each game/machine entry (see table above). When using the classic image set, BIOS ROMs will contain a white B in their ROM status icons. Device ROMs contain a white D and cannot run standalone. Other (= non-default) image sets may indicate BIOS and device ROMs differently.

Depending on your hardware, ROM status determination may be a very time-consuming task, so it's not started automatically. You have to explicitly trigger a ROM check (see Tools menu) at least once. To speed up this process for future runs, ROM states are cached in an external ROM state cache file (default: ~/.qmc2/<emulator>.rsc on UNIX, ~/Library/Application Support/qmc2/<emulator>.rsc on Mac OS X, or %USERPROFILE%\.qmc2\<emulator>.rsc on Windows). If QMC2 finds cached ROM state information in this file, it will read the states for each game/machine from the cache when the game/machine list is reloaded.

Unless the option AutoTriggerROMCheck hasn't been activated, it is in your responsibility to trigger a re-check of the ROM states when anything changes (ROM images or MAME/MESS updates). If the number of totally supported games/machines (by the emulator) is different than the number of cached ROM states, QMC2 will log a warning to the front end log (and optionally trigger an automatic ROM check, if AutoTriggerROMCheck has been set).

QMC2 also supports individual ROM checks, so changes to only some games/machines of your collection do not force you to fully re-check every ROM. For MAME/MESS updates there's probably no way around it, though (unless you know which games/machines have changed or have been added).

ROM states can be used to filter and/or sort the detailed game/machine list (a.k.a. the master list). Please note that as a matter of principle the ROM state filter can't be applied to the hierarchical parent/clone view of the game/machine list, because the display of clones depends on the display of their parents. The optional views 'by version' and 'by category' (which are only available when the use of catver.ini and/or MESS category.ini has been enabled) are also not filtered.

BTW, the words game, machine or system are used as synonyms throughout QMC2. The MAME and UME variants prefer to operate on games, whereas the MESS variants operate on machines (or systems).

ROMAlyzer

Since v0.2.b1, there is also a so called ROMAlyzer which allows to deeply scan individual (or multiple) games/machines for their exact ROM state. This work was inspired by Carsten Engel's romalyzer.pl Perl script (see scripts/romalyzer.pl in the source distribution) - he also offered very helpful comments on ROM identification and how to handle CHDs. Thanks!

ROMAlyzer features, tips and restrictions:

- Imitates the emulator's way of finding ROMs, using their CRCs to identify the individual ROM files (in ZIPs).
- Uses the XML game/machine data to compare (expected) checksums and sizes as well as to know which ROM & CHD files are required, if they need to be merged from other sets etc.
- ZIP-archived ROMs will be decompressed and their checksums will be recalculated on-the-fly (this will also identify ZIP-archives with invalid file integrity) -- note that ZIPs are required to have no sub-directory structure, otherwise the results may vary (this is unsupported but should work).
- ROMs which are stored in game/machine-directories (not ZIP-archived) will be loaded to calculate their hashes.
- All required hash algorithms are supported: CRC(-32), SHA1 and MD5.
- CHD verification is accomplished through the comparison of the header checksums with the expected hash values; you can optionally enable deeper file integrity verifications through the CHD manager (chdman) which is thus required to use this feature (slow).
- The CHD manager will allow you to optionally update your CHDs on-the-fly if applicable -- backup your CHDs before enabling automatic updates! Also, make absolutely sure you're using the latest version of chdman, that is, the version that came with your current MAME/MESS/UME release (the minimum required version is 0.145u1!). QMC2 assumes that CHD version 5 is the latest and greatest format, and it will only try to update a CHD if its version is less than that.
- For best performance, choose a temporary working directory for the CHD manager which is on the same file system as the CHDs you're analysing (i.e. your ROM path). The reason for this is that in the final step we simply rename/move the updated chdman's output to replace the old CHD.
- If QMC2 is unable to replace an updated CHD (for instance due to missing write permission on the ROM path) it will keep the updated file in the CHD manager's temporary working directory and you'll need to copy/move it manually.
- ROM and CHD files will never be fully loaded into memory while analyzing, only small blocks (or hunks) of data are read for hash calculation and dropped directly afterwards. However, the 'set rewriter' (see below!) will load all (uncompressed) data of a set into memory -- so if you want to use that function, a system with at least 4 GB RAM is recommended (it actually only depends on the largest ROM set available in MAME/MESS/UME, not counting any CHDs here).
- Long ROMAlyzer runs can be paused / resumed or interrupted at nearly any time. Except when a set is currently rewritten, interruptions take place immediatly, and any running external process (like chdman for example) will be terminated. Pausing the analysis is nicer and takes place asynchronously, waiting for the current set to finish its analysis.
- ROM sets that use merged files will also be checked for their merge-states. Possible states include:
  - OK (green) -- all merged files are at their expected places and are taken from the parent set
  - WARNING (yellow) -- one or more files to be merged are taken from the child set, but if the parent set already has the files (needs it anyway), they can be considered obsolete within the child set (it's OK, but you can free some space by reorganizing your sets)
  - CRITICAL (red) -- one or more files to be merged are not found or otherwise 'bad' in both the parent and the child sets
- The checksum wizard will allow you to search for an SHA1 or CRC checksum in all sets. You can use it to qualify the states and locations of the respective files and to automatically repair 'bad' sets when 'good' sets exist.
- You can enable the so called set rewriter to recreate clean new ZIPs (does not include CHDs!). Things to note about the set rewriter:
  - Take backups of your primary ROM data before you replace it with the ZIPs created by the set rewriter!
  - NEVER use one of your primary ROM paths as the output directory for the set rewriter!
  - When you have update ROMs, you can point the set rewriter to them (see 'additional ROM path'). You can enter a semicolon-separated list in the way as MAME/MESS/UME's rompath parameter accepts it to specify multiple paths!
  - When the source data is bad and/or incomplete, the results will not be better. First get your ROM sets working before you dare to run the set rewriter in order to clean them up!
- Take a look at the ROMAlyzer's log for a more detailed analysis report.

### 5. GUI style plugins and Qt style sheets

GUI styles can be switched on-the-fly by explicitly selecting available style plugins from the respective combo-box in the setup dialog (see Front end -> GUI). If you installed additional style plugins to Qt, these will be available here as well.

The Default GUI style is the desktop's default style.

KDE styles are supported if they were made for KDE 4 (Qt 4)!

Since v0.1.b11, support for style-specific custom color palettes (which can be setup with qtconfig) has been added. The default behavior of QMC2 is to use the default palette. You can disable this via the StandardColorPalette setting to use the customized color palette instead - if applicable (see Front end -> GUI in the configuration dialog).

Note that some add-on GUI styles may look ugly or be even buggy (older versions of the Oxygen style, for example, were known to raise an X11 bug when the ROMAlyzer was opened initially). Don't ask for support if you know that this is the cause of your troubles! Please contact the style's developer(s) instead.

Qt style sheets

Qt style sheets can be used in conjunction with any GUI style to gain more theme'ing power.

Since v0.2.b10, QMC2 supports dynamic loading of style sheets from within the GUI. It loads the style sheet before the GUI style is set up, so the GUI style may overload parts of the theme with its settings. This means that not every combination might look as expected, others may fit better.

Compatible style sheets can be found here: http://qmc2.arcadehits.net/wordpress/style-sheets/.

To install a style sheet, simply unpack the archive somewhere in your file system. Then select the style sheet (.qss file) from within QMC2 to activate it. See Tools -> Options -> GUI -> Style sheet.

Note that due to a pending Qt bug we have to change the current working directory of the running application to the style sheet's path to make sure that relative URLs (in the .qss file) are handled correctly. If you don't like that, use the -stylesheet command line parameter instead! Update: since version 0.2.b16 we support the specification of the working directory that's used when the emulator is launched in play- or demo-mode; we strongly recommend to set this option as it cleanly works around this issue.

Read more about Qt style sheets here: http://qt-project.org/doc/4.8/stylesheet.html

### 6. Short cuts, GUI control keys and joystick support

Several functions (or actions in Qt technical jargon :) can be accessed via short cut key-sequences. The following table lists all of them:

Default short cut | Function
Ctrl+P | Play the currently selected game/machine (start emulation)
Ctrl+Shift+P | Linux/Unix and Windows only: Play the currently selected game/machine (start emulation) in embedded mode
Ctrl+R | Reload the entire game/machine list
Ctrl+J | Copy the currently selected game/machine to the list of favorites
Ctrl+X | Stop any active processing, otherwise exit QMC2
Ctrl+O | Linux/Unix and Windows only: Open the options/preferences dialog
Ctrl+I | Housekeeping: clear image cache
Ctrl+M | Housekeeping: clear MAWS / ProjectMESS cache (in-memory and/or on-disk)
Ctrl+N | Housekeeping: clear icon cache
Ctrl+T | Housekeeping: recreate template configuration map (needed if the XML options template changes at run-time)
Ctrl+, | Mac OS X only: Open the options/preferences dialog
Ctrl+Shift+C | Housekeeping: check the loaded template configuration map against the currently selected emulator's configuration options and their defaults
Ctrl+H | QMC2 documentation browser
Ctrl+B | About QMC2: version, license, system info etc.
Ctrl+Q | About Qt: version, license etc.
Ctrl+S | Check current game's/machine's ROM state individually and update its state in the ROM state cache
Ctrl+D | Analyse (deep-scan) current ROM with the ROMAlyzer
Ctrl+Z | Open ROMAlyzer to deeply analyse the ROMs of one or more games/machines
Ctrl+E | Export current ROM status to file
Ctrl+1 | Check ROM states for all games/machines and recreate the ROM state cache from scratch
Ctrl+2 | MAME/UME targets only: Check sample sets for games that need samples
Ctrl+3 | Check images and icons files for existence / accessability / usability and obsoleteness
Ctrl+Alt+C | Toggle ROM state filtering for status Correct
Ctrl+Alt+M | Toggle ROM state filtering for status Mostly correct
Ctrl+Alt+I | Toggle ROM state filtering for status Incorrect
Ctrl+Alt+N | Toggle ROM state filtering for status Not found
Ctrl+Alt+U | Toggle ROM state filtering for status Unknown
Ctrl+Alt+1 | Launch QMC2 for (SDL)MAME
Ctrl+Alt+2 | Launch QMC2 for (SDL)MESS
Ctrl+Alt+3 | Launch QMC2 for (SDL)UME
Ctrl+Shift+A (WIP) | Setup arcade mode
F5 | View game/machine list with full detail
F6 | View parent/clone hierarchy
F7 | View games by category (only available when the use of catver.ini / category.ini has been enabled)
F8 | MAME/UME targets only: view games by version they were added to the emulator (only available when the use of catver.ini has been enabled)
F9 | Run external (and generic) ROM tool on the currently selected game/machine
F11 | Toggle between full screen and windowed mode
F12 | Launch QMC2 Arcade
Ctrl+Shift+T | Tag current set
Ctrl+Shift+U | Untag current set
Ctrl+Shift+G | Toggle tag mark of current set
Shift+Down | Toggle tag mark of current set and move the cursor one item down
Shift+Up | Toggle tag mark of current set and move the cursor one item up
Ctrl+Shift+L | Tag all sets
Ctrl+Shift+N | Untag all sets
Ctrl+Shift+I | Invert all tags
Ctrl+Shift+S | Check the ROM states of all tagged sets
Ctrl+Shift+D | Analyze (run ROMAlyzer on) all tagged sets
Ctrl+Shift+J | Add all tagged sets to the favorites list
Ctrl+Shift+X | Tag all visible sets (according to the current ROM state filter)
Ctrl+Shift+Y | Untag all visible sets (according to the current ROM state filter)
Ctrl+Shift+Z | Invert all tags of visible sets (according to the current ROM state filter)
Ctrl+Shift+F9 | Run the ROM tool on all tagged sets
When Phonon features are enabled, the following short cuts will also be available:
Ctrl+Alt+P | Audio player: play/resume current track
Ctrl+Alt+# | Audio player: pause current track
Ctrl+Alt+S | Audio player: stop current track
Ctrl+Alt+Left | Audio player: jump to start of previous track
Ctrl+Alt+Right | Audio player: jump to start of next track
Ctrl+Alt+F | Audio player: fast forward within current track (jump to next track if end is reached)
Ctrl+Alt+B | Audio player: fast backward within current track (jump to previous track if start is reached)
Ctrl+Alt+PgUp | Audio player: raise volume
Ctrl+Alt+PgDown | Audio player: lower volume
Ctrl+Y | Clear YouTube (on-disk) image cache

Note: WIP means work in progress -- that is, those short cuts will only be available for QMC2 builds configured with 'WIP=1'. Short cuts marked as reserved (if any) aren't really available yet, but planned to be used in a later version.

Remapping short cuts and GUI control keys

Since v0.1.b11, QMC2 also supports remapping of all these short cuts and some special keys (cursor keys, tab, +/-, ...) needed for GUI control by key-strokes. It should be very handy for users of MAME cabinets with sticks that map their controls to key-strokes (X-Arcade controls for example). We hope it's useful for others as well :).

Joystick control

For users of (regular) analog or digital joysticks, there is direct support for joystick GUI control through SDL (Simple Directmedia Layer) since v0.2.b3. Simply enable joystick support on the respective configuration page, map any of the above functions or GUI control keys to joystick functions and you can start using a stick to control QMC2 right away.

Internally, joystick functions are mapped to active keyboard short cuts and/or GUI control keys. The corresponding key presses are emulated in software as soon as a mapped joystick function is recognized. This means that using a joystick to control the GUI will cause some additional events, but it doesn't hurt.

Key events for joystick mappings will always be sent to the widget which currently has focus, but only if the widget is one of QMC2. All other cases will be ignored, which means that it does not influence the emulator (or vice versa), although QMC2 still recognizes the joystick movements, button presses etc... it will just not react on them while the emulator (or any other application) has focus.

However, there are two exceptions to this rule:

- For embedded emulators, mixing / sharing the joystick control between QMC2 and an emulator is not supported (well, not recommended)
- When QMC2 is in joystick test- or calibration-mode, it will not only receive all joystick events, but also react on them with widget updates. This is not really a problem and could be used for debugging purposes, but should normally be avoided because it eats some CPU cycles for no real use.

### 7. External tools and tool argument syntax

External tools like zip (on all platforms), rm (on UNIX and Mac OS X) or del (on Windows) are used for specific operations which weren't natively built into QMC2.

For example, to remove obsolete image files from ZIP archives, QMC2 uses an external zip-tool and passes the files to be removed on the argument list when the zip-tool is started. We recommend to use Info-ZIP's zip 2.32+/3.0+ which is what we've tested. But it could be any zip program that supports the deletion of multiple entries from ZIP archives at once.

Similarly, a second tool is needed for the deletion of files within file systems (when images are stored directory based, that is). We recommend the common rm command on UNIX and Mac OS X, and the simple shell command del on Windows. This tool also needs to support the deletion of multiple files in one step.

Finally, there's a third generic tool -- the so called ROM tool -- that can be used to call a program or script which does any external processing based on the game's/machine's ID and/or its long name (description). It is completely up to you what this tool might do... ideally, it should have some ROM management functionality, though :).

Tools can have a single function or they can have multiple functions. For each function, an argument list has to be specified which defines the correct syntax for the command. Macros (like $MACRONAME$) can be used as placeholders and will be filled with real data before execution.

The following macros exist:

Macro | Will be replaced with... | Valid tools
$ARCHIVE$ | ... the currently processed ZIP archive's filename (fully qualified) | Zip tool
$FILELIST$ | ... the currently processed list of files ("file1 file2 ..." - fully qualified) | Zip tool
$ID$ | ... the ID of the currently selected game/machine | ROM tool
$DESCRIPTION$ | ... the long name (or description) of the currently selected game/machine | ROM tool

Everything else will be passed as literal text at the position where it's specified (see Front end -> Proxy / Tools in the setup dialog).

When external tools are started by QMC2, a simple tool-executor dialog will pop up to display the command and its output.

### 8. Multi-platform support

As the front end code has been designed with portability in mind, QMC2 should work on any UNIX or UNIX-like platform, on Mac OS X and meanwhile also on Windows, provided Qt 4 and (SDL)MAME/MESS (or whatever emulator may be used) are supported on this platform as well.

However, you may have to create or adopt the corresponding OS-specific configuration file, which is arch/`uname`.cfg. If it does not exist nor fit your local situation, the build will most likely fail:

    $ make ARCH=test
    ls: arch/test.cfg: No such file or directory
    Qmake version: 1.07a (Qt 3.3.7)
    Qmake is free software from Trolltech AS.
    Error: Wrong QMake version. QMake version 2 (Qt 4) required!

Note that by using the ARCH-variable on the make command line, you could easily specify a local configuration, even if a system configuration file already exists for your platform. Take the one that comes nearest to your system configuration and change it to your needs.

Since v0.1.b10, there's an alternative method which will help to solve distribution-specific build problems. Let's say you wanted to use the Qt 4 packages provided by your distribution and you know that the version is sufficient. So, instead of just considering Linux as the OS name (or architecture), also consider the local differences of this type of setup:

    $ make DISTCFG=1

If make is called this way, the QMC2 build process will try to figure out what the exact name and release of your OS / distribution is. It will load the OS-specific configuration just as before (i.e. arch/Linux.cfg), but it will overwrite the OS configuration settings with the distribution-specific configuration settings (i.e. arch/Linux/openSUSE_10.3.cfg in case of an openSUSE 10.3 installation). This means that only differences to the global OS configuration need to be placed in this file.

Of course, this mechanism requires that a specific configuration file for your OS / distribution exists. If not, the build will fail. Create the required file (see output from make or run make os-detect to figure out the expected name of the configuration file) and try again!

In case of any trouble, feel free to contact us (see section 9.). Please attach the output of make os-detect in this case!

Also, please send us your configuration file if you try QMC2 on other platforms / distributions than the ones included in the arch/ or arch/<os-name>/ directories. Regardless if you are successful or not, any help is greatly appreciated (see section 10.).

Since v0.2.b7, QMC2 is also supported on Mac OS X -- thanks to Vas Crabb who ported it in the first place and maintains the port now.

Since v0.2.b8, QMC2 is also supported on Windows using the original MAME/MESS variants.

### 9. Contact

Project homepage:

- http://qmc2.arcadehits.net/wordpress

Development site:

- http://sourceforge.net/projects/qmc2

QMC2 development mailing list:

- qmc2-devel@lists.sourceforge.net (subscribers only)
- https://lists.sourceforge.net/lists/listinfo/qmc2-devel

Bug tracking system:

- http://tracker.batcom-it.net/view_all_bug_page.php

Individual team members:

- http://wiki.batcom-it.net/index.php?title=Development_team_and_contributors

### 10. Contributing

Help and contributions are greatly appreciated. Following are the most important areas where we need your support:

- Beta testing, bug hunting
- Documentation
- Translations (application and documentation)
- Graphics & GUI design
- Useful feedback and ideas

If you think you can help us in one or more of these areas, please contact us!

We are using SourceForge.net as our open-source development platform. If you intend to become a QMC2 developer, note that you're required to use SVN (Subversion).

See credits.html for a list of contributers.

### 11. License and copyright

QMC2 - M.A.M.E./M.E.S.S./U.M.E. Catalog / Launcher II
Copyright © 2006 - 2013 R. Reucher, Germany. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the license, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

See copying.html for the GNU General Public License.

Third party software used in this project:

zlib 1.2.7
Copyright © 1995 - 2012 Jean-loup Gailly and Mark Adler. All rights reserved.
http://zlib.net/

Minizip 1.01h
Copyright © 1998 - 2009 Gilles Vollant. All rights reserved.
http://www.winimage.com/zLibDll/minizip.html
info@winimage.com

runonce --- GUI program-launching wrapper
Copyright © 2001 Jamie Zawinski. All rights reserved.
jwz@jwz.org

The Ghostbusters Logo
Copyright © 1984 Columbia Pictures Industries, Inc. All rights reserved.

HTML editor from Qt Labs / graphics-dojo
Copyright © 2011 The Qt Project. All rights reserved.
http://qt.gitorious.org/qt-labs/graphics-dojo

PDF.js -- JavaScript / HTML5 PDF rendering library
Copyright (C) 2012 Mozilla Foundation http://wiki.mozilla.org/PDF.js

### 12. Legal notice

Please note that you are required to have permission to use or to be the legal owner of any ROM images you are going to run through an emulator and / or this front end. The goal of emulators and its surrounding projects is educational and academic (of course, it's also fun :).

We do NOT and will NEVER encourage or support any type of illegal use!

However, a hand full of ROM images has been released to the public for non-commercial use. For instance, free MAME compatible ROMs are available at http://mamedev.org/roms.