Using the WM_VKEYTOITEM Message Correctly

• Microsoft Windows Software Development Kit (SDK) versions 3.1
• Microsoft Win32 Application Programming Interface (API) included with:

      - Microsoft Windows NT versions 3.5 and 3.51
      - Microsoft Windows 95 version 4.0
  

SUMMARY

The WM_VKEYTOITEM message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_KEYDOWN message. The return value from this message 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.

This is true only for certain keys such as the UP ARROW (VK_UP), DOWN ARROW (VK_DOWN), PAGE DOWN (VK_NEXT) and PAGE UP (VK_PREVIOUS) keys. All other keys are handled in the normal way by the list box, regardless of the return value from the WM_VKEYTOITEM message.

MORE INFORMATION

The documentation for the WM_VKEYTOITEM message indicates that the owner of a list box control can trap the WM_VKEYTOITEM message that is generated in response to a WM_KEYDOWN message and return -2 if the application does not want the default list box window procedure to take further action.

This is valid only for keys that are not translated into a character by the list box control in Windows. 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 keydown, the list box ignores the return value (it will go ahead and do the default processing for that character).

WM_KEYDOWN messages generated by keys such as VK_UP (UP ARROW), VK_DOWN (DOWN ARROW), VK_NEXT (PAGE DOWN) and VK_PREVIOUS (PAGE UP) are not translated to WM_CHAR messages. In such cases, trapping the WM_VKEYTOITEM message and returning a -2 prevents the list box from doing the default processing for that key.

For example, if an application traps the DOWN ARROW key and does some nondefault processing (such as moving the selection to the item two indexes below the currently selected item) and then returns -2, the list box control will not do any more processing with this message.

Alternatively, if the application trapped the "A" key, does some nondefault processing, and returns -2, the list box code will still do the default processing. The list box will select an item in the list box that starts with an "A" (if one is present).

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

NOTE: This discussion is for regular list boxes that are created with the LBS_WANTKEYBOARDINPUT style. If the list box is owner draw, the application must process the WM_CHARTOITEM message. For more information on the WM_CHARTOITEM message, refer to the SDK documentation.