just say no to GAPI – What you need to know about AllKeys and input management.

The Games API (GAPI) was a technology that allowed Windows Mobile 2003 applications to quickly draw graphics onto the device screen. It also contained functions that allowed an application to request all button press messages, even the ones that were normally intercepted by the Windows Mobile operating system.

The graphics component of GAPI was replaced by DirectDraw (which allowed hardware acceleration) in Windows Mobile 5.0. Application compatibility was maintained so that older programs would still work.

Most of the reference material for GAPI was removed from the Windows Mobile 6.1 documentation set, although the input functions were kept, so that applications could still request all key and button presses.  Application compatibility was maintained for this release as well.

This is all changing for the next generation of Windows Mobile, Windows Mobile 6.5.  Although some devices may still support GAPI, there is no longer a requirement for device manufacturers or mobile operators to ship or test for compatibility with GAPI.  This means that applications that require GAPI will provide an unpredictable experience for users on Windows Mobile 6.5 devices.

Another important change is that acceptance to the Windows Marketplace for Mobile and Designed for Windows Mobile certification requires no application dependencies on GAPI.

In order to replace the input functionality that GAPI once provided, a new keyboard API function is being made public.  This function is AllKeys() , and is defined below.  One great thing about this substitution is that AllKeys has been a part of Windows Mobile as long as GAPI, and is actually the API call that GAPI wrapped in order to publicly expose this functionality. This means that the transition to AllKeys should be easy, and backwards compatibility should be maintained.

You can migrate your input code to AllKeys in the following way:

Replace:

·         GXOpenInput() with AllKeys(TRUE).

·         GXCloseInput() with AllKeys(FALSE).

While AllKeys is set to true, all key presses will be sent to your application for handling.

Since GXOpenInput and GXCloseInput were simply wrappers for a call to AllKeys, so this substitution should cause no change in behavior in your programs.

The following is the definition of the new AllKeys API.

AllKeys

This function allows your programs to request that all key presses be sent directly to the requesting application. Normally some buttons are intercepted by the operating system for its own use, but games and input - intensive applications may want access to these buttons for their own use.

Syntax

BOOL AllKeys(

     BOOL bAllKeys

);

Parameters

Parameter

Description

bAllKeys

[in] If bAllKeys is set to TRUE, this function allows all keyboard events to be sent to the application. (This includes the soft-key buttons and back button).

If it is set to FALSE, this function specifies standard keyboard event behavior. Some events including soft-key buttons and the back button are not sent to the application.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Sample Code

The following C++ code illustrates how to use AllKeys. In the application that this sample is taken from, a check box is used to set AllKeys to true or false.

// process checkbox

case IDC_ALL_KEYS_CHECK_BOX:

if (g_AllKeys == true)

    {

    // Allow the OS to intercept some button presses

     AllKeys(FALSE);

    g_AllKeys = false;

    // set button state

    SendMessage(hwndCtl,BM_SETCHECK, BST_UNCHECKED,0);

    }

else

    {

    // Do not allow os to intercept button presses

    AllKeys(TRUE);

    g_AllKeys = true;

    //set button state

    SendMessage(hwndCtl,BM_SETCHECK, BST_CHECKED,0);

    }

Requirements

OS Versions: Windows Mobile 2003 and later.

Header: Winuser.h.