ShowKeyboard 

1.0     2.0     

Shows or hides the on-screen keyboard. (Not supported in Japanese version.)

 

Note  This function is provided only for compatibility with version 1.0 of the Pen API, and will not be supported in future versions. It is not supported for 32-bit applications. Applications should interface directly with the on-screen keyboard.

 

BOOL ShowKeyboard( HWND hwnd, UINT wCommand, LPPOINT lppt, LPSKBINFO lpSKBInfo )

Parameters

hwnd

Handle of window invoking the on-screen keyboard.

wCommand

A show request and optional keypad. The values for the show requests are listed in the  Comments  section below.

lppt

Address of a POINT44VP0_ structure containing the keyboard position in screen coordinates. If NULL, the keyboard appears centered on the display.

lpSKBInfo

Address of an SKBINFO1AOCY7 structure to be filled with values for the current keyboard. This parameter is ignored if NULL. If the hwnd member of the SKBINFO structure is NULL, no on-screen keyboard has been loaded.

Return Value

Returns TRUE if successful; otherwise FALSE.

Comments

Any user action on the keyboard itself overrides the function requests. For example, if the user closes the on-screen keyboard, the keyboard becomes unregistered for all windows in all applications. If the user minimizes the keyboard, the active SKBINFO structure is changed to reflect the new state.

ShowKeyboard tracks registration information for up to 20 window handles. If one application displays the keyboard and then another one does the same thing, both applications must request that the keyboard be hidden before it actually disappears.

The following SKB_ requests can be specified in the wCommand parameter:

Constant

Description

SKB_HIDE

Hides the on-screen keyboard. This request may not actually hide the keyboard if another application is also using it. The command decrements the use count for the keyboard. SKB_HIDE automatically loads the on-screen keyboard if it is not already present.

SKB_QUERY

Returns the current state of the keyboard pointed to
by the lpSKBInfo parameter without invoking a new keyboard state. This command does not automatically load the on-screen keyboard.

SKB_SHOW

Shows the on-screen keyboard in a restored state at
the most recently used screen location. This command increments a window-use count. SKB_SHOW automatically loads the on-screen keyboard if it is not present.

 

The SKB_SHOW command in the wCommand parameter can be combined using the bitwise-OR operator with any of the command or keypad requests listed in the following tables:

Constant

Description

SKB_CENTER

Centers the keyboard on the display. This command
has higher priority than SKB_MOVE.

SKB_MINIMIZE

Displays the on-screen keyboard in a minimized state. This command can be used with SKB_CENTER or SKB_MOVE. If it is used with SKB_MOVE, the location specified will be used when the keyboard is restored.

SKB_MOVE

Moves the keyboard to the location specified by the lppt parameter. If lppt is NULL, the keyboard is centered on the screen. If it is not NULL, lppt specifies a pointer to the x and y screen coordinates of the upper-left corner of the restored keyboard.

 

The following keypad requests can be used with SKB_SHOW in the wCommand parameter. The SKB_BASIC, SKB_FULL, and SKB_NUMPAD constants can not be combined with the OR operator:

Constant

Description

SKB_BASIC

Switches the keyboard to a partial keyboard with no extended keys.

SKB_FULL

Switches the keyboard to the full 101-key display.

SKB_NUMPAD

Switches the keyboard to a partial keyboard consisting only of ESC, TAB, SHIFT, and the numeric keypad.

 

The following three bitmaps are provided for owner-draw push buttons that can be used to invoke the on-screen keyboard. The application must process WM_DRAWITEM and other button-related code. On-screen keyboard push buttons should behave the same way as other standard buttons (for example, the Minimize button) and take the appropriate action when a button-up message is received following a button-down message.

Constant

Description

OBM_SKBBTNUP

Push button is up.

OBM_SKBBTNDOWN

Push button is down.

OBM_SKBBTNDISABLED

Push button is disabled.

 

Example

The up bitmap, for example, can be loaded as shown in the following code sample:

HANDLE hDLL = GetSystemMetrics( SM_PENWINDOWS );

HBITMAP hBitmap = LoadBitmap( hDLL,

                       MAKEINTRESOURCE(OBM_SKBBTNUP) );

The application must call the Windows DeleteObjectY31AVA function to delete each bit-map handle returned by the Windows LoadBitmapA1XQ1H function.

The button should be left in the up state after it is released. If the user closes the keyboard and the buttons are up, they will still be up the next time the keyboard is opened. The following code sample retrieves the current keyboard and restores the current state:

#include <penwin.h>

 

if (ShowKeyboard( hwnd, SKB_SHOW, NULL, NULL)) // Nonzero: no error.

           .

           .                        // Perform some tasks.

           .

     ShowKeyboard( hwnd, SKB_HIDE, NULL, NULL );

}

else

     ErrorMsg( "Unable to use Screen Keyboard" );

 

The following code sample moves the keyboard and then puts it back into its starting position:

SKBINFO skbinfo;

WORD wCommand = SKB_SHOW | SKB_MOVE;

POINT pnt;

 

pnt.x = wSKBLeft;    // Initialize point.

pnt.y = wSKBTop;

 

// Show the keyboard.

 

ShowKeyboard( hwnd, wCommand, &pnt, &skbinfo );

           .

           .

           .

// Now restore the keyboard.

 

if (skbinfo.fVisible)

     wCommand = SKB_SHOW | SKB_MOVE |

           (skbinfo.fMinimized ? SKB_MINIMIZED : 0);

else

     wCommand = SKB_HIDE;

 

ShowKeyboard( hwnd, wCommand, (LPPOINT)(&skbinfo.rect), NULL) ;