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

## Setting Roster Media

The Roster Media pane is accessible when using DecoderPro from the contextual menu on a roster entry, from the "Labels & Media" button at the bottom right of the DecoderPro main window and from the "Labels and media" entry in the Actions menu.

### Image entry

Dropping an image file in the inner frame will update this entry (it has to be an image file, hence after searching on the web for an image you like, save it on the dektop, and then drop the file in the entry, dropping image content directly from browser window may work for some browsers (the image will be downloaded and a local copy stored)).

The contextual menu (right click) on an image allows to remove the Image entry in current roster entry.

Roster images are stored in JMRI Preferences folder. When the image is updated or removed from the roster, the image file is not removed from its storage in JMRI Preferences folder.

The Icon entry is used as an icon for that roster entry.

The Image entry is used as a background for JMRI Throttles when that option is enabled.

### Icon entry

Dropping an image file in the inner frame will update this entry (it has to be an image file, hence after searching on the web for an image you like, save it on the dektop, and then drop the file in the entry, dropping image content directly from browser window may work for some browsers (the image will be downloaded and a local copy stored)).

The contextual menu (right click) on an image allows to remove the Image entry in current roster entry.

Roster icons are stored in JMRI Preferences folder. When the image is updated or removed from the roster, the image file is not removed from its storage in JMRI Preferences folder.

The Icon entry is used in various Roster Combo Boxes in JMRI, and in the Throttles List Window.

It is recommended to use GIF or PNG images with a transparent background and to have the images turned so that the locomotive head will be to the right. That will allow for easier transformations of the image in later applications.

Note: an easy way to find icons is to search for "train GIF" or look at resources linked to the Traffic Screensaver in your favorite Internet search engine.

### Web reference

This entry is dedicated towards storing an URL, on the above screenshot it points to the Wikipedia entry for that roster prototype.

### Custom attributes

This is a list of key value pairs allowing to set some custom setting per roster entry.

It is possible to manualy add custom values here, don't forget to validate the entry (click somewhere else) before saving to roster.

Some known special settings :

- speedLabels : a json formated array of labels to be displayed on the JMRI throttle speed sliders, for instance the entry could be :
  [ { "value" : 40, "label" : "SS" } , { "value" : 80, "label": "NS"} , { "value" : 100, "label": "FS"} ]
  where "value" is a number of speed increment and "label" a text string.
  Note that label support HTML text formating, for instance : "<html><font color=red>SS</font></html>" would display the SS label red or "<html><font size=25 color=green>FS</font></html>" FS with color green and size 25
- ... many more custom settings from various JMRI tools

## Roster Function Labels

It is also recommended to fill in the Function Labels entries in the Function Labels pane in DecoderPro. These entries will be used by the Function Panel in Throttle Windows, and also by the throttle apps to display label text instead of the function numbers, or even on/off icons.

- fn is the function number
- label is the text for that function entry
- visible is that function button visible on throttle UI (only applies when a label exists, else see the "Hide undefined Roster function buttons" on the global throttle preferences screen)
- latch checked means this is a latchable (lockable) function, unchecked means momentary (toggle switch vs momentary switch)
- off is the function off icon
- on is the function on icon
- shunt enabled will switch the JMRI native throttle slider to continuous mode (from -100 to +100 instead of from 0 to 100) when that function is enabled, to be set on the "Slow" function for shunting

Image are edited the same way than in the above window, note that the contextual menu on each image entry allows to remove curent image but also to open a file browser directly in the JMRI icon ressources for function icons, SVG files are supported here and in native JMRI throttle window (allows for nice resizing) but may not be supported in web throttles.

Functions images are stored in JMRI Preferences folder. When a new image is dropped if a file exist with the same name and same content, the existing file is used. When the image is updated or removed from the roster entry, the image file is not removed from its storage in JMRI Preferences folder.

There is an option for JMRI Throttles that will show Throttle Function buttons only when an entry is defined here. Using the "Export current throttle customization to roster entry" in Throttle Windows menu will update these entries from the Function Panel if required. See the Functions Panel documentation in the Basic Throttle Window description.