ZXDS custom menu and custom keyboard documentation
==================================================

ZXDS allows you to set up a custom menu bar containing 9 action icons
you wish to use most frequently. It also allows setting up a fully
customizable keyboard consisting of 60 arbitrary keys and/or actions.
This document explains how to do that and you can also find some ready
examples in the custom/menus/ and custom/keyboards/ directories.

Custom menu
-----------

To modify the default, locate the /ZXDS/ZXDS.cfg which gets created after you run
ZXDS for the first time, and find the lines which look like this:

menu[1] = LOAD_FILE
menu[2] = LOAD_SLOT
menu[3] = CONTROLS
menu[4] = QUICK_LOAD
menu[5] = QUICK_SAVE
menu[6] = TOGGLE_SPEED
menu[7] = PAUSE
menu[8] = KEYBOARD
menu[9] = HELP

Now simply replace the individual action names with the desired ones.
For reference, the list of all usable actions names is at the end of this
document - but most often it is just the same thing what the corresponding
icon in one of the menu bars or on the shortcut controls screen says.

Save the modified config, and the next time you start ZXDS, the custom menu
should display the icons you have configured. Alternatively, you can put the
modified lines to a separate .cfg file, and load it from a load requester.
This allows switching between multiple custom menu bars, each tuned for
particular purpose. See the custom/menus/ directory for few such examples.

Custom keyboard
---------------

The custom keyboard extends the custom menu bar idea even further. It is
most suitable for mapping complex game and/or application keyboard controls
to a set of reasonably labeled custom keyboard buttons, but has many other
uses beyond that.

There are 60 buttons available, 6 rows of 10 buttons each. Every button can
be assigned to either perform one of the builtin actions available, or to simulate
a key press (or two). The latter buttons can be even given descriptive names and color.

To assign an action to a button, use this:

custom[<index>] = <action>

To assign a key to a button, use either of these:

custom[<index>] = <key>
custom[<index>] = <key>, <color>
custom[<index>] = <key>, <color>, <label>

The <index> is the index of the button to assign, from 0 to 59. Note that having 10
buttons per row makes the two digits match the button row and columns directly.
Also note that assigning to button 0 automatically resets all other button definitions,
so make sure your keyboard definition always does that as the first thing.

The <action> is one of the action names listed at the end of this document.

The <key> is the name of the key to press: A to Z, 0 to 9, Caps, Shift,
Space or Enter. The Kempston joystick buttons (Up, Down, Left, Right, Fire)
and Kempston mouse buttons (LMB, MMB, RMB) are supported, too. You can in
fact combine any two of these using the + sign - for example, use Caps+Space
to simulate the Break key.

The <color> is either Grey, or one of the eight spectrum colors: Black,
Blue, Red, Magenta, Green, Cyan, Yellow, White. When not specified, it
defaults to Grey (as Black is just too much, well, black).

The <label> is the text to label the button with. It can span multiple lines,
each line having 6 characters. The text breaks at spaces if possible, however
you can insert multiple spaces to force line break at particular point, as in
"Here  I go". When no label is specified, the name of the key (or keys) is used instead.

Although you may put these definitions into ZXDS.cfg, and have the custom
keyboard defined every time you run ZXDS, it is better if you put them into
a standalone .cfg file, and load it from the load requester only when needed.
If you name the .cfg using the same base name as the corresponding tape or
snapshot file you will be loading, ZXDS will even load it automatically for you.
If you wish, you can find some ready examples in the custom/keyboards/ directory.

In either case, if you have done everything correctly, the custom keyboard
will be available as an additional keyboard and can be switched to by using
the "Keyboard" icon few times.

To get rid of the custom keyboard, you can load the empty keyboard from
custom/keyboards/none.cfg. It contains the only assignment

custom = none

which resets all the custom keyboard definitions.

Available actions
-----------------

This is the list of all actions which can be used in custom menu and custom keyboard:

NONE                    # no action
LAST_DISPLAY            # switch to each previously used menu screen in turn
LOAD_FILE               # show load file requester
SAVE_FILE               # show save file requester
SAVE_SCREEN             # save a raw screenshot
SAVE_BITMAP             # save bitmap screenshot
LOAD_SLOT               # show load slots screen
SAVE_SLOT               # show save slots screen
QUICK_SAVE              # quick save to the last saved slot
QUICK_LOAD              # quick load from the last used slot
CONTROLS                # show the controls screen
KEYS1                   # load keys from the corresponding button config - QAOPM
KEYS2                   # load keys from the corresponding button config - kempston
KEYS3                   # load keys from the corresponding button config - cursor
KEYS4                   # load keys from the corresponding button config - sinclair I
KEYS5                   # load keys from the corresponding button config - sinclair II
KEYS6                   # load keys from the corresponding button config - custom keys 1
KEYS7                   # load keys from the corresponding button config - custom keys 2
KEYS8                   # load keys from the corresponding button config - custom keys 3
KEYS9                   # load keys from the corresponding button config - custom keys 4
SAVE_CONFIG             # save default config
LOAD_CONFIG             # load default config
FAST_SPEED              # switch to fast emulation speed
NORMAL_SPEED            # switch to normal emulation speed
MORE_SPEED              # increase emulation speed
LESS_SPEED              # decrease emulation speed
TOGGLE_SPEED            # toggle between current and normal speed
ZX48                    # switch to ZX Spectrum 48K
ZX128                   # switch to ZX Spectrum 128K+
PENTAGON                # switch to Pentagon 128
CYCLE_VOLUME            # cycle AY channel volume levels
QUIET_VOLUME            # switch to quiet AY channel volume level
NORMAL_VOLUME           # switch to normal AY channel volume level
LOUD_VOLUME             # switch to loud AY channel volume level
STEREO_MODE             # cycle AY stereo modes
STEREO_NONE             # switch AY to mono
STEREO_ABC              # switch AY to ABC stereo
STEREO_ACB              # switch AY to ACB stereo
STEREO_WIDTH            # toggle AY stereo separation modes
STEREO_NORMAL           # switch AY to normal stereo separation
STEREO_WIDE             # switch AY to wide stereo separation
CYCLE_COLORS            # cycle available palette modes
COLOR                   # switch to color palette
GREY                    # switch to grey palette
BLACK_INK               # switch to special black and white palette
WHITE_INK               # switch to special black and white palette
QUIT                    # quit the emulator
SHUTDOWN                # shutdown the emulator
RESET                   # reset the emulated machine
USR0                    # reset the emulated machine in USR 0 mode
NMI                     # generate NMI
PAUSE                   # pause the emulation
FRAME_STEP              # pause the emulation after emulating single frame
TAPE                    # show tape browser
PLAY_TAPE               # start tape playback
STOP_TAPE               # stop tape playback or recording
PAUSE_TAPE              # start/stop tape playback
RECORD_TAPE             # start tape recording
RESTART_TAPE            # rewind tape to the first block
REWIND_TAPE             # rewind tape to the previous block
FORWARD_TAPE            # fast forward tape to the next block
EJECT_TAPE              # eject tape
LOAD_SPEED              # toggle between normal and fast loading speed
DISK                    # show disk browser
KEYBOARD                # show the keyboard
LOG                     # show the system log
STATS                   # show the system statistics
MOST_USED               # show the most used files
LAST_USED               # show the last used files
VIEW_FILE               # show the file viewer
POKES                   # show the poke cheats
MEMORY                  # show the memory dump
DATA_DUMP               # show the memory data dump
TEXT_DUMP               # show the memory text dump
CODE_DUMP               # show the memory code dump
HOST                    # host the multiplayer session
JOIN                    # join the multiplayer session
BYE                     # leave the multiplayer session
STOP_RZX                # stop the RZX playback
UNDO                    # restore the memory state you have just reset or overwritten
HELP                    # toggle help on and off


And that's all. Now go and create some awesome custom keyboards for your most favorite games!
