Introduction

The Input System is actually a large number of things all bunched into one.

Primarily it is about giving the user control of what button does what and when.

Quick Guide

To create a special input, such a key mapping try the following:

Basically you create a TEXT file (with like Windows Notepad or something) and have in it something like this: 

 mode=default
 type=key
 data=M
 event=StatusMessage Dropped marker
 event=MarkLocation

Here is a marked up one to explain 

 mode=default         Default   = All entries
 type=key             Type = key (meaning keyboard)
 data=M               Data = The key - a keyboard entry or special like APP1 (hardware key)
 event=StatusMessage  Display the message "Dropped marker"
 event=MarkLocation   Mark the current location

Note that the 'events' are in reverse order (RPN) so status message happens last above.

Here is another example: 

 mode=default
 type=gce
 data=TASK_START
 event=PlaySound \Storage Card\XCSoarScott\TASK_START.wav

The above is a "gce" - a "Glide Computer Event" - rather than a key press. The data entries all have special meaning - e.g. TASK_START = the tasks starts. In this case I play the sound file above. I could also automatically start the logger (although this already happens).

Here is one I used to use for aborting the task 

 mode=default Nav1 Nav2 Nav3 Config1 Config2 Config3 Info1 Info2 Info3 Display1 Display2 Display3 Menu1
 type=key
 data=APP1
 event=AbortTask show
 event=AbortTask toggle

This says that in all modes (well most) and the APP1 key is pressed then toggle the abort task and show the current status.

The reason this one has multiple modes is because the APP1 key is used in many places.

NOTE - you only need to change the entries you want, you don't need to include the whole file - the default is assumed and then effectively you overwrite the entries you want. Glide computer events, key names etc are all on this Wiki page.

Here is the default file for reference...

Common/Data/Input/default.xci

Modes

There is a new concept called Input Mode - this is a the mode the GUI is in for input. For example, you can click on the info boxes and you are now in "infobox" mode. Clicking on the map is called "default". But it doesn't stop there, you can create a new mode called anything you like. This may not mean much - but wait till you combine it with the rest of the features... As an example you can create hierarchical menus.

Hardware vs Screen

Input is not restricted to hardware buttons any more. You can map all your hardware buttons (currently support for APP1 to APP6, Left, Right, Up, Down and Enter, although possibly some more) but also any key code at all. This feature allows those with a built in keyboard to use any key to map to any function in XCS. This is an advantage with an external keyboards. There are a number of bluetooth devices out there (eg: http://shop.brando.com.hk/btgamepad.php?) which can map each of their buttons to any key code - that key code can then be mapped to any feature in XCS. You can then add to the hardware buttons the buttons available to you on external devices. Other inputs (eg: Serial) are also being looked at - and support is in the code for that extension.

We are striving towards a platform which is not only easier to use and more intuitive, but also faster and easier to use in flight as well. As such, another new feature as part of input is the concept of Button Labels. Combined with the modes mentioned above, you can create any arbitrary set of functions to map to any number of buttons. Think about it like creating a tree, or a multiple level menu.

This produces two benefits that I know will be appreciated by people with limited inputs. The first is that you can create menus, where by you press one button to get to the next level (eg: pressing on APP1 brings up AutoZoom?, Pan Mode, Full screen on the other buttons. Press APP1 again and it goes to Terrain, Marker and Auto MacCready?. Press APP1 again and the menu is gone) - but more importantly for those with touch screens and limited buttons, each of these labels can optionally be assigned an Event and you can touch the button area as if it was a button. This means that we can actually control on a touch screen model the entire system without buttons - press an area of the screen and the buttons pop up, click through - change options and more.

More Labels

The combined features of labels, configurable buttons (including from external hardware), hierarchical menus (for lack of a better name), touch screen buttons has allowed us to configure XCS - without recompile - for an enormous range of hardware, and personal preference. And all configurable as plain text, simple files. There is no need for a file, the defaults internally will probably be a combination of a 4 button bottom system with one button always shown on screen for no/few button display.

Layout

The screen layout - location of the labels - is also configurable - allowing us to vary the layout of buttons depending on the type of organiser or desired look and feel.

Events

There is a great unexpected benefit in the development of the input system.

We can execute any number of events attached to an input with only 2 extra lines of code. This worked perfectly. So now we have a basic macro system, allowing many more events to be attached to a single input event.

Glide Computer Events

But it doesn't stop there, this has lead to some more excellent developments. The idea of Glide Computer Events things like "Maximum Height Reached". Currently we play a sound effect for that. But you may choose to play a sound, bring up a message box and write to the log file. You can also call these automatic input.

One nice feature of XCS is the ability to change things such as Zoom and North when Circling. Now you can do so much more. You could choose to point North, Zoom to 1.0 (rather than a relative change), Turn on Vario Sounds, Start a timer. When switching back to Cruise mode, you can bring up the stats box for 30 seconds and flag the thermal exit.

Imagination

The options are limited by your imagination.

This is also contributing to a major reduction in complex code. We can move out these complex tests into one centrally, easier to manage system, reducing bugs and improving maintainability.

Another side benefits of these Macros is User Defined Flight Modes. One idea was a button which switched to Zoom 1.0, Pan ON, Pan Move to Next Waypoint. Basically the ability to jump and see the next waypoint. And in the previous we can change the Input Mode to "ViewWaypoint?" - at which point you can redefine the same button to switch back to your original settings.

The flexibility of this system comes with only one small price. We can't provide an interface within XCS to fully customise all of these near infinitely variable possibilities. However we believe that is unnecessary anyway, you are not likely to change these sort of features very often, and definitely not on the field. That does not mean you can't do it yourself, you can of course edit the plane(sic) text file to change functions.

Contribution

What this really means is that we can have people in the project helping and contributing to the customising of XCS, without having to change the code. This, especially on an open source project is fantastic as it nicely separates the user interface changes from the highly reliable part of the code. It also involves people who can develop new interfaces and functions that are expert gliders but not necessarily programmers.

For information on file formats see Common/Data/Input/template.xci or keep reading this document.

Defaults and Files

WARNING: 4.7 will inroduce a new format. 4.6 introduced an XML parser for working with interfaces. By using XML in our other configuration files (especially task files) we will have files in a similar format, still be plain text and prevent issues when changing versions (currently task files are not compatible between versions or platforms).

The file in the source Common/Data/input/template.xci is used to generate automatically the C code necessary for the default configuration. However it is in the exact same format as can be read in by XCS and therefore can be used literally as a template for a more complicated file.

When you create your own file, you will need to select it as the Input File within XCSoar Menu/Settings/Input Files, and then restart XCS.

File Format

The file is plain text, with key=value pairs and a blank line to indicate the end of a record. 

  mode=default
  type=key
  data=APP1
  event=StatusMessage My favorite settings are done
  event=ScreenModes full
  event=Sounds on
  event=Zoom 1.0
  event=Pan off
  label=My Prefs
  location=1

The record above demonstrates remapping the first hardware key on your organiser to change Pan to off, Zoom to 1.0, Sounds on, ScreenModes? full, and then a status message to tell you it is done.

Lines are terminated by the standard DOS newline which is CRLF (Carrage Return then Line Feed). are terminated by an extra new line.?

Events

Event order

Until further work is done on processing, events are actually done in reverse order - also known as RPN. This is because the events work on the stack principle. Each one is pushed onto the stack for execution, and then executed by popping back off the stack. This has reduced complexity of the code base.

When writing input events, have a look where you put the StatusMessage? and make sure that it is at the top, not the bottom (if you have one).

Event List

Each event is seperately documented here.

{{Reference-Events}}

Modes

XCSoar now has the concept of Modes. These are an arbitrary string that associates with where and what XCS is doing.

Note: a mode entry in a record can have multiple entries by using a space between eg: "infobox menu1 menu2"

List of known modes

  • default - Really map mode, where you mostly are
  • infobox - An info box has been selected on the scrreen
  • <nowiki>* - Any other arbitrary string</nowiki>

Mode precedence has been tricky, so instead of solving the problem it is being worked around. XCS will choose to set a global variable to specify what mode it thinks it is in. This can then be used by the input code to decide what to do. This mode could get out of sink with the real world, and careful checking will be required, but at this stage it seems like the only sensible option.

The code will review first if an entry exists in the current mode, and then in the default mode. This allows you to do one of the following example: Define a default action for button "A" to be "Zoom In" but make that button increase Bugs value in infobox mode only. You can do this by making an "default" and a "infobox" entry. You can also put an entry in for Button "A" for every mode and have complete control.

Special Modes

eg: The level of a menu (Think File vs Edit, vs Tools vs Help) Have special modes, such as the level of the menu you are at. You press one button, then another set become available (like pressing menu and seeing Settings etc). This will be very useful in non-touch screen models. The menu configuration can then be read from this same file and configured, allowing any number of levels and any number of combinations.

The only hard part is what mode to go back to. We need a "Calculate Live Mode" function - which can be called to calculate the real live mode (eg: finalglide vs curse) rather than the temporary mode such as Menu, Special Menu Level, Warning etc.

Labels

The label and location values are examples of what can be done here to allow input button labels to be displayed. What needs to be considered is a simple way of mapping the locations and the size. In some models it may be that buttons are 4 across the top of the screen, where as others it is 3 or 2 or even 6. So both size and location needs to be considered.

The label itself will go through gettext to allow language translations. See Advanced:Language?

Keys

If the type is "key" the key type can have the following possible values

  • APP1 - APP6 - Hardware key on pocket pc
  • F1-F12 - Standard function keys
  • LEFT, RIGHT, UP, DOWN, RETURN - Mapped to arrow keys - joystick on organisers
  • A-Z, 0-9 - and other possible keyboard buttons (case is ignored)

Type

  • key - A key press
  • gce - Glide Computer Event

Glide Computer Events

These are automatically triggered events. They work in exactly the same way, but instead of the user pressing a key, the glide computer triggers the events.

A simple example is moving from Cruise to Climb mode. We want to zoom in, change our track up to north up and switch to full screen. You may also choose to drop a marker with the words "entered thermal". The choicese are up to your imaginations - the GCE (Glide Computer Events) allow you to control what happens.

These are represented as "type=gce" and data=* - as listed below.

  • ARM_READY - ???
  • COMMPORT_RESTART - Restarting COM Ports
  • FLIGHTMODE_FINALGLIDE - Finalglide Mode activated
  • FLIGHTMODE_FINALGLIDE_ABOVE - Plane climbed above Glidepath
  • FLIGHTMODE_FINALGLIDE_BELOW - Plane dropped below Glidepath
  • FLIGHTMODE_FINALGLIDE_TERRAIN - Finalglide is impossible because of terrain height
  • FLIGHTMODE_CRUISE - Cruise Mode activated
  • FLIGHTMODE_CLIMB - Climb Mode activated
  • GPS_CONNECTION_WAIT - Waiting for GPS Connection
  • GPS_FIX_WAIT - Waiting for GPS Fix
  • HEIGHT_MAX - ???
  • LANDING - Landing detected
  • STARTUP_SIMULATOR - XCSoar started in SIM Mode
  • STARTUP_REAL - XCSoar started in FLY Mode
  • TAKEOFF - Takeoff detected
  • TASK_START - Task was started (Valid ?!)
  • TASK_FINISH - Task was finished
  • TASK_NEXTWAYPOINT - Waypoint was reached

Future

  • Combination Presses
  • Double Click
  • Long Click

FAQ

How do I defined Double Click

Double click is hard coded to bring up the menu, for devices that do not have hardware buttons.

Why is the default.xci file not installed

The default.xci file is turned into C code that is compiled directly into the code. The advantage of this is that no data is required to have a basic system working. However you need to know that the data already exists, so reading any xci file assumes it is overwriting values in default. This is also good, but can be a gotcha.

How do I write my own

Use a text editor, name the file "AnyUsefulName?.xci" (the .xci is important) and put it in the "XCSoarData" directory in the "My Documents" folder.

Known Gotchas

1. If you run into odd behaviour from your file it may be because you are using the same mode name that is also in use by the default file. It doesn't always cause problems, but should you encounter this try renaming your mode to something unique. There will then be no confliction.

If you want to start from scratch, start your xci file with: "#CLEAR". But make sure you have appropriate menu items for such things accessing the configuration menu and exit! The working xci file that is compiled into XCSoar is always available onCVS at Common/Data/Input/default.xci so this should always be used as a reference when creating new xci files.

2. It's mentioned above, but always end your file with a blank line including a carriage return.