`helpsystem` — the help bar

The 32 button icons, one by one.

The bar at the bottom of the screen that reminds you what the buttons do. 38 properties: six for formatting, and 32 icons.

Recalbox itself decides what the bar announces, screen by screen, and translates each label. Your theme only sets the form: the placement, the font, the colors, and the image of each pictogram.

<helpsystem name="help">
  <pos>0.02 0.955</pos>
  <fontPath>${root}/data/fonts/Exo2.otf</fontPath>
  <fontSize>0.025</fontSize>
  <textColor>C6CBD8</textColor>
  <iconColor>FFFFFF</iconColor>
  <iconA>${root}/data/arts/boutons/a.svg</iconA>
  <iconB>${root}/data/arts/boutons/b.svg</iconB>
</helpsystem>

Formatting

Property	Role
`pos` `size`	placement
`textColor`	the labels' color
`iconColor`	the icons' tint — provide them in white
`fontPath` `fontSize`	the font

The 32 icons

Replacing an icon is optional: Recalbox provides its own. You only redefine the ones you want.

Directions — iconUpDown, iconLeftRight, iconUpDownLeftRight

Buttons — iconA, iconB, iconX, iconY

Triggers — iconL, iconR, iconL2, iconR2, iconL3, iconR3, iconLR, iconL2R2, iconL3R3

System — iconStart, iconSelect, iconHotkey

Hotkey combinations — iconHkA, iconHkB, iconHkX, iconHkY, iconHkL, iconHkR, iconHkLeftRight

Joysticks — iconJ1UpDown, iconJ1LeftRight, iconJ1UpDownLeftRight, iconJ2UpDown, iconJ2LeftRight, iconJ2UpDownLeftRight

A combination is two pictograms

When the help is about a combination, Recalbox draws iconHotkey, then the key.

[HK] [A]  Launch the game

iconHkA is therefore the image of the A button used in a combination — not a drawing of “HK + A”. Provide a plain button there: the shortcut is already in front.

iconHotkey counts double: it appears in front of every combination in the bar. It is the icon to polish first if your theme shows any.

The name is imposed: `help`

Recalbox looks for the component named help, and it alone. <helpsystem name="barre"> will exist in your file without ever driving anything.

The bar is set view by view

Recalbox re-reads the view's <helpsystem> at every screen change, and starts over from its own icons. What a view does not declare therefore falls back to Recalbox's default — never to what another view had set.

Two ways to do it:

the same set everywhere — declare the bar in a view that covers everything: <view name="system, detailed, menu">;
a different bar per screen — a <helpsystem> in each view, with its own images.

Provide white icons and use iconColor: a single set of files is then enough for all your theme's color variants.

Offering several icon sets

That is what the big themes do: a SNES set, an Xbox set, a PlayStation set… and the user picks in Menu → Interface → Theme.

Each set is a file containing only the <helpsystem> and its images:

<!-- ./options/icones-snes.xml -->
<theme>
  <view name="system, detailed, menu">
    <helpsystem name="help">
      <iconA>${root}/data/icones/snes/a.svg</iconA>
      <iconB>${root}/data/icones/snes/b.svg</iconB>
    </helpsystem>
  </view>
</theme>

And you offer them like this, without declaring anything else:

<include subset="iconset" name="1 - SNES">${root}/options/icones-snes.xml</include>
<include subset="iconset" name="2 - Xbox">${root}/options/icones-xbox.xml</include>

iconset is a reserved name: Recalbox displays “SELECT THEME'S ICONSET”, translated into the machine's language. No <subset> tag is needed to name it.

helpsystem — the help bar