WM CHAR

This message is sent when an operator presses a key.

Syntax

param1
     USHORT  fsflags     /*  Keyboard control codes. */
     UCHAR   ucrepeat    /*  Repeat count. */
     UCHAR   ucscancode  /*  Hardware scan code. */

param2
     USHORT  usch        /*  Character code. */
     USHORT  usvk        /*  Virtual key codes. */

Parameters

fsflags (USHORT) - Input

Keyboard control codes.

KC_CHAR

Indicates that usch value is valid.

KC_SCANCODE

Indicates that ucscancode is valid. Generally, this is set in all WM_CHAR messages generated from actual operator input. However, if the message has been generated by an application that has issued the WinSetHook function to filter keystrokes, or posted to the application queue, this may not be set.

KC_VIRTUALKEY

Indicates that usvk is valid. Normally usvk should be given precedence when processing the message. Note: For those using hooks, when this bit is set, KC_SCANCODE should usually be set as well.

KC_KEYUP

The event is a key-up transition; otherwise it is a down transition.

KC_PREVDOWN

The key has been previously down; otherwise it has been previously up.

KC_DEADKEY

The character code is a dead key. The application is responsible for displaying the glyph for the dead key without advancing the cursor.

KC_COMPOSITE

The character code is formed by combining the current key with the previous dead key.

KC_INVALIDCOMP

The character code is not a valid combination with the preceding dead key. The application is responsible for advancing the cursor past the dead-key glyph and then, if the current character is not a space, sounding the alarm and displaying the new character code.

KC_LONEKEY

Indicates if the key is pressed and released without any other keys being pressed or released between the time the key goes down and up.

KC_SHIFT

The SHIFT state is active when key press or release occurred.

KC_ALT

The ALT state is active when key press or release occurred.

KC_CTRL

The CTRL state was active when key press or release occurred.

ucrepeat (UCHAR) - Input

Repeat count.

ucscancode (UCHAR) - Input

Hardware scan code. A keyboard-generated value that identifies the keyboard event. This is the raw scan code, not the translated scan code.

usch (USHORT) - Input

Character code. The character value translation of the keyboard event resulting from the current code page that would apply if the CTRL or ALT keys were not depressed.

usvk (USHORT) - Input

Virtual key codes. A virtual key value translation of the keyboard event resulting from the virtual key code table. The low-order byte contains the vk value, and the high-order byte is always set to zero by the standard translate table. This value applies if fsflags does not contain KC_VIRTUALKEY.

Returns

rc (BOOL) - returns

Processed indicator.

TRUE

Message processed

FALSE

Message ignored.

Remarks

This message is posted to the queue associated with the window that has the focus.

The set of keys that causes a WM_CHAR message is device-dependent.

When this message is processed, precedence should normally be given to a valid virtual key if there is one contained in the message.

There are several instances when a window procedure may receive this message with the KC_KEYUP bit set, although it did not receive this message for the down transition of the key.

For example,

• The down transition of the key is translated by the function WinTranslateAccel, into a WM_COMMAND, WM_SYSCOMMAND, WM_HELP, or a WM_NULL message.

• The key down causes the input focus to change (tab to another window, dismiss a dialog, exit a program, and so on).

• Some other event happens that changes the focus between the time that the key is pressed down and the time that it is released.

Applications should normally only process WM_CHAR messages that do not have the KC_KEYUP bit set.

Except for the special instance where the LONEKEY flag is set on an accelerator key definition, all translations are done on the down stroke of the character.

When the current character is a double-byte character then param2 contains both bytes of the double-byte character. These bytes are in the order CHAR1FROMMP, CHAR2FROMMP. When the current character is a single-byte character, CHAR2FROMMP contains 0.

Default Processing

The default window procedure sends the message to the owner window if it exists, otherwise it takes no action on this message other than to set rc to FALSE.

Related Messages

• WM_CHAR (Default Dialogs)
• WM_CHAR (in Entry Fields)
• WM_CHAR (in Frame Controls)
• WM_CHAR (in List Boxes)
• WM_CHAR (in Multiline Entry Fields)

Examples

This example uses the CHARMSG macro to process a WM_CHAR message. It first uses the macro to determine if a key was released. It then uses the macro to generate a switch statement based on the character received.

MRESULT CALLBACK GenericWndProc(hwnd, usMessage, mp1, mp2)

HWND   hwnd;
USHORT usMessage;
MPARAM mp1;
MPARAM mp2;
{

    switch (usMessage) {
    case WM_CHAR:
        if (CHARMSG(&usMessage)->fs & KC_KEYUP) {
            switch (CHARMSG(&usMessage)->chr) {