2011-06-29, 20:02
If all went well, you have now mapped all the basic functionality and you know how to emulate keyboard presses. There is one slight problem, though, which you will probably find out if you start mapping all the functionality onto your remote. It's kind of obvious when you think about it. The solution however, can be bit more complicated. But let's start with the problem. The problem is that your remote probably has much fewer keys than your remote has.
When using a keyboard, you have the luxury of having a large number of keys available and the standard XBMC keyboard.xml to at least some extent uses this space. Practically, this means that you have a lot of keys that do have some function, but that are simply unavailable in many parts of the program. For instance, there's the 'O' key, which displays codec information while playing a movie. But in the rest of the program, it doesn't seem to do one bit. Or the 'C' button. It displays the context menu when browsing through the files or library, but in other parts is doesn't seem to have any function.
When using a keyboard, it doesn't really matter. Like I said, there are more than enough keys. But when using a regular remote you do NOT have this luxury. Having buttons that are useless 70% of the time is a waste of buttons. If you want to map all functionality, you will have to come up with a creative solution, especially when you don't have a lot of buttons.
In this part I will try to outline one solution that could solve this problem. I will show you how you can create multifunctional remote buttons that have a different function depending on the context in which this button is used. This means that you can 'recycle' a button in different environments in different parts of the program. I had gotten used to this efficient behaviour before I had my 'real' remote and used the Android XBMC App:
For instance, the title button not only triggers the context menu, the same button also shows the codec info when playing a video. And the "menu" button of course triggers the menu, but it also returns you to your Home Screen instantly when your are not playing a video. I found this to be very efficient use of (virtual) buttons and wanted to copy this behaviour with my real remote.
After all, if you don't and you have a limited number of buttons on your remote, you're going to have to settle for a limited subset of the functionality. Or you would have to start working with rather illogical button mappings, such as mapping certain actions to the numeric section of the remote. It'd be like an automated phone call: press 1 for codec info, press 2 for ...
Fortunately, the framework to make this happen already exists and is already being used, even on a keyboard (take for example the "up" key). This magic is all contained in, or at least exposed to the user via keyboard.xml and any user-specific or system wide overrides. And that's exactly what you have to do: create overrides for the vanilla keyboard.xml to map your buttons exactly the way you want to. After all, remember we are emulating a keyboard, so we can configure it as such.
First it's important that you understand how the keyboard.xml file works. Have a good look at the vanilla keyboard.xml. The structure of this file is pretty simple, although maybe a bit too verbose due to being XML and all. The general structure is like this:
So there a different sections. The most important one is "global". Other examples include Home, MyVideoLibrary, FullscreenVideo and lots of others. Just have a look at the default keyboard.xml. The important thing is that you realize there are different sections that can each have different keymappings.
Knowing this, mapping the right actions to exactly the right keys should be relatively easy. However, do NOT change the default keyboard.xml. Rather, create a file of which the contents will automatically override the respective mapping from the central keyboard.xml. The location of this file or these files is ~/.xbmc/userdata/keymaps/. All the files there that have the .xml extension will be processed automatically by XBMC. All you have to do is create a file there (e.g. custom.xml) and you're good to go.
Also important are the actions. You can see most of them in the keyboard.xml file, but there's an exhaustive list here. Those are the actions/command that XBMC will understand. Most them are pretty much self-explanatory, but there's always the description.
So now the actual mapping. To smoothen this process, make sure that in one tab/windows you have the default keyboard.xml and in another the available actions.
Let's go back to the example where we want to map the ContextMenu and CodecInfo to one button on our remote. First, you have to look how they are mapped now. The Context Menu can be triggered with the "C" key as you can see. The Codec Info overlay can be triggered using the "O" button. Now you can do two things: map the Codec Info to the C button or the Context Menu to the O in the appropriate sections. Technically it doesn't matter which route you take, but it's smart to check how many overrides you need and take the one that requires the least overrides. Both actions have been defined globally, so we can simply count the sections in which we would need overrides. Say we wanted to map ContextMenu to "O". We would have to create overrides in MyVideoLibrary, MyVideoFiles, MyMusicLibrary, ... MyFiles, etc, etc. Basically everywhere where you can browse files or database entries. Those are a lot of sections. However, if we chose to map CodecInfo to "C" it would be less work. With <FullscreenVideo> the most important mapping would already be fixed.
Now, make sure your custom.xml has the proper structure to begin with, which is basically a <keymap> tag to open and a </keymap> tag to close. Between those tags you can map your keys (within sections). So we wanted to map the CodecInfo action the the C button. The first question is in which sections. Global? No, because then the content menu wouldn't function anymore. So, where do we need CodecInfo? Only when a video is playing of course. The most prominent section is <FullscreenVideo>, but there are also other. If we make this map, everytime you press the button that is mapped to KEY_C in ir-keytable, you get the codec info overlay, while in other parts of XBMC the default behaviour of the C button remains (open/close a context menu).
Another, slightly simpler example, is this: normally, the backspace key goes to the parent directory (i.e. back). But when playing a video I wanted to use my "back" button to go back 7 secs. This way I have a good control over the video: up/down for a big step (10 minutes or one chapter) forward/backward, left/right for 30 second steps and back for a 7 second step back (in case I missed something someone just said or something that just happened and I don't want to rewatch 30 seconds).
And you can also add 'new' functionality. For instance, I have a "Home" button, with which I would like to go back to the Home Screen whenever I press it. There's no mapping to a normal key, so we have to create one. The "H" is not in use so let's take that one. We can just define it in the 'global' section. The action is XBMC.ActivateWindow(Home).
Also, I would like the "menu" button ("M" on the keyboard) to open the Settings. In the video sections this button has already been mapped to opening the OSD Menu, so all we have to do is create a 'global' override (which is not valid for the sections where "M" has already been defined explicitly). The resulting file looks like this:
In the comments I documented the default behaviour for KEY_C, but it's not necessary of course. Note the repetitive pattern with just different section tags. I hope it's pretty self-explanatory.
So know you know how to 'add' functionality/actions and override currently mapped functionality. Note that the examples I just gave you are just that: examples. Like I said, I was basically inspired by the way the XBMC Android Remote App mapped its buttons. When mapping your own keys you will have to use your own preferences and creativity.
When using a keyboard, you have the luxury of having a large number of keys available and the standard XBMC keyboard.xml to at least some extent uses this space. Practically, this means that you have a lot of keys that do have some function, but that are simply unavailable in many parts of the program. For instance, there's the 'O' key, which displays codec information while playing a movie. But in the rest of the program, it doesn't seem to do one bit. Or the 'C' button. It displays the context menu when browsing through the files or library, but in other parts is doesn't seem to have any function.
When using a keyboard, it doesn't really matter. Like I said, there are more than enough keys. But when using a regular remote you do NOT have this luxury. Having buttons that are useless 70% of the time is a waste of buttons. If you want to map all functionality, you will have to come up with a creative solution, especially when you don't have a lot of buttons.
In this part I will try to outline one solution that could solve this problem. I will show you how you can create multifunctional remote buttons that have a different function depending on the context in which this button is used. This means that you can 'recycle' a button in different environments in different parts of the program. I had gotten used to this efficient behaviour before I had my 'real' remote and used the Android XBMC App:
For instance, the title button not only triggers the context menu, the same button also shows the codec info when playing a video. And the "menu" button of course triggers the menu, but it also returns you to your Home Screen instantly when your are not playing a video. I found this to be very efficient use of (virtual) buttons and wanted to copy this behaviour with my real remote.
After all, if you don't and you have a limited number of buttons on your remote, you're going to have to settle for a limited subset of the functionality. Or you would have to start working with rather illogical button mappings, such as mapping certain actions to the numeric section of the remote. It'd be like an automated phone call: press 1 for codec info, press 2 for ...
Fortunately, the framework to make this happen already exists and is already being used, even on a keyboard (take for example the "up" key). This magic is all contained in, or at least exposed to the user via keyboard.xml and any user-specific or system wide overrides. And that's exactly what you have to do: create overrides for the vanilla keyboard.xml to map your buttons exactly the way you want to. After all, remember we are emulating a keyboard, so we can configure it as such.
First it's important that you understand how the keyboard.xml file works. Have a good look at the vanilla keyboard.xml. The structure of this file is pretty simple, although maybe a bit too verbose due to being XML and all. The general structure is like this:
Code:
<keymap>
<global>
<keyboard>
<key1>Action1</key1>
<key2>Action2</key2>
...
</keyboard>
</global>
<section1>
<keyboard>
<key1>Action2</key1>
...
</keyboard>
</section1>
<section2>
<keyboard>
<key1>Action3</key1>
...
</keyboard>
</section2>
...
</keymap>So there a different sections. The most important one is "global". Other examples include Home, MyVideoLibrary, FullscreenVideo and lots of others. Just have a look at the default keyboard.xml. The important thing is that you realize there are different sections that can each have different keymappings.
Knowing this, mapping the right actions to exactly the right keys should be relatively easy. However, do NOT change the default keyboard.xml. Rather, create a file of which the contents will automatically override the respective mapping from the central keyboard.xml. The location of this file or these files is ~/.xbmc/userdata/keymaps/. All the files there that have the .xml extension will be processed automatically by XBMC. All you have to do is create a file there (e.g. custom.xml) and you're good to go.
Also important are the actions. You can see most of them in the keyboard.xml file, but there's an exhaustive list here. Those are the actions/command that XBMC will understand. Most them are pretty much self-explanatory, but there's always the description.
So now the actual mapping. To smoothen this process, make sure that in one tab/windows you have the default keyboard.xml and in another the available actions.
Let's go back to the example where we want to map the ContextMenu and CodecInfo to one button on our remote. First, you have to look how they are mapped now. The Context Menu can be triggered with the "C" key as you can see. The Codec Info overlay can be triggered using the "O" button. Now you can do two things: map the Codec Info to the C button or the Context Menu to the O in the appropriate sections. Technically it doesn't matter which route you take, but it's smart to check how many overrides you need and take the one that requires the least overrides. Both actions have been defined globally, so we can simply count the sections in which we would need overrides. Say we wanted to map ContextMenu to "O". We would have to create overrides in MyVideoLibrary, MyVideoFiles, MyMusicLibrary, ... MyFiles, etc, etc. Basically everywhere where you can browse files or database entries. Those are a lot of sections. However, if we chose to map CodecInfo to "C" it would be less work. With <FullscreenVideo> the most important mapping would already be fixed.
Now, make sure your custom.xml has the proper structure to begin with, which is basically a <keymap> tag to open and a </keymap> tag to close. Between those tags you can map your keys (within sections). So we wanted to map the CodecInfo action the the C button. The first question is in which sections. Global? No, because then the content menu wouldn't function anymore. So, where do we need CodecInfo? Only when a video is playing of course. The most prominent section is <FullscreenVideo>, but there are also other. If we make this map, everytime you press the button that is mapped to KEY_C in ir-keytable, you get the codec info overlay, while in other parts of XBMC the default behaviour of the C button remains (open/close a context menu).
Another, slightly simpler example, is this: normally, the backspace key goes to the parent directory (i.e. back). But when playing a video I wanted to use my "back" button to go back 7 secs. This way I have a good control over the video: up/down for a big step (10 minutes or one chapter) forward/backward, left/right for 30 second steps and back for a 7 second step back (in case I missed something someone just said or something that just happened and I don't want to rewatch 30 seconds).
And you can also add 'new' functionality. For instance, I have a "Home" button, with which I would like to go back to the Home Screen whenever I press it. There's no mapping to a normal key, so we have to create one. The "H" is not in use so let's take that one. We can just define it in the 'global' section. The action is XBMC.ActivateWindow(Home).
Also, I would like the "menu" button ("M" on the keyboard) to open the Settings. In the video sections this button has already been mapped to opening the OSD Menu, so all we have to do is create a 'global' override (which is not valid for the sections where "M" has already been defined explicitly). The resulting file looks like this:
Code:
<keymap>
<global>
<keyboard>
<h>XBMC.ActivateWindow(Home)</h>
<m>XBMC.ActivateWindow(Settings)</m>
</keyboard>
</global>
<FullscreenVideo>
<keyboard>
<c>CodecInfo</c> <!-- Default: ContextMenu -->
<backspace>SmallStepBack</backspace> <!-- Default: ParentDir -->
</keyboard>
</FullscreenVideo>
<FullscreenInfo>
<keyboard>
<c>CodecInfo</c>
</keyboard>
</FullscreenInfo>
<VideoOSD>
<keyboard>
<c>CodecInfo</c>
</keyboard>
</VideoOSD>
<OSDVideoSettings>
<keyboard>
<c>CodecInfo</c>
</keyboard>
</OSDVideoSettings>
<OSDAudioSettings>
<keyboard>
<c>CodecInfo</c>
</keyboard>
</OSDAudioSettings>
</keymap>In the comments I documented the default behaviour for KEY_C, but it's not necessary of course. Note the repetitive pattern with just different section tags. I hope it's pretty self-explanatory.
So know you know how to 'add' functionality/actions and override currently mapped functionality. Note that the examples I just gave you are just that: examples. Like I said, I was basically inspired by the way the XBMC Android Remote App mapped its buttons. When mapping your own keys you will have to use your own preferences and creativity.
