Cogs in mainly a graphics engine but also supports some input event handling for:
Input events from input devices are handled outside Cogs and Cogs support Bridge functions to send the events to Cogs. These events are stored in Cogs and handled on the next rendering.
An application handling all interaction relates only to the selected GUI framework. Input events from mouse and keyboard in the 3D window is also handled in the application.
Adding Cogs input handling requires synchronization to select where the input events shall be handled. If Cogs debug GUI is enabled and the user clicks in a Debug GUI text field, the mouse down and further move events should be ignored by the application (not trying to pick anything behind the GUI element), likewise keyboard events should be directed to the text field only.
GUI frameworks determines which element shall have focus, e.g. receiving mouse and keyboard events. The target element is normally decided when hovering the mouse above the element, but the framework can also 'capture' the mouse (setPointerCapture()) and keyboard. Used when clicking in in a text field to type text.
For synchronization Cogs uses notion of Focus for both focus and capture.
The Cogs GUI stored input events passed from the client and the events are handled in the rendering loop.
Application input handling should ideally be performed after rendering letting Cogs GUI handling the events first. This is not practically possible and input synchronization is recommended to improve usage for application developers when showing Cogs Debug GUI.
Actual interface to use is exported by each language interface. Cogs Bridge exposes the basic functionality.
/*!
Returns true if any of given input devices is has GUI Focus in Cogs.
E.g. for Keyboard: typing in text field.
Mouse: Hovering above GUI window, Dragging slider, Pressing mouse button to do interaction.
\param inputDeviceTypes - Device type(s) to check. See enum InputDeviceType
*/
CogsBool hasGuiInputFocus(BridgeView * bv, int inputDeviceTypes);
// Receiving Keyboard event.
if (!::hasInputDeviceFocus(view, int(InputDeviceType::Keyboard))) {
// Cogs does not need to consume this event (e.g. typing text in a Cogs Text Control)
DoApplicationHandling(event);
}
Cogs demo application has keyboard shortcuts to toggle Cogs Debug GUI ('g'), select next demo ('+') etc.
If not using the above synchronizing Key 'g' works as expected toggling the Debug GUI. But if user wants to change resource path in Debug GUI, typing a path with 'g' will just hide the Debug GUI.
// Receiving Mouse event.
if (!::hasInputDeviceFocus(view, int(InputDeviceType::Mouse))) {
// Cogs does not need to consume this event (e.g. Dragging Cogs Slider, Cogs 3D Interaction, etc)
DoApplicationHandling(event);
}
An application doing own interaction should stop navigation if the user opens the Debug GUI and drags a slider while pressing mouse button.
Note that Cogs 3D interaction (OrbitingCameraController) is not currently notifying the application about mouse focus. This controller is handling most mouse events and an application wanting to do much custom interaction and navigation should consider doing all 3D interaction.
An application doing own 3D interaction may choose to not pass any input events to Cogs unless the application has enabled the Cogs Debug GUI.
Sensitive user keyboard input can then be isolated from Cogs. Check Language dependent Cogs API for possible support.