WM_VKEYTOITEM message

Sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_KEYDOWN message.

WM_VKEYTOITEM

    WPARAM wParam;
    LPARAM lParam; 

Parameters

wParam

The LOWORD specifies the virtual-key code of the key the user pressed. The HIWORD specifies the current position of the caret.

lParam

Handle to the list box.

Return value

The return value specifies the action that the application performed in response to the message. A return value of -2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. (See Remarks.) A return value of -1 indicates that the list box should perform the default action in response to the keystroke. A return value of 0 or greater specifies the index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the specified item.

Remarks

A return value of -2 is valid only for keys that are not translated into characters by the list box control. If the WM_KEYDOWN message translates to a WM_CHAR message and the application processes the WM_VKEYTOITEM message generated as a result of the key press, the list box ignores the return value and does the default processing for that character). WM_KEYDOWN messages generated by keys such as VK_UP, VK_DOWN, VK_NEXT, and VK_PREVIOUS are not translated to WM_CHAR messages. In such cases, trapping the WM_VKEYTOITEM message and returning -2 prevents the list box from doing the default processing for that key.

To trap keys that generate a char message and do special processing, the application must subclass the list box, trap both the WM_KEYDOWN and WM_CHAR messages, and process the messages appropriately in the subclass procedure.

The preceding remarks apply to regular list boxes that are created with the LBS_WANTKEYBOARDINPUT style. If the list box is owner-drawn, the application must process the WM_CHARTOITEM message.

The DefWindowProc function returns -1.

If a dialog box procedure handles this message, it should cast the desired return value to a BOOL and return the value directly. The DWL_MSGRESULT value set by the SetWindowLong function is ignored.

Requirements

Requirement Value
Minimum supported client
Windows Vista [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]
Header
Winuser.h (include Windows.h)

See also

Reference

WM_CHARTOITEM

Other Resources

HIWORD

LOWORD

WM_KEYDOWN