Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining


Called by the framework when the list box's parent window receives a WM_VKEYTOITEM message from the list box.

virtual int VKeyToItem(
   UINT nKey,
   UINT nIndex 


The virtual key code of the key the user pressed. For a list of of standard virtual key codes, see Winuser.h


The current position of the list-box caret.

Returns – 2 for no further action, – 1 for default action, or a nonnegative number to specify an index of a list box item on which to perform the default action for the keystroke.

The WM_VKEYTOITEM message is sent by the list box when it receives a WM_KEYDOWN message, but only if the list box meets both of the following:

You should never call this function yourself. Override this function to provide your own custom handling of keyboard messages.

You must return a value to tell the framework what action your override performed. 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. Before returning – 2, you could set the selection or move the caret or both. To set the selection, use SetCurSel or SetSel. To move the caret, use SetCaretIndex.

A return value of – 1 indicates that the list box should perform the default action in response to the keystroke.The default implementation returns – 1.

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 given item.

// CMyODListBox is my owner-drawn list box derived from CListBox. This 
// example moves the caret down one item on the down key and up one item 
// on the up key. The list box control was created with the following 
// code:
//   m_myODListBox.Create(
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
int CMyODListBox::VKeyToItem(UINT nKey, UINT nIndex)
   // On key up, move the caret up one item.
   if ((nKey == VK_UP) && (nIndex > 0))
   // On key down, move the caret down one item.
   else if ((nKey == VK_DOWN) && (nIndex < (UINT)GetCount()))

   // Do not perform any default processing.
   return -2;

Header: afxwin.h

Community Additions

© 2015 Microsoft