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

Статья
05/20/2023

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

Примечание

Этот метод может неправильно работать с некоторыми раскладками клавиатуры , которые могут создавать несколько символов (например, лигатуры) и (или) дополнительные символы Юникода при нажатии одной клавиши. Настоятельно рекомендуется использовать методы ToUnicode или ToUnicodeEx , которые правильно обрабатывают такие случаи.

Синтаксис

int ToAsciiEx(
  [in]           UINT       uVirtKey,
  [in]           UINT       uScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWORD     lpChar,
  [in]           UINT       uFlags,
  [in, optional] HKL        dwhkl
);

Параметры

[in] uVirtKey

Тип: UINT

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

[in] uScanCode

Тип: UINT

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

[in, optional] lpKeyState

Тип: const BYTE*

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

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

[out] lpChar

Тип: LPWORD

Указатель на буфер, который получает переведенный символ (или два символа, упакованные в одно значение WORD , где байт нижнего порядка содержит первый символ, а байт высокого порядка — второй символ).

[in] uFlags

Тип: UINT

Этот параметр должен иметь значение 1, если меню активно, в противном случае — ноль.

[in, optional] dwhkl

Тип: HKL

Входной идентификатор языкового стандарта, используемый для перевода кода. Этот параметр может быть любым идентификатором входного языкового стандарта, ранее возвращенным функцией LoadKeyboardLayout .

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

Тип: int

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

Возвращаемое значение	Описание
0	Указанная виртуальная клавиша не имеет перевода текущего состояния клавиатуры.
1	Один символ был скопирован в буфер.
2	В буфер были скопированы два символа. Обычно это происходит, когда символ недоставленной клавиши (акцентный или диакритический), хранящийся в раскладке клавиатуры, не может быть составлен с помощью указанной виртуальной клавиши для формирования одного символа.

Идентификатор языкового стандарта ввода является более широким понятием, чем раскладка клавиатуры, так как он также может охватывать преобразователь речи в текст, редактор метода ввода (IME) или любую другую форму ввода.

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

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

Хотя NUM LOCK является переключателем, влияющим на поведение клавиатуры, ToAsciiEx игнорирует параметр переключателя (низкий бит) lpKeyState (VK_NUMLOCK), так как только параметра uVirtKey достаточно, чтобы отличать клавиши перемещения курсора (VK_HOME, VK_INSERT и т. д.) от числовых клавиш (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9).

Требования


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