                            How to customize Mocca?
                        ===============================


1. Adding a new scheme
-------------------------
A scheme is a definition of an emulator and a set of files to feed the
emulator. Additionally, a scheme should have a background image and menu image
to show up in Mocca.

Schemes are stored in <moccadir>/moccaschemes, each scheme in a separate
directory. The directory specifies the name of the scheme, but this can be
overridden. However, make sure that no two schemes share the same name!

A scheme directory must contain the following files:

    background.png         320x240 background for the scheme file list
    menuicon.png           48x48 icon for the menu
    scheme.txt             scheme specification file
    colors.txt             optionally, colors definition specific to the scheme

Both .txt files are a list of (setting, value) mappings, each on a single line
and the setting name separated from the value name by at least one space. The
difference is what they contain: scheme.txt contains string settings, while
colors.txt contain color definitions.



1.1 scheme.txt
-----------------

scheme.txt can contain the following values:

    extension             Specifies the extension of files that will be
                          recognized by the scheme. (recommended)
    application           Specifies the name of the emulator that will be used
                          to run the files (required)
    arguments             If the application requires its command-line arguments
                          in a special form (rather than just a file name as
                          the first argument), specify all arguments here. Use
                          %s to represent the location of the filename.
                          (optional)

If extension is empty or not defined, all files will be shown (not
recommended). If application is empty or equal to "*", no emulator will be run;
instead, the file will be run by itself (it should be an executable, therefore,
otherwise the GP2X will crash attempting to run it).


Example scheme.txt:

    extension   .nes
    application nknes2x.gpe



1.2 colors.txt
------------------

A color is defined by 6 or 8 hexadecimal characters in the following format:
rrggbbaa. aa denotes the alpha channel, and determines if the color is partly
translucent. Alpha channels are not available for font colors -- only for box
and line colors. Note that on non-font colors, alpha channels are always
required (otherwise you will end up with an invisible color). If you want the
color to be plainly visible, use "FF" for the alpha channel.

Each scheme inherits all colors from the main scheme colors, so if you do not
wish to change those, you do not need to define the file (or you can leave
it empty). However, you can override the main scheme colors to suit the rest
of your scheme if you desire.

See section 3 for a list of available colors.


Example colors.txt:

    filelist_text     000000
    filelist_focus    ff0000
    box_color         ffeeccff




2. Customizing and skinning
------------------------------

Skinning the menu is a lot like adding a scheme: just replace the default image
files of a scheme (or the main scheme) with your own versions, and optionally,
change the colors.

See section 1.2 for an explanation of what a colors.txt file should look like,
or section 3 for a list of colors you can change.




3. List of available colors
------------------------------

Here is the list of all colors that are used (and can be changed). Colors that
define a font color are marked with (F), and will not use the alpha channel.

# Main menu colors
box_color
box_border
selection_color
selection_border
text_color                   (F)
version_color                (F)

# Pop-up menu colors
popupmenu_background
popupmenu_border
popupmenu_item_background
popupmenu_item_border
popupmenu_focus_background
popupmenu_focus_border
popupmenu_text               (F)

# Pop-up message colors
popup_background
popup_border
popup_text                   (F)

# File list colors
filelist_text                (F)
filelist_focus               (F)
