Author: Lionel Jeanson
Description: Throttle documentation for JMRI project
Keywords: JMRI decoderpro dcc nmra throttle throttlepro

# Throttles Preferences

The Throttles Preferences pane is accessible from :

- the JMRI preferences window
- the throttle window preferences menu entry
- the throttle and throttles list windows toolbars

It is composed of two tabs :

- The General tab contains the JMRI throttles user interface preferences.
- The Keyboard controls tab allows to review and set the various keyboard shortcuts used by the JMRI throttles user interface. It is also there that the multiplier for mouse wheel + ctrl for speed is set.

When openned as a single preferences window (not JMRI global preferences), 3 buttons are availble at the bottom :

- Cancel button will close the window and leave current Throttles settings as they are.
- Apply button will apply the current set of preferences and the preferences window will stay open.
- Save button will apply, save current Preferences, and close the Preferences Windows, settings will be automatically loaded at next start of JMRI.

## General Panel

For best user experience, the recommended settings are those illustrated above.

### Use extended throttle

This setting will enable/disable all extended throttles features.

### Save throttles when saving throttle windows layout

When saving a throttle layout, all opened throttles layouts are also saved to their respective files.
Warning this does not export to roster file the function name customization if any (see Export current throttle customization to roster menu entry)

### Use Roster image as background

When a roster is selected, the image defined in its Media Panel will be loaded as a background for the throttle window.
When this option is enabled and the selected address is 0 or 3, a default image will be loaded.

### Do not scale image

When a background image is loaded for current throttle, if enabled, will not scale it before display.

### Search Roster info when address entered

When an address is entered in the Address Panel, the JMRI Roster database will be searched for a matching roster entry (and will hence triggers options described above and bellow if they're enabled).

### Automatic loading Throttle pane preferences when linked to Roster

When a Roster is selected, if a matching Throttle definition file exist, JMRI will automatically loads it.
These files are stored in <JMRI Preference Folder>/Throttle/XYZ.xml where XYZ in the Roster ID.
Using the Save menu entry from the File menu in a Throttle Window will create or update these files.

### Ignore Throttle frame position

For old Throttle files that contain Throttle Window position in them, do as described.
Note: Throttle Windows position are now saved in the Throttles Layout backup files (not in the Throttles backup files anymore)

### Hide undefined Roster function buttons

When a Roster is selected, the address panels buttons are initialized as defined in the Functions Labels panel in DecoderPro Label&Media screen. If this option is enabled, buttons not defined (no text) in PanelPro will be automatically hidden in the Function Panel.
Note: you can reset Function Buttons visibility in a Throttle Window by going to View Menu and clicking "Show all function buttons".

### Enable Throttle toolbar

This option enables a Toolbar that will show in all Throttle Windows.

### Enable button icons when available

When a Roster is selected, the address panels buttons are initialized as defined in the Functions Labels panel in DecoderPro Label&Media screen. If this option is enabled, button icons, if defined, are loaded and displayed instead of function text. Function text still needs to be defined (see Hide undefined Roster function buttons above)
This option will also enable icons instead of text on the directions, idle and stop buttons on the control panel of JMRI throttle windows.

### Use large speed slider and control buttons

If enabled, the speed slider will be drawn much larger and bolder. Will also automaticaly resize the control panel buttons as large as possible.
Makes everything more readable when standing far away from screen.

### Steal / Share Options

These are system dependent options, and are not be available for all hardware types. Some systems perform automatic steal or sharing, so no option is required.

The Silent Steal and Silent Share options are independent of the Use Extended Throttle setting.
If both Silent Steal and Silent Share are available, only 1 can be selected at a time.

Automation scripts and the actual hardware may override these options at any point. Although these options are to serve as a guide, they are fully honoured in the main JMRI Throttle window.

WiThrottle connections are only able to support Steal questions, so steal or share questions are processed as steal-only.

See individual hardware documentation for more detail on how these options affect your system, eg. CBUS® Throttles( CBUS® is a registered trade mark of Dr Michael Bolton)

### Default throttle file :

This file selector allows to define a JMRI Throttle file (xml file created from save as menu in a throttle window) as a default to be loaded each time a new throttle is obtained by a JMRI Throttle Window (unless a roster entry is available for that address).
It allows to define a nicely crafted JMRI Throttle window for any address to be used, particularly, default function names, icons and lockable states.