ezEngine  Milestone 7
ezStandardInputDevice Class Reference

Implements an input device abstraction on top of the SFML library. More...

#include <InputDevice_SFML.h>

Inheritance diagram for ezStandardInputDevice:

Public Member Functions

 ezStandardInputDevice (sf::Window *pWindow, ezUInt32 uiWindowNumber)
 
void WindowMessage (const sf::Event &TheEvent)
 This function needs to be called whenever an SFML event arrives, such that the input device can handle it.
 
void SetClipMouseCursor (bool bEnable)
 Will trap the mouse inside the application window. Should usually be enabled, to prevent accidental task switches. More...
 
bool GetClipMouseCursor () const
 Returns whether the mouse is confined to the application window or not.
 
virtual void SetShowMouseCursor (bool bShow)
 Shows or hides the mouse cursor inside the application window. More...
 
virtual bool GetShowMouseCursor () const
 Returns whether the mouse cursor is shown.
 
 ezStandardInputDevice (ezUInt32 uiWindowNumber)
 
void WindowMessage (HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam)
 This function needs to be called by all Windows functions, to pass the input information through to this input device.
 
void SetClipMouseCursor (bool bEnable)
 Will trap the mouse inside the application window. Should usually be enabled, to prevent accidental task switches. More...
 
bool GetClipMouseCursor () const
 Returns whether the mouse is confined to the application window or not.
 
virtual void SetShowMouseCursor (bool bShow) override
 Shows or hides the mouse cursor inside the application window.
 
virtual bool GetShowMouseCursor () const override
 Returns whether the mouse cursor is shown.
 
- Public Member Functions inherited from ezInputDeviceMouseKeyboard
virtual void SetMouseSpeed (const ezVec2 &vScale)
 Sets the scaling factor that is applied on all (relative) mouse input.
 
ezVec2 GetMouseSpeed () const
 Returns the scaling factor that is applied on all (relative) mouse input.
 
- Public Member Functions inherited from ezInputDevice
 ezInputDevice ()
 Default Constructor.
 

Static Public Member Functions

static ezStandardInputDeviceGetDevice (ezUInt32 uiWindowNumber=0)
 Returns an ezStandardInputDevice device for the given window.
 
static void DestroyAllDevices ()
 Destroys all devices of this type. Automatically called at engine shutdown.
 
static void LocalizeButtonDisplayNames ()
 Calling this function will 'translate' most key names from English to the OS language, by querying that information from the OS. More...
 

Private Member Functions

 EZ_ADD_DYNAMIC_REFLECTION (ezStandardInputDevice)
 
virtual void InitializeDevice () override
 Override this if you need to do device specific initialization before the first use.
 
virtual void UpdateInputSlotValues () override
 Override this, if you need to query the state of the hardware to update the input slots. More...
 
virtual void RegisterInputSlots () override
 Override this to register all the input slots that this device exposes. More...
 
virtual void ResetInputSlotValues () override
 Override this, if you need to reset certain input slot values to zero, after the ezInputManager is finished with the current frame update.
 
void UpdateMouseCursor ()
 
 EZ_ADD_DYNAMIC_REFLECTION (ezStandardInputDevice)
 
virtual void InitializeDevice () override
 Override this if you need to do device specific initialization before the first use.
 
virtual void UpdateInputSlotValues () override
 Override this, if you need to query the state of the hardware to update the input slots. More...
 
virtual void RegisterInputSlots () override
 Override this to register all the input slots that this device exposes. More...
 
virtual void ResetInputSlotValues () override
 Override this, if you need to reset certain input slot values to zero, after the ezInputManager is finished with the current frame update.
 

Private Attributes

sf::Window * m_pWindow
 
ezUInt32 m_uiWindowNumber
 
ezVec2I32 m_vEmulatedMousePos
 
ezVec2I32 m_vLastMousePos
 
bool m_bShowCursor
 
bool m_bClipCursor
 

Static Private Attributes

static bool s_bMainWindowUsed = false
 

Additional Inherited Members

- Static Protected Member Functions inherited from ezInputDevice
static void RegisterInputSlot (const char *szName, const char *szDefaultDisplayName, ezBitflags< ezInputSlotFlags > SlotFlags)
 Calls RegisterInputSlot() on the ezInputManager and passes the parameters through.
 
- Protected Attributes inherited from ezInputDevice
ezMap< ezString, float > m_InputSlotValues
 Stores all the values for all input slots that this device handles. More...
 
ezUInt32 m_LastCharacter
 If this input device type handles character input, it should write the last typed character into this variable. The ezInputManager calls RetrieveLastCharacter() to query what the user typed last.
 

Detailed Description

Implements an input device abstraction on top of the SFML library.

Unfortunately SFML does neither support relative mouse motion, nor clipping a mouse cursor to the window area. Thus relative and absolute mouse position are 'emulated' by this device. As a consequence, relative mouse motion only works without limits, when the mouse cursor is clipped (in that case it is reset to the window center after each movement).

SFML has several other limitations, as well. For example keyboard input is not language setting independent. To see the effect, just try out what different things happen when you use an English, German and Russian language setting :-( Therefore, it is highly advised to make all key-mappings configurable, such that users with other language settings can 'fix' this on their end.

Also many special keys are not properly supported by SFML, most notably Numpad Enter is handled like Return.

Member Function Documentation

void ezStandardInputDevice::LocalizeButtonDisplayNames ( )
static

Calling this function will 'translate' most key names from English to the OS language, by querying that information from the OS.

The OS translation might not always be perfect for all keys. The translation can change when the user changes the keyboard layout. So if he switches from an English layout to a German layout, LocalizeButtonDisplayNames() should be called again, to update the display names, if that is required.

virtual void ezStandardInputDevice::RegisterInputSlots ( )
overrideprivatevirtual

Override this to register all the input slots that this device exposes.

This is called once during initialization. It needs to call RegisterInputSlot() once for every input slot that this device exposes to the system.

Implements ezInputDevice.

void ezStandardInputDevice::RegisterInputSlots ( )
overrideprivatevirtual

Override this to register all the input slots that this device exposes.

This is called once during initialization. It needs to call RegisterInputSlot() once for every input slot that this device exposes to the system.

Implements ezInputDevice.

void ezStandardInputDevice::SetClipMouseCursor ( bool  bEnable)

Will trap the mouse inside the application window. Should usually be enabled, to prevent accidental task switches.

Especially on multi-monitor systems, the mouse can easily leave the application window (even in fullscreen mode). Do NOT use this function when you have multiple windows and require absolute mouse positions.

void ezStandardInputDevice::SetClipMouseCursor ( bool  bEnable)

Will trap the mouse inside the application window. Should usually be enabled, to prevent accidental task switches.

Especially on multi-monitor systems, the mouse can easily leave the application window (even in full-screen mode). Do NOT use this function when you have multiple windows and require absolute mouse positions.

Note
Unfortunately the SFML implementation has some restrictions regarding relative and absolute mouse positions. Therefore when the mouse cursor is clipped to the window area, it is actually always centered in the window. This enables relative mouse motions without limits (ie. the cursor cannot reach the screen border, thus it can be moved indefinitely). On the other hand, it does not make much sense to show the mouse cursor and have it clipped, as the actual OS cursor position will be quite useless. However, ez then 'emulates' the absolute cursor position, thus retrieving the absolute mouse position from the input device still works as expected.

If, however, you need to allow the user to move the mouse cursor outside the window, be aware that the relative mouse motions will stop working, once the mouse cursor reaches the screen borders.

void ezStandardInputDevice::SetShowMouseCursor ( bool  bShow)
virtual

Shows or hides the mouse cursor inside the application window.

Note
When SetClipMouseCursor is enabled, the mouse will always be centered in the window. In that case it should also always be hidden.

Implements ezInputDeviceMouseKeyboard.

virtual void ezStandardInputDevice::UpdateInputSlotValues ( )
inlineoverrideprivatevirtual

Override this, if you need to query the state of the hardware to update the input slots.

Note
This function might be called multiple times before ResetInputSlotValues() is called. This will be the case when ezInputManager::PollHardware is used to make more frequent hardware updates than input is actually processed. Just make sure to always accumulate delta values (such as mouse move values) and don't expect ResetInputSlotValues() to be called in tandem with this function and it will be fine.

Implements ezInputDevice.

void ezStandardInputDevice::UpdateInputSlotValues ( )
overrideprivatevirtual

Override this, if you need to query the state of the hardware to update the input slots.

Note
This function might be called multiple times before ResetInputSlotValues() is called. This will be the case when ezInputManager::PollHardware is used to make more frequent hardware updates than input is actually processed. Just make sure to always accumulate delta values (such as mouse move values) and don't expect ResetInputSlotValues() to be called in tandem with this function and it will be fine.

Implements ezInputDevice.


The documentation for this class was generated from the following files: