![]() |
AppEasy Core SDK
1.5.0
Cross platform mobile and desktop app and game development SDK - The easy way to make apps
|
This class is responsible for handling all keyboard, pointer and other input devices input. More...
#include <CzInput.h>
Public Types | |
enum | eInputTypeHint { Hint_Text = 0, Hint_Number = 1, Hint_Password = 2, Hint_Email = 3, Hint_URL = 4 } |
Passed to showOnScreenKeyboard() to hint at what type of keyboard entry to show. More... | |
Public Member Functions | |
bool | isPointerAvailable () const |
Returns availability of the pointer. | |
bool | isKeysAvailable () const |
Returns availability of keys. | |
bool | isOSKeyboardAvailable () const |
Returns availability of on screen keyboard. | |
bool | isAccelerometerAvailable () const |
Returns availability of accelerometer. | |
bool | isCompassAvailable () const |
Returns true if compass is available. | |
bool | isMultiTouch () const |
Returns multitouch capability. | |
CzTouch * | getTouchByID (int id) |
Returns the touch identified by its id. | |
CzTouch * | getTouch (int index) |
Gets a specific touch. | |
CzTouch * | getFirstTouch () |
Returns last touch that was made. | |
CzTouch * | findTouch (int id) |
Finds a specific touch by its id. | |
int | getTouchCount () const |
Get number of touches this frame. | |
bool | hasTapped () const |
Returns tapped status. | |
bool | isTouching (int index) const |
Returns true if specified touch at the specified index is touching. | |
CzIVec2 | getTouchedPos (int index) const |
Returns the touch position of the touch at the specified index. | |
CzIVec2 | getDragDelta (int index) const |
Returns tapped status of the touch at the specified index. | |
bool | isDragging (int index) const |
Returns true if the user has moved the touch at the specified index. | |
void | setKeyCodeMapping (uint8 *mapping_table) |
Sets the hardware to AppEasy key nappnig table. | |
bool | isKeyDown (int key) const |
Tests if a key is down. | |
bool | isKeyUp (int key) const |
Tests if a key is up. | |
bool | wasKeyPressed (int key) const |
Tests if a key was pressed. | |
bool | wasKeyReleased (int key) const |
Tests if a key was released. | |
const char * | showOnScreenKeyboard (const char *prompt, int flags=0, const char *default_text=NULL) |
bool | isBackPressed () |
void | resetBackPressed () |
bool | isMenuPressed () |
void | resetMenuPressed () |
int | getLastKey () const |
bool | startAccelerometer () |
Start accelerometer input. | |
void | stopAccelerometer () |
Stop accelerometer input. | |
void | setAccelerometerReference () |
Sets the current accelerometer position as a reference posisition. | |
CzVec3 | getAccelerometerPosition () const |
Get current accelerometer position. | |
CzVec3 | getAccelerometerOffset () const |
Get current accelerometer offset from the reference position. | |
bool | startCompass () |
Start compass input. | |
void | stopCompass () |
Stop compass input. | |
CzVec3 | getCompassHeading () const |
Get current compass heading. | |
float | getCompassDirection () const |
Get current compass direction (0 to 360 degrees) | |
bool | Init () |
Initialises the input system (returns true if pointer is supported) | |
void | Release () |
Releases data used by the input system. | |
void | Update () |
Updates the input system, called every frame. |
This class is responsible for handling all keyboard, pointer and other input devices input.
AppEasy provides the CzInput singleton class to manage all game input. CzInput manages the following types of input:
Access to input methods are provided via the CZ_INPUT macro, for example:
if (CZ_INPUT->getTouchCount() > 0) { }
If you are using CzApp then you do not need to worry about initialising, updating or cleaning up the input system, however if you are rolling your own solution then you will need to take care of these steps yourself, here's a quick example showing how to do this:
// Initialise the input system CzInput::Create(); CZ_INPUT->Init(); // Main loop while (1) { // Update input system CZ_INPUT->Update(); } // Shut down the input system CZ_INPUT->Release(); CzInput::Destroy();
As AppEasy is designed to work across multiple platforms you should check to ensure that a particular input system is available before you use it. Here’s a quick example showing how to check that the pointer input is available:
// Check to see that the pointer is available if (CZ_INPUT->isPointerAvailable()) { // Check to see if any touches have been made int num_touches = CZ_INPUT->getTouchCount(); }
AppEasy provides a number of methods to check for particular input systems availability:
bool isPointerAvailable() // Returns availability of the pointer bool isKeysAvailable() // Returns availability of keys bool isOSKeyboardAvailable() // Returns availability of on screen keyboard bool isAccelerometerAvailable() // Returns availability of accelerometer bool isCompassAvailable() // Returns true if compass is available
CzInput supports single and multi-touch events, allowing you to check for multiple simultaneous touches. However many devices do not support multi-touch events so a method has been provided to determine multi-touch support:
bool isMultiTouch() // Returns multitouch capability
If you are developing a game or app that relies on multi-touch then you should implement a fall back method that will work with single touch devices. Touch modes is a good solution that can help mirror multi-touch functionality by putting the pointer into different modes, such as move, scale, rotate etc.. and allow the user to switch between them.
No matter if you are using single or multi-touch functionality retrieving touches is done in very much the same way.
CzInput provides methods that enable you to detect and collect touch data. The usual process is to determine if any touches have been made by calling CZ_INPUT->getTouchCount() and then take a look at the touches list to see what touch events occurred. Here's an example:
// Check to make sure that the pointer is available if (CZ_INPUT->isPointerAvailable()) { // Get the total number of current touches int num_touches = CZ_INPUT->getTouchCount(); if (num_touches != 0) { // Check list of touches to see which are active for (int t = 0; t < CZ_MAX_TOUCHES; t++) { // Get the touch data CzTouch* touch = CZ_INPUT->getTouch(t); if (touch->active) { // Do something with the touch } } } }
Note that getTouch() returns the CzTouch struct for the touch at the specified index. CzTouch looks like this:
struct CzTouch { public: int x, y; ///< Touch position int px, py; ///< Previous touch position int dx, dy; ///< Delta position bool touched; ///< Touched state bool active; ///< Touch active state bool prev_active; ///< Touch active state (last frame) int id; ///< ID of touch - The system tracks multiple touches by assigning each one a unique ID CzTouch() : active(false), prev_active(false), id(-1), touched(false) {} };
If you want to track a touch to monitor its status then you should store its ID and use CzInput::getTouchByID(id) to find it again later.
As you expand your list of supported devices for your products you will discover that devices come in all sorts of different configurations, some will even have hard keyboards / keypads and buttons. For example, the Samsung Galaxy pro has a full QWERTY keyboard and almost all Android devices have hardware buttons for menu, home and back.
To query the state of a key / button (buttons are mapped to keys) you call the following methods of CzInput:
bool isKeyDown(int key) const; // Tests if a key is down bool isKeyUp(int key) const; // Tests if a key is up bool wasKeyPressed(int key) const; // Tests if a key was pressed bool wasKeyReleased(int key) const; // Tests if a key was released
Each method takes a platform independent eCzKeyCode as input.
As most devices do not have hardware keyboards an on screen keyboard is the only method of inputting text into the device. AppEasy provides access to this functionality via showOnScreenKeyboard():
const char* showOnScreenKeyboard(const char* prompt, int flags = 0, const char* default_text = NULL);
Calling this method will display a modal on screen keyboard with the provided prompt text and using the supplied default text (pass NULL if you do not require default text). Flags provides a hint to the system to let it know what type of keyboard you want to display to the user (see eInputTypeHint). Passing 0 for flags will use the default keyboard. Once the on screen keyboard has been dismissed the entered text will be returned as a string.
An accelerometer is a device usually found inside mobile phones and tablets that measures acceleration. This is great for gaming as you can use the actual angle or speed at which the user tilts their device to affect game play. For example, you could for example use the accelerometer to allow the player to navigate a ball around a maze or maybe determine how hard the player wants to hit a ball. However the accelerometer does have limitations. If the users phone is perpendicular to the floor then changes in reading may not be registered.
Accelerometer hardware is usually quite power hungry so in order ot use it you need to start it using:
CZ_INPUT->startAccelerometer();
And when not in use you can turn it off using:
CZ_INPUT->stopAccelerometer();
Per frame update of the accelerometer is automatically taken care of by CzInput.
To read the current position of the accelerometer you call:
Because the user can potentially start a game with the phone held at any angle, reading accelerometer readings are best made from a frame of reference. This is usually the initial position that the user is holding the device at when they start the game. To set the reference point for the accelerometer call:
CZ_INPUT->setAccelerometerReference();
This will set the reference point for offset reads to the current position of the users phone. You may want to display a short instructions screen at this point that informs the user how to hold the phone.
To read the accelerometer position with respect to the reference point call:
The digital compass is a device that uses the Earth's ambient magnetic field to determine the orientation of the users mobile phone or tablet. This allows you to measure the angle of the device and the direction in which its pointing.
Like the accelerometer hardware the compass is usually quite power hungry so in order to use it you need to start it using:
CZ_INPUT->startCompass();
And when not in use you can turn it off using:
CZ_INPUT->stopCompass();
Per frame update of the compass is automatically taken care of by CzInput.
To read the current orientation and heading of the compass you call:
Passed to showOnScreenKeyboard() to hint at what type of keyboard entry to show.
CzTouch * CzInput::findTouch | ( | int | id | ) |
Finds a specific touch by its id.
CzVec3 CzInput::getAccelerometerOffset | ( | ) | const |
Get current accelerometer offset from the reference position.
CzVec3 CzInput::getAccelerometerPosition | ( | ) | const [inline] |
Get current accelerometer position.
float CzInput::getCompassDirection | ( | ) | const [inline] |
Get current compass direction (0 to 360 degrees)
CzVec3 CzInput::getCompassHeading | ( | ) | const [inline] |
Get current compass heading.
CzIVec2 CzInput::getDragDelta | ( | int | index | ) | const [inline] |
Returns tapped status of the touch at the specified index.
CzTouch* CzInput::getFirstTouch | ( | ) | [inline] |
Returns last touch that was made.
int CzInput::getLastKey | ( | ) | const |
CzTouch* CzInput::getTouch | ( | int | index | ) | [inline] |
Gets a specific touch.
CzTouch * CzInput::getTouchByID | ( | int | id | ) |
Returns the touch identified by its id.
int CzInput::getTouchCount | ( | ) | const |
Get number of touches this frame.
CzIVec2 CzInput::getTouchedPos | ( | int | index | ) | const [inline] |
Returns the touch position of the touch at the specified index.
bool CzInput::hasTapped | ( | ) | const [inline] |
Returns tapped status.
bool CzInput::Init | ( | ) |
Initialises the input system (returns true if pointer is supported)
bool CzInput::isAccelerometerAvailable | ( | ) | const [inline] |
Returns availability of accelerometer.
bool CzInput::isBackPressed | ( | ) | [inline] |
bool CzInput::isCompassAvailable | ( | ) | const [inline] |
Returns true if compass is available.
bool CzInput::isDragging | ( | int | index | ) | const |
Returns true if the user has moved the touch at the specified index.
bool CzInput::isKeyDown | ( | int | key | ) | const |
Tests if a key is down.
bool CzInput::isKeysAvailable | ( | ) | const [inline] |
Returns availability of keys.
bool CzInput::isKeyUp | ( | int | key | ) | const |
Tests if a key is up.
bool CzInput::isMenuPressed | ( | ) | [inline] |
bool CzInput::isMultiTouch | ( | ) | const [inline] |
Returns multitouch capability.
bool CzInput::isOSKeyboardAvailable | ( | ) | const [inline] |
Returns availability of on screen keyboard.
bool CzInput::isPointerAvailable | ( | ) | const [inline] |
Returns availability of the pointer.
bool CzInput::isTouching | ( | int | index | ) | const [inline] |
Returns true if specified touch at the specified index is touching.
void CzInput::Release | ( | ) |
Releases data used by the input system.
void CzInput::resetBackPressed | ( | ) | [inline] |
void CzInput::resetMenuPressed | ( | ) | [inline] |
void CzInput::setAccelerometerReference | ( | ) |
Sets the current accelerometer position as a reference posisition.
void CzInput::setKeyCodeMapping | ( | uint8 * | mapping_table | ) | [inline] |
Sets the hardware to AppEasy key nappnig table.
const char * CzInput::showOnScreenKeyboard | ( | const char * | prompt, |
int | flags = 0 , |
||
const char * | default_text = NULL |
||
) |
bool CzInput::startAccelerometer | ( | ) |
Start accelerometer input.
bool CzInput::startCompass | ( | ) |
Start compass input.
void CzInput::stopAccelerometer | ( | ) |
Stop accelerometer input.
void CzInput::stopCompass | ( | ) |
Stop compass input.
void CzInput::Update | ( | ) |
Updates the input system, called every frame.
bool CzInput::wasKeyPressed | ( | int | key | ) | const |
Tests if a key was pressed.
bool CzInput::wasKeyReleased | ( | int | key | ) | const |
Tests if a key was released.