A windows application learns of keyboard events the same way it learns about mouse events: through messages. a program receives a message whenever a key is pressed or released. if you want to know when the page up or page down key is pressed so that your application can react accordingly, you process wm_keydown messages and check for key codes identifying the page up or page down key. if you'd rather know when a key is released, you process wm_keyup messages instead. for keys that produce printable characters, you can ignore key-down and key-up messages and process wm_char messages that denote characters typed at the keyboard. relying on wm_char messages instead of wm_keyup/down messages simplifies character processing by enabling windows to factor in events and circumstances surrounding the keystroke, such as whether the shift key is pressed, whether caps lock is on or off, and differences in keyboard layouts.

the input focus
like the mouse, the keyboard is a global hardware resource shared by all applications. windows decides which window to send mouse messages to by identifying the window under the cursor. keyboard messages are targeted differently. windows directs keyboard messages to the window with the "input focus." at any given time, no more than one window has the input focus. often the window with the input focus is the main window of the active application. however, the input focus might belong to a child of the main window or to a control in a dialog box. regardless, windows always sends keyboard messages to the window that owns the focus. if your application's window has no child windows, keyboard processing is relatively straightforward: when your application is active, its main window receives keyboard messages. if the focus shifts to a child window, keyboard messages go to the child window instead and the flow of messages to the main window ceases.

windows notifies a window that it is about to receive or lose the input focus with wm_setfocus and wm_killfocus messages, which mfc programs process as shown here:

// in cmainwindow's message map
on_wm_setfocus ()
on_wm_killfocus ()

  
void cmainwindow::onsetfocus (cwnd* poldwnd)
{
    // cmainwindow now has the input focus. poldwnd
    // identifies the window that lost the input focus.
    // poldwnd will be null if the window that lost the
    // focus was created by another thread.
}

void cmainwindow::onkillfocus (cwnd* pnewwnd)
{
    // cmainwindow is about to lose the input focus.
    // pnewwnd identifies the window that will receive
    // the input focus. pnewwnd will be null if the
    // window that's receiving the focus is owned by
    // another thread.
}

an application can shift the input focus to another window with cwnd::setfocus:

pwnd->setfocus ();

or it can use the static cwnd::getfocus function to find out who currently has the input focus:

cwnd* pfocuswnd = cwnd::getfocus ();

keystroke messages
windows reports key presses and releases by sending wm_keydown and wm_keyup messages to the window with the input focus. these messages are commonly referred to as keystroke messages. when a key is pressed, the window with the input focus receives a wm_keydown message with a virtual key code identifying the key. when the key is released, the window receives a wm_keyup message. if other keys are pressed and released while the key is held down, the resultant wm_keydown and wm_keyup messages separate the wm_keydown and wm_keyup messages generated by the key that's held down. windows reports keyboard events as they happen in the order in which they happen, so by examining the stream of keystroke messages coming into your application, you can tell exactly what was typed and when.

all keys but two generate wm_keydown and wm_keyup messages. the two exceptions are alt and f10, which are "system" keys that have a special meaning to windows. when either of these keys is pressed and released, a window receives a wm_syskeydown message followed by a wm_syskeyup message. if other keys are pressed while the alt key is held down, they, too, generate wm_syskeydown and wm_syskeyup messages instead of wm_keydown and wm_keyup messages. pressing f10 puts windows in a special modal state that treats the next keypress as a menu shortcut. pressing f10 followed by the f key, for example, pulls down the file menu in most applications.

an application processes keystroke messages by providing message-map entries and message handling functions for the messages it is interested in. wm_keydown, wm_keyup, wm_syskeydown, and wm_syskeyup messages are processed by a class's onkeydown, onkeyup, onsyskeydown, and onsyskeyup member functions, respectively. the corresponding message-map macros are on_wm_keydown, on_wm_keyup, on_wm_syskeydown, and on_wm_syskeyup. when activated, a keystroke handler receives a wealth of information about the keystroke, including a code identifying the key that was pressed or released.

keystroke message handlers are prototyped as follows:

afx_msg void onmsgname (uint nchar, uint nrepcnt, uint nflags)

nchar is the virtual key code of the key that was pressed or released. nrepcnt is the repeat count—the number of keystrokes encoded in the message. nrepcnt is usually equal to 1 for wm_keydown or wm_syskeydown messages and is always 1 for wm_keyup or wm_syskeyup messages. if key-down messages arrive so fast that your application can't keep up, windows combines two or more wm_keydown or wm_syskeydown messages into one and increases the repeat count accordingly. most programs ignore the repeat count and treat combinatorial key-down messages (messages in which nrepcnt is greater than 1) as a single keystroke to prevent overruns—situations in which a program continues to scroll or otherwise respond to keystroke messages after the user's finger has released the key. in contrast to the pc's keyboard bios, which buffers incoming keystrokes and reports each one individually, the windows method of reporting consecutive presses of the same key to your application provides a built-in hedge against keyboard overruns.

the nflags parameter contains the key's scan code and zero or more of the bit flags described here:

bit(s) meaning description
0_7 oem scan code 8-bit oem scan code
8 extended key flag 1 if the key is an extended key, 0 if it is not
9_12 reserved n/a
13 context code 1 if the alt key is pressed, 0 if it is not
14 previous key state 1 if the key was previously pressed, 0 if it was up
15 transition state 0 if the key is being pressed, 1 if it is being released

message virtual key code previous key state
wm_keydown vk_shift 0
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keydown vk_shift 1
wm_keyup vk_shift 1

if you want your application to disregard keystrokes generated as a result of typematic action, simply have it ignore wm_keydown messages with previous key state values equal to 1. the transition state value is 0 for wm_keydown and wm_syskeydown messages and 1 for wm_keyup and wm_syskeyup messages. finally, the context code indicates whether the alt key was pressed when the message was generated. with certain (usually unimportant) exceptions, the code is 1 for wm_syskeydown and wm_syskeyup messages and 0 for wm_keydown and wm_keyup messages.

in general, applications shouldn't process wm_syskeydown and wm_syskeyup messages; they should let windows process them instead. if these messages don't eventually find their way to ::defwindowproc, system keyboard commands such as alt-tab and alt-esc will stop working. windows puts a tremendous amount of power in your hands by routing all mouse and keyboard messages through your application first, even though many of these messages are meaningful first and foremost to the operating system. as with nonclient-area mouse messages, the improper handling of system keystroke messages—in particular, the failure to pass these messages on to the operating system—can result in all sorts of quirky behavior.

virtual key codes
the most important value by far that gets passed to a keystroke message handler is the nchar value identifying the key that was pressed or released. windows identifies keys with the virtual key codes shown in the table below so that applications won't have to rely on hardcoded values or oem scan codes that might differ from keyboard to keyboard.

conspicuously missing from this table are virtual key codes for the letters a through z and a through z and for the numerals 0 through 9. the virtual key codes for these keys are the same as the corresponding characters' ansi codes: 0x41 through 0x5a for a through z, 0x61 through 0x7a for a through z, and 0x30 through 0x39 for 0 through 9.

virtual key codes

virtual key code(s) corresponding key(s)
vk_f1_vk_f12 function keys f1_f12
vk_numpad0_vk_numpad9 numeric keypad 0_9 with num lock on
vk_cancel ctrl-break
vk_return enter
vk_back backspace
vk_tab tab
vk_clear numeric keypad 5 with num lock off
vk_shift shift
vk_control ctrl
vk_menu alt
vk_pause pause
vk_escape esc
vk_space spacebar
vk_prior page up and pgup
vk_next page down and pgdn
vk_end end
vk_home home
vk_left left arrow
vk_up up arrow
vk_right right arrow
vk_down down arrow
vk_snapshot print screen
vk_insert insert and ins
vk_delete delete and del
vk_multiply numeric keypad *
vk_add numeric keypad +
vk_subtract numeric keypad -
vk_decimal numeric keypad .
vk_divide numeric keypad /
vk_capital caps lock
vk_numlock num lock
vk_scroll scroll lock
vk_lwin left windows key  
vk_rwin right windows key  
vk_apps menu key ()  

shift states and toggles
when you write handlers for wm_keydown, wm_keyup, wm_syskeydown, or wm_syskeyup messages, you might need to know whether the shift, ctrl, or alt key is held down before deciding what to do. information about the shift states of the shift and ctrl keys is not encoded in keyboard messages as it is in mouse messages, so windows provides the ::getkeystate function. given a virtual key code, ::getkeystate reports whether the key in question is held down. the expression

::getkeystate (vk_shift)

::getkeystate (vk_control)

returns a negative value if the ctrl key is held down. thus, the bracketed statements in the following code fragment taken from an onkeydown handler are executed only when ctrl-left (the left arrow key in combination with the ctrl key) is pressed:

if ((nchar == vk_left) && (::getkeystate (vk_control) < 0)) {
  
}

to inquire about the alt key, you can call ::getkeystate with a vk_menu parameter or simply check the context code bit in the nflags parameter. usually even that amount of effort isn't necessary because if the alt key is pressed, your window will receive a wm_syskeydown or wm_syskeyup message instead of a wm_keydown or wm_keyup message. in other words, the message id generally tells you all you need to know about the alt key. as a bonus, you can use the identifiers vk_lbutton, vk_mbutton, and vk_rbutton in conjunction with ::getkeystate to determine if any of the mouse buttons is held down.

an application can also use ::getkeystate to determine whether num lock, caps lock, and scroll lock are on or off. while the high bit of the return code indicates whether a key is currently pressed (yielding a negative number when the high bit is 1), the low bit—bit 0—indicates the state of the toggle. the expression

::getkeystate (vk_numlock) & 0x01

evaluates to nonzero if num lock is on and evaluates to 0 if it is not. the same technique works for the vk_capital (caps lock) and vk_scroll (scroll lock) keys. it's important to mask off all but the lowest bit of the return code before testing because the high bit still indicates whether the key itself is up or down.

in all cases, ::getkeystate reports the state of the key or the mouse button at the time the keyboard message was generated, not at the precise moment that the function is called. this is a feature, not a bug, because it means you don't have to worry about a key being released before your message handler gets around to inquiring about the key state. the ::getkeystate function should never be called outside a keyboard message handler because the information it returns is valid only after a keyboard message has been retrieved from the message queue. if you really need to know the current state of a key or a mouse button, or if you want to check a key or a mouse button outside a keyboard message handler, use ::getasynckeystate instead.

character messages
one problem you'll encounter if you rely exclusively on key-up and key-down messages for keyboard input is shown in the following scenario. suppose you're writing a text editor that turns messages reporting presses of the character keys into characters on the screen. the a key is pressed, and a wm_keydown message arrives with a virtual key code equal to 0x41. before you put an a on the screen, you call ::getkeystate to determine whether the shift key is held down. if it is, you output an uppercase "a"; otherwise, you output a lowercase "a." so far, so good. but what if caps lock is enabled too? caps lock undoes the effect of the shift key, converting "a" to "a" and "a" to "a." now you have four different permutations of the letter a to consider:

virtual key code vk_shift caps lock result
0x41 no off a
0x41 yes off a
0x41 no on a
0x41 yes on a

that's why windows provides the ::translatemessage api function. ::translatemessage converts keystroke messages involving character keys into wm_char messages.the message loop provided by mfc calls ::translatemessage for you, so in an mfc application you don't have to do anything special to translate keystroke messages into wm_char messages. when you use wm_char messages for keyboard input, you needn't worry about virtual key codes and shift states because each wm_char message includes a character code that maps directly to a symbol in the ansi character set (windows 98) or unicode character set (windows 2000). assuming that caps lock is not turned on, pressing shift-a produces the following sequence of messages:

message virtual key code character code
wm_keydown vk_shift  
wm_keydown 0x41  
wm_char  0x41 ("a")
wm_keyup 0x41  
wm_keyup vk_shift  

now you can safely ignore key-up and key-down messages because everything you need to know about the keystroke is encoded in the wm_char message. if the alt key had been held down while shift-a was pressed, your application would have received a wm_syschar message instead:

message virtual key code character code
wm_syskeydown vk_shift  
wm_syskeydown 0x41  
wm_syschar  0x41 ("a")
wm_syskeyup 0x41  
wm_syskeyup vk_shift  

since alt-key combinations are generally used for special purposes, most applications ignore wm_syschar messages and process wm_char messages instead.

figure 3-6 shows the characters in the ansi character set. since ansi codes are only 8 bits wide, there are only 256 possible characters. unicode uses 16-bit character codes, expanding the possible character count to 65,536. fortunately, the first 256 characters in the unicode character set and the 256 characters in the ansi character set are identical. thus, code like this:

case _t (`a'):
case _t (`a'):

works fine with either character set.

figure 3-6. the ansi character set.

an on_wm_char entry in a class's message map routes wm_char messages to the member function onchar, which is prototyped as follows:

afx_msg void onchar (uint nchar, uint nrepcnt, uint nflags)

nrepcnt and nflags have the same meanings that they have in keystroke messages. nchar holds an ansi or unicode character code. the following code fragment traps presses of the letter keys, the enter key, and the backspace key, all of which produce wm_char messages:

// in cmainwindow's message map
on_wm_char ()

  
void cmainwindow::onchar (uint nchar, uint nrepcnt, uint nflags)

{
    if (((nchar >= _t (`a')) && (nchar <= _t (`z'))) ||
        ((nchar >= _t (`a')) && (nchar <= _t (`z')))) {
        // display the character
    }
    else if (nchar == vk_return) {
        // process the enter key
    }
    else if (nchar == vk_back) {
        // process the backspace key
    }
}

if it's unclear to you whether a particular key produces a wm_char message, there's an easy way to find out. simply run the visualkb application that comes with this book and press the key. if the key produces a wm_char message, the message will appear in visualkb's window.

dead-key messages
there are two keyboard messages i didn't mention because they are rarely used by application programs. many international keyboard drivers allow users to enter a character accented with a diacritic by typing a "dead key" representing the diacritic and then typing the character itself. ::translatemessage translates wm_keyup messages corresponding to dead keys into wm_deadchar messages, and it translates wm_syskeyup messages generated by dead keys into wm_sysdeadchar messages. windows provides the logic that combines these messages with character messages to produce accented characters, so dead-key messages are usually passed on for default processing. some applications go the extra mile by intercepting dead-key messages and displaying the corresponding diacritics. the keystroke following the dead key then replaces the diacritic with an accented character. this provides visual feedback to the user and prevents dead keys from having to be typed "blind."

you can process dead-key messages in an mfc application by including an on_wm_deadchar or on_wm_sysdeadchar entry in a message map and supplying handling functions named ondeadchar and onsysdeadchar. you'll find descriptions of these functions in the mfc documentation.

the caret
the flashing vertical bar that word processors and other windows applications use to mark the point where the next character will be inserted is called the caret. the caret serves the same purpose in a windows application that the blinking underscore cursor does in a character-mode application. mfc's cwnd class provides the seven caret-handling functions shown below. the one essential function missing from this table, ::destroycaret, must be called directly from the windows api because there is no mfc equivalent.

cwnd caret handling functions

function description
createcaret creates a caret from a bitmap
createsolidcaret creates a solid line caret or a block caret
creategraycaret creates a gray line caret or a block caret
getcaretpos retrieves the current caret position
setcaretpos sets the caret position
showcaret displays the caret
hidecaret hides the caret

a window that uses the caret should "create" a caret when it receives the input focus and should "destroy" the caret when it loses the input focus. a caret is created with createcaret, createsolidcaret, or creategraycaret and is destroyed with ::destroycaret.

once a caret is created, it isn't visible until showcaret is called to make it visible. the caret can be hidden again with a call to hidecaret. if calls to hidecaret are nested—that is, if hidecaret is called twice or more in succession—showcaret must be called an equal number of times to make the caret visible again.

when you draw in the area of a window that contains the caret outside an onpaint handler, you should hide the caret to avoid corrupting the display. you can redisplay the caret after drawing is complete. you don't need to hide and redisplay the caret in an onpaint handlerbecause ::beginpaint and ::endpaint do that for you.

a program moves the caret by calling setcaretpos. windows doesn't move the caret for you; it's your program's job to process incoming keyboard messages (and perhaps mouse messages) and manipulate the caret accordingly. getcaretpos can be called to retrieve the caret's current position.

as you know, a window receives a wm_setfocus message when it receives the input focus and a wm_killfocus message when it loses the input focus. the following wm_setfocus handler creates a caret, positions it, and displays it when a window gains the input focus:

void cmainwindow::onsetfocus (cwnd* pwnd)
{
    createsolidcaret (2, m_cychar);
    setcaretpos (m_ptcaretpos);
    showcaret ();
}

and this wm_killfocus handler saves the caret position and hides and destroys the caret when the input focus is lost:

void cmainwindow::onkillfocus (cwnd* pwnd)
{
    hidecaret ();
    m_ptcaretpos = getcaretpos ();
    ::destroycaret ();
}

in these examples, m_cychar holds the caret height and m_ptcaretpos holds the caret position. the caret position is saved when the focus is lost, and it is restored when the focus is regained. since only one window can have the input focus at a time and keyboard messages are directed to the window with the input focus, this approach to caret handling ensures that the window that "owns" the keyboard also owns the caret.

the caret-create functions serve two purposes: defining the look of the caret and claiming ownership of the caret. the caret is actually a bitmap, so you can customize its appearance by supplying a bitmap to cwnd::createcaret. but more often than not you'll find that the easier-to-use createsolidcaret function (it's easier to use because it doesn't require a bitmap) does the job nicely. createsolidcaret creates a solid block caret that, depending on how you shape it, can look like a rectangle, a horizontal or vertical line, or something in between. in the onsetfocus example above, the statement

createsolidcaret (2, m_cychar);

creates a vertical-line caret 2 pixels wide whose height equals the character height of the current font (m_cychar). this is the traditional way of creating a caret for use with a proportional font, although some programs key the width of the caret to the width of a window border. you can obtain the border width by calling ::getsystemmetrics with the value sm_cxborder. for fixed-pitch fonts, you might prefer to use a block caret whose width and height equal the width and height of one character, as in

createsolidcaret (m_cxchar, m_cychar);

a block caret doesn't make sense for a proportionally spaced font because of the varying character widths. cwnd's creategraycaret function works just as createsolidcaret does except that it creates a gray caret rather than a solid black caret. caret dimensions are expressed in logical units, so if you change the mapping mode before creating a caret, the dimensions you specify will be transformed accordingly.

as mentioned above, it's your job to move the caret. cwnd::setcaretpos repositions the caret, accepting a cpoint object that contains the x and y client-area coordinates of the new cursor position. positioning the caret in a string of text is fairly straightforward if you're using a fixed-pitch font because you can calculate a new x offset into the string by multiplying the character position by the character width. if the font is proportionally spaced, you'll have to do a little more work. mfc's cdc::gettextextent and cdc::gettabbedtextextent functions enable an application to determine the width, in logical units, of a string of characters rendered in a proportional font. (use gettabbedtextextent if the string contains tab characters.) given a character position n, you can compute the corresponding caret position by calling gettextextent or gettabbedtextextent to find the cumulative width of the first n characters. if the string "hello, world" is displayed at the position specified by a cpoint object named point and dc is a device context object, the following statements position the caret between the "w" and "o" in "world":

csize size = dc.gettextextent (_t ("hello, w"), 8);
setcaretpos (cpoint (point.x + size.cx, point.y));