Torque Device and Input
From TorqueWiki
Contents |
[edit] Input Links
http://tdn.garagegames.com/wiki/TorqueScript_Console_Functions_6
wiki/TorqueScript/Input/Overview
wiki/Script/Input_Keys_and_Maps
[edit] Event Handling
- Input events come from the OS,
- are translated in the platform layer and then posted to the game.
- by default game then checks the input event against a global action map (which supercedes all other action handlers)
- If there is no action specified for the event, it is passed on to the GUI system.
- If the GUI does not handle the input event it is passed to the currently active (non-global) action map stack.
[edit] Action Maps
Action maps map platform input events to console commands. Any platform input event can be bound in a single generic way - so in theory the game doesn't need to know if the event came from the keyboard, mouse, joystick or some other input device. This allows users of the game to map keys and actions according to their own preferences.
Commands:
ActionMap::bind(), ActionMap::bindCmd()
There is one defined ActionMap object that is processed first for all events called GlobalActionMap.
Game action maps are arranged in a stack for processing - so individual parts of the game can define specific actions - for example when the player jumps into a vehicle it could push a vehicle action map and pop the default player action map.
[edit] Input Event Processing in the GUI system
Input events are first processed for dispatch in GuiCanvas::processInputEvent. Depending on the type of input event (keyboard or mouse), the Canvas processes the event in different ways.
For keyboard events, the Canvas maintains an instance variable call the first responder (mFirstResponder). The first responder is essentially the control that has keyboard focus - for example a text field that the user is typing into or a button that the user has tabbed to. For any keyboard event, the first responder has the first chance to process it. If it does not process the event it passes it up to its parent class and then in GuiControl finally to its parent control. If the keyboard event is not handled by any control in the responder chain (from first responder up to the root content control), the Canvas checks to see if it is a special key - tab and shift-tab set the first responder to the next and previous controls in the tab list respectively. If it is not tab or shift-tab, the Canvas checks to see if the key is in the accelerator map for any of the controls visible (for example an OK button mapped to the enter key). If it is not mapped, the Canvas passes back false, signifying that the event should be processed by the action map handler.
For mouse events (if the cursor is on), the event is handled by the GUI system. Each mouse event can potentially generate several virtual method calls to controls. For example, moving the mouse cursor from one control into another will cause the first control to receive an onMouseLeave method call, followed by an onMouseEnter method call to the new control and finally an onMouseMove to that control as well. GuiControls can lock the mouse focus on the canvas so that only that control receives mouse method invocations - for example the GuiButtonCtrl control locks the mouse on mouse down and unlocks it on mouse up so that even if the user moves the cursor outside the control, the button still maintains focus and can re-highlight when the cursor is moved back inside. The GuiControl virtual method pointInControl by default returns true if the cursor is inside the bounding rectangle of the control. Control subclasses with non-rectangular shapes can override this method to provide controls with irregular mouse boundaries.
[edit] The GUI system and the Console
The GUI system is designed to work tightly with the Console language. The GuiControl class has an instance variable called mConsoleVariable which is the name of a global console variable that will, if set, reflect the state of that control in a control-dependant way. For example, a variable that is mapped to a checkbox control will have the value of 1 when the control is checked and 0 when it is not. Each GuiControl also has an instance variable called mConsoleCommand and mAltConsoleCommand that get executed in different cases depending on the control - in the case of a GuiButton the mConsoleCommand script gets evaluated when the button is clicked (in GuiControl::onAction()).
Another way the GUI system interacts with the console is via Console namespaces - when you name a control (like MainMenuQuitButton) that control name is registered as a namespace whose parent is the control's class, and special console methods can then be invoked from code on that control - in the case of a button the buttons onAction console method will be called when the button is pressed. Custom controls can be built in this way to execute several different commands with custom arguments.
