README

License & Disclaimer

Copyright (C) 2007-2010 Ruud Senden | SilentException

 

This Program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

 

This Program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

 

Use this program at your own risk, I can not be held responsible for any damage.

 

You should have received a copy of the GNU General Public License along with this program; see the file COPYING.  If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. http://www.gnu.org/copyleft/gpl.html

Introduction

This is a generic MediaPortal keyboard input plug-in. By using a similar mapping mechanism as used for remote controls, one can map arbitrary key presses to MediaPortal actions, windows, etc. The main differences with the standard MediaPortal keyboard handling are as follows:

  • This plug-in takes the Ctrl, Alt, Shift and Win modifier keys into account.
  • This plug-in allows you to map key combinations not only to actions, but also to windows and such.
  • Configuration of this plug-in is similar as the standard MediaPortal Remote Plugin configurations.

 

With some imagination, this plug-in can be used for various very different purposes. Some examples:

  • Many remote controls act like an HID keyboard, where each button corresponds with a specific keystroke. Most remote controls send keystroke combinations that include Ctrl, Alt, Shift and sometimes Win modifier keys. For example, the Asus S-Presso remote control sends Ctrl-B for Replay, Ctrl-Shift-B for Rewind and Ctrl-Alt-Shift-B for Repeat buttons. This plug-in enables you to control MediaPortal using such a remote control.
  • The standard MediaPortal key mapping mechanism doesn’t allow mapping keystrokes to windows. Using this plug-in, you can create keyboard shortcuts to specific MediaPortal screens. Both built-in MediaPortal windows and windows defined by plug-ins are supported.
  • You may want to bind different actions to the same key depending on the context. For example in the Home screen you may want the number keys to act like a shortcut to various windows or actions, but have them act as regular number keys in all other screens. This is possible using the standard remote-like key mapping provided by this plug-in.
  • You may want to bind different, possibly somewhat related actions to the same key depending on which modifier key is pressed. Using this plug-in, you can for example define ‘B’ as Back, Ctrl-B as Replay, Ctrl-Shift-B as Rewind, etcetera.

Supported MediaPortal versions

This plug-in has been compiled and tested against MediaPortal 1.1.0. However, it may also work for earlier and/or later MediaPortal versions. If you find that it works with any other version of MediaPortal, please post a message on the forum (see below).

Installation Instructions

Using MediaPortal Extension Installer:

  1. Start the MediaPortal Extension Installer.
  2. Find the KeyboardInputPlugin extension in the list of known extensions. If you want to include (possibly newer) beta versions in your list, make sure to enable the corresponding option in the MediaPortal Extension Installer.
  3. Install the plug-in as usual, following the on-screen instructions.
  4. After installation, the KeyboardInputPlugin configuration screen will be shown. Refer to the ‘Plug-in Configuration’ section below for more information.

 

Manual installation:

  1. Copy the Release\plugins\process\KeyboardInputPlugin.dll file to the <MediaPortal install dir>\plugins\pocess directory.
  2. Several predefined Keyboard.xml files are available in the Release\InputDeviceMappings\examples\* folders. Copy one of these files, corresponding to your intended use, to the <MediaPortal install dir>\InputDeviceMappings\default directory.
  3. Depending on the Keyboard.xml file you chose in the previous step, additional configuration may be required. You can add button definitions and configure the button mappings by using the MediaPortal Configuration program. Refer to the ‘Plug-in Configuration’ section below for more information.
  4. Start MediaPortal and check whether your key definitions work.

Plug-in Configuration

Button definitions and mappings can be updated via the plug-in configuration screen. This screen is available via MediaPortal Configuration -> Plugins -> Process Plugins -> KeyboardInputPlugin -> Configure. Configuration is quite similar to the standard remote control configuration screens included in MediaPortal. By selecting a button node, you can add, remove or re-arrange actions for that specific button. Please refer to the regular MediaPortal Remote Control Configuration documentation for more information.

 

The main difference compared to the standard remote control configuration screens is that you can add new button definitions and modify existing ones. Buttons are defined by a button name and a button code. The button name can be any name you like. The button code is a special code that corresponds to a specific keystroke combination. For background information about button codes, refer to the ‘Button Codes’ section below. However, usually the button code is generated (learned) automatically.

 

In order to add a new button definition, select the root node (named ‘Keyboard’ by default, but may be different depending on which Keyboard.xml file is used) in the tree view. Then click the ‘New’ button at the bottom to add a new button node named ‘New Button’. To delete an existing button definition, select the button node and click the ‘Remove’ button at the bottom.

 

In order to modify the button name or button code for a newly created or existing button, you can use the ‘Button’ section in the upper right corner of the configuration window. First select the button node that you wish to modify, then change its name and/or button code. In order to have the program automatically learn a button code:

1.      Make sure that the ‘Learn Mode’ checkbox is checked

2.      Click into the ‘Button code’ text box (e.g. make sure that this text box has focus)

3.      Simply press the keystroke combination or remote button that you want the plug-in to learn

 If successful, the button code will change from 0 to some other number.

 

The important areas, as discussed above, are depicted in the picture below:

Additional information for Windows 7 users

Windows 7 sometimes automatically disables the keyboard hook if it doesn’t respond in time (for example due to high CPU load). Usually the plug-in will automatically recover from this situation and restart the hook. However, the plug-in may miss one or more keystrokes before being able to recover. If this is a problem for you (for example because the hook is disabled quite frequently), you can try the following registry change:

1.      Open regedit and go to: HKEY_CURRENT_USER\Control Panel\Desktop\

2.      Change/create: "LowLevelHooksTimeout" as DWORD and set the value to "5000", then reboot. Remember to backup the old key value, if any.

3.      You can also experiment with the key value from 500 to 10000.

If you suffer from this problem a lot, please let us know on the forum thread (see below) so we can try to implement additional workarounds.

Other information

A MediaPortal forum thread about this plug-in is available at http://forum.team-mediaportal.com/generic_keyboard_remote_input_plugin-t25755.html. Please let me know there how this plug-in works for you, and whether you have any suggestions. Please also post you own Keyboard.xml file (from the MediaPortal application data directory) for specific remotes such that we can add it to the installation package.

Button Codes

The button codes as used by this plug-in are based on key codes defined by the C# Keys enumeration, as listed below. For the Shift, Control, Alt and Win modifiers, one should mathematically add 1000, 10000, 100000 or 1000000 to the key code respectively. Some examples:

 

Key code 66 = “B”

Key code 10066 = “Ctrl-B”

Key code 11066 = “Ctrl-Shift-B”

Key code 111066 = “Ctrl-Alt-Shift-B”

Key code 1111066 = “Ctrl-Alt-Shift-Win-B”

 

List of key codes defined by the C# Keys enumeration:

 

        //     The BACKSPACE key.

        Back = 8

        //     The TAB key.

        Tab = 9

        //     The LINEFEED key.

        LineFeed = 10

        //     The CLEAR key.

        Clear = 12

        //     The ENTER key.

        Enter = 13

        //     The RETURN key.

        Return = 13

        //     The PAUSE key.

        Pause = 19

        //     The ESC key.

        Escape = 27

        //     The SPACEBAR key.

        Space = 32

        //     The PAGE UP key.

        Prior = 33

        //     The PAGE UP key.

        PageUp = 33

        //     The PAGE DOWN key.

        Next = 34

        //     The PAGE DOWN key.

        PageDown = 34

        //     The END key.

        End = 35

        //     The HOME key.

        Home = 36

        //     The LEFT ARROW key.

        Left = 37

        //     The UP ARROW key.

        Up = 38

        //     The RIGHT ARROW key.

        Right = 39

        //     The DOWN ARROW key.

        Down = 40

        //     The SELECT key.

        Select = 41

        //     The PRINT key.

        Print = 42

        //     The EXECUTE key.

        Execute = 43

        //     The PRINT SCREEN key.

        PrintScreen = 44

        //     The PRINT SCREEN key.

        Snapshot = 44

        //     The INS key.

        Insert = 45

        //     The DEL key.

        Delete = 46

        //     The HELP key.

        Help = 47

        //     The 0 key.

        D0 = 48

        //     The 1 key.

        D1 = 49

        //     The 2 key.

        D2 = 50

        //     The 3 key.

        D3 = 51

        //     The 4 key.

        D4 = 52

        //     The 5 key.

        D5 = 53

        //     The 6 key.

        D6 = 54

        //     The 7 key.

        D7 = 55

        //     The 8 key.

        D8 = 56

        //     The 9 key.

        D9 = 57

        //     The A key.

        A = 65

        //     The B key.

        B = 66

        //     The C key.

        C = 67

        //     The D key.

        D = 68

        //     The E key.

        E = 69

        //     The F key.

        F = 70

        //     The G key.

        G = 71

        //     The H key.

        H = 72

        //     The I key.

        I = 73

        //     The J key.

        J = 74

        //     The K key.

        K = 75

        //     The L key.

        L = 76

        //     The M key.

        M = 77

        //     The N key.

        N = 78

        //     The O key.

        O = 79

        //     The P key.

        P = 80

        //     The Q key.

        Q = 81

        //     The R key.

        R = 82

        //     The S key.

        S = 83

        //     The T key.

        T = 84

        //     The U key.

        U = 85

        //     The V key.

        V = 86

        //     The W key.

        W = 87

        //     The X key.

        X = 88

        //     The Y key.

        Y = 89

        //     The Z key.

        Z = 90

        //     The 0 key on the numeric keypad.

        NumPad0 = 96

        //     The 1 key on the numeric keypad.

        NumPad1 = 97

        //     The 2 key on the numeric keypad.

        NumPad2 = 98

        //     The 3 key on the numeric keypad.

        NumPad3 = 99

        //     The 4 key on the numeric keypad.

        NumPad4 = 100

        //     The 5 key on the numeric keypad.

        NumPad5 = 101

        //     The 6 key on the numeric keypad.

        NumPad6 = 102

        //     The 7 key on the numeric keypad.

        NumPad7 = 103

        //     The 8 key on the numeric keypad.

        NumPad8 = 104

        //     The 9 key on the numeric keypad.

        NumPad9 = 105

        //     The multiply key.

        Multiply = 106

        //     The add key.

        Add = 107

        //     The separator key.

        Separator = 108

        //     The subtract key.

        Subtract = 109

        //     The decimal key.

        Decimal = 110

        //     The divide key.

        Divide = 111

        //     The F1 key.

        F1 = 112

        //     The F2 key.

        F2 = 113

        //     The F3 key.

        F3 = 114

        //     The F4 key.

        F4 = 115

        //     The F5 key.

        F5 = 116

        //     The F6 key.

        F6 = 117

        //     The F7 key.

        F7 = 118

        //     The F8 key.

        F8 = 119

        //     The F9 key.

        F9 = 120

        //     The F10 key.

        F10 = 121

        //     The F11 key.

        F11 = 122

        //     The F12 key.

        F12 = 123

        //     The F13 key.

        F13 = 124

        //     The F14 key.

        F14 = 125

        //     The F15 key.

        F15 = 126

        //     The F16 key.

        F16 = 127

        //     The F17 key.

        F17 = 128

        //     The F18 key.

        F18 = 129

        //     The F19 key.

        F19 = 130

        //     The F20 key.

        F20 = 131

        //     The F21 key.

        F21 = 132

        //     The F22 key.

        F22 = 133

        //     The F23 key.

        F23 = 134

        //     The F24 key.

        F24 = 135

        //     The browser back key (Windows 2000 or later).

        BrowserBack = 166

        //     The browser forward key (Windows 2000 or later).

        BrowserForward = 167

        //     The browser refresh key (Windows 2000 or later).

        BrowserRefresh = 168

        //     The browser stop key (Windows 2000 or later).

        BrowserStop = 169

        //     The browser search key (Windows 2000 or later).

        BrowserSearch = 170

        //     The browser favorites key (Windows 2000 or later).

        BrowserFavorites = 171

        //     The browser home key (Windows 2000 or later).

        BrowserHome = 172

        //     The volume mute key (Windows 2000 or later).

        VolumeMute = 173

        //     The volume down key (Windows 2000 or later).

        VolumeDown = 174

        //     The volume up key (Windows 2000 or later).

        VolumeUp = 175

        //     The media next track key (Windows 2000 or later).

        MediaNextTrack = 176

        //     The media previous track key (Windows 2000 or later).

        MediaPreviousTrack = 177

        //     The media Stop key (Windows 2000 or later).

        MediaStop = 178

        //     The media play pause key (Windows 2000 or later).

        MediaPlayPause = 179

        //     The launch mail key (Windows 2000 or later).

        LaunchMail = 180

        //     The select media key (Windows 2000 or later).

        SelectMedia = 181

        //     The start application one key (Windows 2000 or later).

        LaunchApplication1 = 182

        //     The start application two key (Windows 2000 or later).

        LaunchApplication2 = 183

        //     The OEM 1 key.

        Oem1 = 186

        //     The OEM Semicolon key on a US standard keyboard (Windows 2000 or later).

        OemSemicolon = 186

        //     The OEM plus key on any country/region keyboard (Windows 2000 or later).

        Oemplus = 187

        //     The OEM comma key on any country/region keyboard (Windows 2000 or later).

        Oemcomma = 188

        //     The OEM minus key on any country/region keyboard (Windows 2000 or later).

        OemMinus = 189

        //     The OEM period key on any country/region keyboard (Windows 2000 or later).

        OemPeriod = 190

        //     The OEM question mark key on a US standard keyboard (Windows 2000 or later).

        OemQuestion = 191

        //     The OEM 2 key.

        Oem2 = 191

        //     The OEM tilde key on a US standard keyboard (Windows 2000 or later).

        Oemtilde = 192

        //     The OEM 3 key.

        Oem3 = 192

        //     The OEM 4 key.

        Oem4 = 219

        //     The OEM open bracket key on a US standard keyboard (Windows 2000 or later).

        OemOpenBrackets = 219

        //     The OEM pipe key on a US standard keyboard (Windows 2000 or later).

        OemPipe = 220

        //     The OEM 5 key.

        Oem5 = 220

        //     The OEM 6 key.

        Oem6 = 221

        //     The OEM close bracket key on a US standard keyboard (Windows 2000 or later).

        OemCloseBrackets = 221

        //     The OEM 7 key.

        Oem7 = 222

        //     The OEM singled/double quote key on a US standard keyboard (Windows 2000

        //     or later).

        OemQuotes = 222

        //     The OEM 8 key.

        Oem8 = 223

        //     The OEM 102 key.

        Oem102 = 226

        //     The OEM angle bracket or backslash key on the RT 102 key keyboard (Windows

        //     2000 or later).

        OemBackslash = 226

        //     The PROCESS KEY key.

        ProcessKey = 229

        //     The ATTN key.

        Attn = 246

        //     The CRSEL key.

        Crsel = 247

        //     The EXSEL key.

        Exsel = 248

        //     The ERASE EOF key.

        EraseEof = 249

        //     The PLAY key.

        Play = 250

        //     The ZOOM key.

        Zoom = 251

        //     The PA1 key.

        Pa1 = 253

        //     The CLEAR key.

        OemClear = 254