Функция ToUnicode (winuser.h)

Статья
08/28/2023

Преобразует указанный код виртуальной клавиши и состояние клавиатуры в соответствующие символы Юникода.

Синтаксис

int ToUnicode(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags
);

Параметры

[in] wVirtKey

Тип: UINT

Код виртуального ключа для перевода. См . раздел Коды виртуальных ключей.

[in] wScanCode

Тип: UINT

Код аппаратного сканирования ключа для преобразования. Бит высокого порядка этого значения задается, если ключ находится вверх.

[in, optional] lpKeyState

Тип: const BYTE*

Указатель на 256-байтовой массив, содержащий текущее состояние клавиатуры. Каждый элемент (байт) в массиве содержит состояние одного ключа.

Если задан бит байта высокого порядка, ключ не работает. Низкий бит, если он задан, указывает, что ключ включен. В этой функции имеет значение только бит переключателя клавиши CAPS LOCK. Состояние переключателя клавиш NUM LOCK и SCROLL LOCK игнорируется. Дополнительные сведения см. в разделе GetKeyboardState .

[out] pwszBuff

Тип: LPWSTR

Буфер, который получает переведенные символы или символы в виде массива единиц кода UTF-16. Этот буфер может быть возвращен без завершения со значением NULL, даже если имя переменной предполагает, что он завершается null. Возвращаемое значение этого метода можно использовать, чтобы определить, сколько символов было записано.

[in] cchBuff

Тип: int

Размер (в символах) буфера, на который указывает параметр pwszBuff .

[in] wFlags

Тип: UINT

Поведение функции.

Если задан бит 0, меню активно. В этом режиме сочетания клавиш ALT+числовой клавиатуры не обрабатываются.

Если задан бит 2, состояние клавиатуры не изменяется (Windows 10 версии 1607 и более поздних версий).

Все остальные биты (до 31) зарезервированы.

Возвращаемое значение

Тип: int

Функция возвращает одно из следующих значений.

Возвращаемое значение	Описание
значение< 0	Указанный виртуальный ключ является символом мертвого ключа (диакритический или диакритический символ). Это значение возвращается независимо от раскладки клавиатуры, даже если несколько символов были введены и сохранены в состоянии клавиатуры. Если это возможно, даже при использовании раскладок клавиатуры в Юникоде функция записала в буфер, заданный pwszBuff, версию интервала символа недоставленной клавиши. Например, функция записывает символ ACUTE ACCENT (U+00B4), а не символ COMBINING ACUTE ACCENT (U+0301).
0	Указанная виртуальная клавиша не имеет перевода текущего состояния клавиатуры. В буфер, указанный pwszBuff, ничего не записано.
значение > 0	Одна или несколько единиц кода UTF-16 были записаны в буфер, указанный pwszBuff. Возвращаемый pwszBuff может содержать больше символов, чем указано в возвращаемом значении. В этом случае все дополнительные символы являются недопустимыми и должны игнорироваться.

Некоторые раскладки клавиатуры могут возвращать несколько символов и /или дополнительные символы в качестве суррогатных пар в pwszBuff. Если неактивный ключевой символ (диакритический или диакритический символ), хранящийся в раскладке клавиатуры, не может быть объединен с указанной виртуальной клавишей для формирования одного символа, то предыдущий введенный неактивный символ можно объединить с текущим символом.

Параметров, предоставленных функции ToUnicodeEx , может быть недостаточно для преобразования кода виртуальной клавиши, так как предыдущая неактивная клавиша хранится в раскладке клавиатуры.

Как правило, ToUnicode выполняет преобразование на основе кода виртуального ключа. Однако в некоторых случаях бит 15 параметра wScanCode можно использовать для различения нажатия клавиши и нажатия клавиши (например, для записи клавиш ALT+numpad).

Так как ToUnicode преобразует код виртуальной клавиши, он также изменяет состояние буфера клавиатуры в режиме ядра. Это изменение состояния влияет на неуявные ключи, лигатуры, alt+числовую клавиатуру и т. д. Это также может вызвать нежелательные побочные эффекты при использовании в сочетании с TranslateMessage (что также изменяет состояние буфера клавиатуры в режиме ядра).

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll