CzInput Class Reference

This class is responsible for handling all keyboard, pointer and other input devices input. More...

#include <CzInput.h>

List of all members.

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.

---

Detailed Description

This class is responsible for handling all keyboard, pointer and other input devices input.

Introduction

AppEasy provides the CzInput singleton class to manage all game input. CzInput manages the following types of input:

• Single and multi-touch input
• Button and key states
• On screen keyboard input
• Acceleromter
• Compass

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();

Checking Availability

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

Single and Multi-touch Touches

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.

Working with Touches

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.

Checking Key / Button States

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.

On Screen Keyboard

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.

Accelerometer Input

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:

CzVec3 accelerometer_pos = CZ_INPUT->getAccelerometerPosition();

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:

CzVec3 accelerometer_pos = CZ_INPUT->getAccelerometerOffset();

Compass Input

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:

CzVec3 compass_heading = CZ_INPUT->getCompassHeading();
float compass_directiom = CZ_INPUT->getCompassDirection();

---

Member Enumeration Documentation

enum CzInput::eInputTypeHint

Passed to showOnScreenKeyboard() to hint at what type of keyboard entry to show.

Enumerator:

Hint_Text
Hint_Number
Hint_Password
Hint_Email
Hint_URL

---

Member Function Documentation

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.

---

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

• CzInput.h
• CzInput.cpp