--------------------------------------------------------------------------------------------------------------
Input shortcuts on Cockpit Tooltips     v. 1.0       10 July 2010
--------------------------------------------------------------------------------------------------------------

OVERVIEW
--------------------------------------------------------------------------------------------------------------
1. Introduction
2. Package contents
3. Instalation / uninstalation
4. Script files info
5. Known/predicted issues and limitations
6. ToDo
7. Thanks to
8. Contact

1. INTRODUCTION
--------------------------------------------------------------------------------------------------------------
NOTE 1:
  This package was created to extend great mod "Tooltips with Keyboard Shortcuts" created by Miguez
  (many thanks for the inspiration).
  Thread about this mod can be found on ED Forums
  ( http://forums.eagle.ru/showthread.php?p=615135#post615135 ).
NOTE 2:
  Another usefull mode I have extend in this package is the "Cockpit Tool Tips (Hints) improved visibility" mod
  created by Buci (thanks for excelent start point)
  ( http://forums.eagle.ru/showthread.php?p=890758#post890758 )


  What it extends?
    No key shortcuts are hardcoded into the scripts.
    Shortcuts are taken from current user configuration before the mission load.
    Tooltips format is widely configurable. (even too widely, perhaps)
    Tooltips size and lifetime is configurable from within gameplay menu.
  What are the benefits?
    Shortcuts are always compatible with your configuration, even if the configuration has changed.


  Background of my work is really simple. I have noticed that when we change some key bindings
  we have to change originally modifed (see Note 1) clickabledata.lua script manually.
  As a result we have two places where our bindings are stored. I was digging up tons of LUA scripts
  to find a way to link cockpit tooltips with the input commands programatically.
  Finally, oryginal game hints have been extended by the key sequence currently bound to each input
  option, so there is no need to modify clickabledata.lua file in case of key binding changes.


2. PACKAGE CONTENTS
--------------------------------------------------------------------------------------------------------------
  This package consist of:

  BlackShark\modules\me_options.lua                                - widget bindings/load/save
  BlackShark\modules\me_options_form.lua                           - labels initialization
  BlackShark\modules\dialogs\me_options_gameplay.dlg               - new widgets to configure tooltips
  Config\tooltips.cfg                                              - Tooltips configuration file
  FUI\Resourcesbs\DHint.res                                        - hints lifetime and delaytime and size
  Scripts\Aircrafts\Ka-50\Cockpit\clickabledata.lua                - entry point for hint_map.lua script
  Scripts\Aircrafts\Ka-50\Cockpit\hint_map.lua                     - searches for input mappings


3. INSTALLATION / UNINSTALLATION
--------------------------------------------------------------------------------------------------------------
  Before instalation make sure that you back up all your oryginal/modified files listed above.
  Installation/unistallation using ModMan 7.3.0 or later is adviced. Mod is compatible with
  DSC: Black Shark v.1.0.2
  
  In case of any conflicts with any existing mods or serverside files, please inform me by email.
  (My email address is at the bottom of this file)


4. SCRIPT FILES INFO
--------------------------------------------------------------------------------------------------------------
First of all. It seems that files can be unreadable to the game when edited with unsupported encoding.
All files provided in this package are encodd with UTF-8.

hint_map.lua
  This file has three purposes:
  A. Read all user input configuration and store it in local table for further use.
  B. Create mapping between cockpit switches and input options available to the player.
  C. Replace old LOCALIZE function implementation with the new one.


  A.
______________________________________________________________________________________________________________
package.path = package.path .. ';./blackshark/modules/?.lua'
local NewInput = require('NewInput')
dofile('scripts/input/layout.lua')
dofile('scripts/input/aircrafts.lua')
local oldGetDeviceType = getDeviceType
______________________________________________________________________________________________________________
     These lines initiate oryginal tools which provide support for input configuration files.

______________________________________________________________________________________________________________
local function addDeviceCommandCombos(commands)
______________________________________________________________________________________________________________
     This function adds all key shortcuts for specific command to local variable inputShortcutsMap.

______________________________________________________________________________________________________________
local cfg_path = 'Config/Input/Aircrafts/'
local aircraftName = 'ka-50'
______________________________________________________________________________________________________________
     Some named strings.


local devices = NewInput.getDevices()
______________________________________________________________________________________________________________
     Gets all devices currently detected by the game.

______________________________________________________________________________________________________________
for i, device in pairs(devices) do
   local path = getLayoutPath(aircraftName, device)
   local layout = Layout()
   layout:open(path)
   addDeviceCommandCombos(layout.keyCommands)
   addDeviceCommandCombos(layout.axisCommands)
end
______________________________________________________________________________________________________________
     Function "getLayoutPath" finds configuration file path for input device in hierarchical manner
     ('\Config\Input\Aircrafts\ka-50\keyboard\keyboard.lua' or
      '\Config\Input\Aircrafts\ka-50\keyboard\default.lua')
     For details see 'scripts/input/aircrafts.lua' file. Next the Layout wrapper object is created
     based on configuration file. Then keyCommands and axisCommands are added to map.

  B.
______________________________________________________________________________________________________________
hintInputMap = {}
-- CPT MECH
hintInputMap["Gear lever"] = {"Gear lever"}
(...)
-- ZMS_3 (Magnetic Variation Entry Panel)
hintInputMap["Magnetic variation selection rotaty"] = {["Left"]="Magnetic variation knob left", ["Right"]="Magnetic variation knob right"}
______________________________________________________________________________________________________________
     In this part mapping is created for each hint. For example, "Gear lever" has only one function
     which is titled exactly the same "Gear lever" in options menu. But "Magnetic variation
     selection rotaty" has two functions: "Magnetic variation knob left" and "Magnetic variation
     knob right", thus first function shortcut will be displayed on the tooltip as
     "Left = ( RShift + RCtrl + M )" and the second one as
     "Right = ( RShift + RAlt + M )". Finally, the whole tooltip will looks like this:
     "Magnetic variation selection rotaty   Left ( RShift + RCtrl + M )   Right ( RShift + RAlt + M )"

  C.
______________________________________________________________________________________________________________
local function getInputShortcuts(input, key)
______________________________________________________________________________________________________________
     This function builds shortcut string for specified input option (ie. "Magnetic variation knob
     left") and key (ie. "Left"). If the control has only one function, key will be equal 1 and won't
     be added to shortcut string.

______________________________________________________________________________________________________________
local OLD_LOCALIZE_REALIZATION = LOCALIZE
function LOCALIZE(hintText)
______________________________________________________________________________________________________________
     Input mapping search. Replacing of the LOCALIZE function in order to change tooltip string
     (proposed by Alex O'kean on ED Forums http://forums.eagle.ru/showpost.php?p=615249&postcount=7 )


5. KNOWN/PREDICTED ISSUES AND LIMITATIONS
--------------------------------------------------------------------------------------------------------------
  - I have found no explicit linkage of cockpit controls with the key codes placed in input configuration.
    All mappings are done manually.
  - It would be nice to have shortcuts placed below the switch tooltips in a multiline manner.
  - Several tooltips are really long.
  - Mod has been tested only with English version of DCS: Black Shark. It should work in Russan version
    as well (old LOCALIZE function is still in use), but it should be checked.
  - New gameplay Menu options are always English. I have found no way to localize them.
  - This is my first LUA script so there should exist a simpler way to get the same effect with more reliable
    approach.
  - Only the "Real mode" shortcuts are supported. They are also displayed in Arcade mode. (I don't know
    how to get the name of the current aircraft in lua script)


6. TODO
--------------------------------------------------------------------------------------------------------------
  - Add support for 'arcade' mode
  - Multiplayer may be affected. Dont know how the server may react on such modifications.

7. THANKS TO
--------------------------------------------------------------------------------------------------------------
  Thanks to Buci for his DHint.res file attached to this package

8. Contact
--------------------------------------------------------------------------------------------------------------
In case of any issues, corrections or bugs feel free to contact me at:
    hubert.bukowski@gmail.com

--------------------------------------------------------------------------------------------------------------
Hopefully this mod will save your time and help to master the cockpit of the Black Shark.

Happy flying,
  Hubert 'Baal' Bukowski
