Documentation
[SDK Documentation] [CGapiInput]

 

GapiDraw Classes CGapiSurface CGapiRGBASurface CGapiDraw CGapiDisplay CGapiMaskSurface CGapiBitmapFont CGapiCursor CGapiApplication CGapiInput CGapiVFS CGapiTimer CGapiGradient

CGapiInput

Overview

GapiInput locks all hardware keys and maps the up/down/left/right keys to the correct orientation of the display.

This document has been updated for use with GapiDraw 4.2 or later.
Last updated on July 11, 2009.

 

CGapiInput::OpenInput

Enables a full, exclusive lock of all hardware keys on the mobile device.

HRESULT OpenInput();
Parameters

None

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_LOCKEDKEYS
GDERR_NOGAPI

Remarks

When destroying the CGapiInput object, the keyboard lock will be released automatically.

In the GapiDraw builds for Windows Mobile 5.0 and later devices, CGapiInput will use the AllKeys API to lock the keys of the mobile device.

In the GapiDraw builds for Pocket PC 2003 devices, CGapiInput will use the GAPI library "gx.dll" to lock the keys of the mobile device. For CGapiInput to find the file "gx.dll" it needs to be placed in the \Windows folder or the application folder of your program. If the file gx.dll should not be available CGapiDisplay::OpenDisplay will return GDERR_NOGAPI, but you will still be able to use CGapiInput for mapping the directional keys.

CGapiInput::CloseInput

Releases the exclusive lock on all hardware keys. This is automatically done in the destructor.

HRESULT CloseInput();
Parameters

None

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_NOTLOCKED

CGapiInput::GetKeyList

Returns a list of virtual key codes matching the current display orientation.

HRESULT GetKeyList(GDKEYLIST* pKeyList);
Parameters
pKeyList
Address of a GDKEYLIST structure that will be filled with virtual key codes.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTLOCKED

Remarks

The list of virtual key codes contains values for

  1. vkA, vkB and vkC - three of the hardware buttons (on mobile devices: soft button 1 + 2 and record, on stationary PCs: "1", "2" and "3")
  2. vkStart - the "action" button (<enter> on stationary PCs)
  3. Arrow keys (left/right/up/down)

The orientation of the arrow keys (up/down/left/right) will be adjusted to match the display orientation. "Up" will for example always be -Y.

In the GapiDraw builds for Windows Mobile 5.0 and later devices the key mapping is defined as follows:
vkA = VK_TSOFT1, vkB = VK_TSOFT2, vkC = VK_TRECORD, vkStart = VK_RETURN. This mapping is according to the Microsoft specification at http://msdn.microsoft.com/en-us/library/bb431750.aspx.

In the GapiDraw builds for Pocket PC 2003, the values of vkA, vkB, vkC and vkStart will be set by the GAPI library (gx.dll).