Keymap

From Official Kodi Wiki
Revision as of 17:58, 18 June 2013 by >Quids (→‎Keynames)
Jump to navigation Jump to search

Template:Keyboard navigation

Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


Keyboard.xml is a XML base keymap file that define the mappings of keys (keyboard keys, mouse/remote/joysticks buttons and more) to XBMC actions. Keyboard.xml was first introduced in XBMC 10 ("Dharma"), in versions prior to that it was called Keymap.xml.

Location of keymaps

Keymap configuration files are stored in the "keymaps" folder in the userdata folder:


The keymap configuration files that ship with XBMC are stored in the "/system/keymaps/" folder within the XBMC root directory.

All *.xml files in these folders are applied as keymaps. All *.xml files are processed in alphabetical order. Keymaps defined in an .xml file add to or override mappings in previous .xml file. Keymaps defined in user folders add to or override mappings in the global keymap.

By default there will be no files in these locations, so grab one from the link below to make a new one/over-ride:

Default keymaps shipped with XBMC

101 on keymaps

For a full guide, see: HOW-TO:Modify keyboard.xml

Now, you don't actually need to copy the default keymap, because XBMC is smart enough to only load changes, so you can just add one or two keys and it will apply it to the existing keymap. It's nice to use a full copy because it makes it easier to see what is and isn't in use, and when you see the full mapping you get a feel for what the different options do, etc.

Structure

There is one global keymap and several window-specific keymaps.
XBMC falls back to the global map when the window-specific map hasn't bound the key being pressed.

The format of keymapping files is as follows:

<keymap>
  <global>
    <gamepad>
      <A>Select</A>
      [...]
    </gamepad>

    <remote>
      <select>Select</select>
      [...]
    </remote>

    <keyboard>
      <enter>Select</enter>
      [...]
    </keyboard>

    <universalremote>
      <obc25>XBMC.ActivateWindow(MyMusic)</obc25>
      [...]
    </universalremote>

    <joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
      <button id="15">Select</button>
      [...]
    </joystick>
  </global>

  <Home>
    [...]
  </Home>

  [...]

</keymap>

As you can see, it's divided into a <global> section, and a number of window sections (such as <Home>).
A list of the available window names can be seen here. The WINDOW can also be a custom window formatted as <windowId#> (e. g. <window1113>).
Each of these sections can contain Gamepad, Remote, Keyboard, Universal Remote, and custom Joystick sections.

The format for mapping a particular key under one of these device types is as follows:

  <keyname>action</keyname>

Keynames

Gamepad Section

An up to date list of the available actions can be found in the source code of XBMC in ButtonTranslator.cpp where the TranslateGamepadString() function does the work.

Example:

<gamepad>
  <A>Select</A>
</gamepad>

Remote Section

An up to date list of the available actions can be found in the source code of XBMC in ButtonTranslator.cpp where the TranslateRemoteString() function does the work.

Example:

<remote> 
  <play>Play</play>
</remote>

Universal Remote Section

To map Universal Remote buttons using the RCA infrared protocol, you may add <universalremote> sections to keymap.xml.
In this case, the tags used are <obc#> where # is the original button code (OBC) of the button.
You would put it inside a <universalremote> section in the <window> or <global> sections.

Example:

<universalremote> 
  <obc148>Stop</obc148>
</universalremote>
Will map Stop Playback to the RCA DVD repeat button <obc148>, which is not used by XBMC by default.
  • Note: ensure that the <universalremote> section is NOT added 'within' the <remote> section - it can appear before or after. Otherwise it will not be recognised and produces errors in the logfile.

Remote keys can be observed in the xbmc.log file (~/.xbmc/temp/xbmc.log on Linux) when debugging is enabled in the GUI (Settings -> debugging ). The list of pre-defined OBC codes can be found at XBIRRemote.h.

Keyboard Section

Valid keyboard keymap syntax includes <keyname>, <key id="">, and <keyname mod="">.

Mapping for arbitrary key codes can be configured using the following syntax:

<key id="123">

where "123" is replaced by the key code.

A full list of valid keynames can be found in

Example:

<keyboard>
  <key id="123">action</key> -- id is the keys keycode. >
  <a mod="shift,alt">action</a> -- corresponds to shift-alt-a, the mod="" syntax is enabled since build 26407. >
  <space>action</space> -- for a complete list of valid keynames, see ButtonTranslator.cpp or List of XBMC keynames above. >
</keyboard>

Microsoft XBOX 360 Controller Section

Valid Microsoft XBOX 360 Controller syntax is <button id="x">action</button> or <axis id="x" limit="y">action</axis>.

Here is a full list of button and axis mappings:

Buttons:

  • 1 - A
  • 2 - B
  • 3 - X
  • 4 - Y
  • 5 - LB
  • 6 - RB
  • 7 - Start
  • 8 - Guide
  • 9 - Left Stick Button
  • 10 - Right Stick Button
  • 11 - D-Pad Up
  • 12 - D-Pad Down
  • 13 - D-Pad Left
  • 14 - D-Pad Right
  • 15 - Back

Axis Mappings:

  • 1 - Left Stick L/R
  • 2 - Left Stick U/D
  • 3 - Left Trigger
  • 4 - Right Stick L/R
  • 5 - Right Stick U/D
  • 6 - Right Trigger

Example:

<keymap>
  <global>
    <joystick name="Xbox 360 Wireless Receiver">
      <altname>Controller (Gamepad for Xbox 360)</altname>
      <altname>Controller (XBOX 360 For Windows)</altname>
      <button id="1">Select</button>
      <button id="2">Back</button>
      <button id="3">FullScreen</button>
      <button id="4">ContextMenu</button>
    </joystick>
  </global>
</keymap>

Sony Play Station 3 Sixaxis Controller Section

Valid Microsoft PS3 Sixaxis Controller syntax is <button id="x">action</button> or <axis id="x" limit="y">action</axis>.

Here is a full list of button:

Buttons:

  • 1 - Select
  • 2 - L3
  • 3 - R3
  • 4 - Start
  • 5 - D-Pad Up
  • 6 - D-Pad Right
  • 7 - D-Pad Down
  • 8 - D-Pad Left
  • 9 - L2
  • 10 - R2
  • 11 - L1
  • 12 - R1
  • 13 - Triangle
  • 14 - Circle
  • 15 - X
  • 16 - Square

Example:

<keymap>
  <global>
    <joystick name="PLAYSTATION(R)3 Controller (00:06:F7:66:24:76)">
      <button id="1">Info</button>          <!-- Select -->
      <button id="2">ContextMenu</button>   <!-- L3 -->
      <button id="3">CodecInfo</button>     <!-- R3 -->
      <button id="4">Play</button>          <!-- Start -->
      <button id="5">Up</button>            <!-- D-Pad Up -->
      <button id="6">Right</button>         <!-- D-Pad Right -->
      <button id="7">Down</button>          <!-- D-Pad Down -->
      <button id="8">Left</button>          <!-- D-Pad Left -->
      <button id="9">Rewind</button>        <!-- L2 -->
      <button id="10">FastForward</button>  <!-- R2 -->
      <button id="11">SkipPrevious</button> <!-- L1 -->
      <button id="12">SkipNext</button>     <!-- R1 -->
      <button id="13">ParentDir</button>    <!-- Triangle -->
      <button id="14">Stop</button>         <!-- Circle -->
      <button id="15">Select</button>       <!-- X -->
      <button id="16">OSD</button>          <!-- Square -->
    </joystick> 
  </global>
</keymap>

Custom Joystick Configuration

Custom joysticks are defined using the following syntax:

<joystick name="JOYSTICK NAME">
  <button id="BUTTON ID">action</button>
</joystick>

Getting the joystick name:

  • On linux: 'cat /proc/bus/input/devices'
  • or see your xbmc log file

Getting the button ids:

  • 'id' is the button ID used by SDL. Joystick button ids of connected joysticks appear in xbmc.log when they are pressed. Use your log to map custom buttons to actions.

Example:

<joystick name="PLAYSTATION(R)3 Controller (00:1B:FB:F6:E0:F2)">
  <button id="15">Select</button>
  <button id="14">PreviousMenu</button>
</joystick>

Actions

The most recent available actions can be found in the TranslateActionString() method in in ButtonTranslator.cpp.

For those debugging integer action codes from the debug log, the mapping of action codes to constants is in Key.h

In addition to the following actions, you can also use Built-in scripting in XBMC. Keymap/Actions

Windows

Keymap/Windows

Additional keys

Other keys that can be mapped to actions.

Media keyboards/remotes

  • browser_back
  • browser_forward
  • browser_refresh
  • browser_stop
  • browser_search
  • browser_favorites
  • browser_home
  • volume_mute
  • volume_down
  • volume_up
  • next_track
  • prev_track
  • stop
  • play_pause
  • launch_mail
  • launch_media_select
  • launch_app1
  • launch_app2
  • play
  • pause
  • fastforward
  • rewind
  • channelup
  • channeldown

Mouse actions

  • leftclick
  • rightclick
  • middleclick
  • doubleclick
  • wheelup
  • wheeldown
  • mousedrag
  • mousemove

See also

Development: