000 Русский. |
English. |
001 Yet Another GetKey v0.07 для REXX. |
Yet Another GetKey v0.07 for REXX. |
002 Оглавление. 1. Введение 2. Установка, использование и удаление 3. Функции 3.1. yaGetKey 3.2. yaGetKeyDrop 3.3. yaGetKeyLoad 3.4. yaGetKeyVer 3.5. Пример 4. Замечания 5. Об авторах 6. Заявление об авторских правах |
Contents. 1. Introduction 2. How Install, Use and Remove 3. Functions 3.1. yaGetKey 3.2. yaGetKeyDrop 3.3. yaGetKeyLoad 3.4. yaGetKeyVer 3.5. Example 4. Some Notes 5. About Authors 6. Full Copyright Statement |
003 1. Введение. Библиотека Yet Another GetKey для REXX предоставляет дополнительную функцию yaGetKey, работающую аналогично функции SysGetKey из стандартной библиотеки RexxUtil. В отличие от SysGetKey, двухбайтовые сканкоды, порождаемые нажатиями некоторых клавиш, функция yaGetKey сразу возвращает в виде двухбайтовых строк. |
1. Introduction. The "Yet Another GetKey for REXX" library provides the additional yaGetKey function. It operates similar to the SysGetKey function from standard RexxUtil library. But the yaGetKey function returns a scan-code as the double-byte string if a keystroke generates the double-byte scancode. |
004 Потребность в новой функции возникла потому, что SysGetKey, считывая данные о нажатии клавиш из буфера клавиатуры, возвращает их для дальнейшей обработки в виде одиночных байтов. Двухбайтовые сканкоды, формируемые после нажатия функциональных клавиш, клавиш расширенной функциональности и некоторых комбинаций клавиш, тоже возвращаются побайтно, что требует повторного вызова SysGetKey после получения первого байта сканкода. Признаком начала сканкода считается получение байта с шестнадцатиричным значением "00"x или "E0"x. |
This function is necessary because the SysGetKey function returns the keystroke data from the keyboard buffer as single bytes. Double-byte scancodes are returned byte-by-byte, too. In this case hexadecimal "00"x or "E0"x values identify the first byte of the double-byte scancode. The second byte will be returned by the repeated function call. |
005 Такое решение серьёзно ограничивает использование существующей реализации SysGetKey для языков ввода, использующих кириллицу, для греческого и некоторых других языков, поскольку один из символов алфавита этих языков кодируется шестнадцатиричным значением "E0"x в соответствии с применяемой кодовой страницей. Например, для русского языка - это строчная буква кириллицы "р" в кодовой странице CP866, для болгарского - прописная буква кириллицы "Я" в кодовой странице CP855, для греческого - маленькая греческая буква "зета" в кодовой странице CP869 и так далее. Поэтому, получив от SysGetKey байт со значением "E0"x, невозможно понять требуется ли повторный вызов функции, потому что полученный байт может оказаться как отдельным символом национального алфавита, так и первым байтом сканкода. |
But some languages use the code pages in which one of the letters of the alphabet is coded as "E0"x value, too. For example, it is CYRILLIC SMALL LETTER ER in Russian (CP866), CYRILLIC CAPITAL LETTER YA in Bulgarian (CP855), GREEK SMALL LETTER ZETA in Greek (CP869) and another. In this case if the SysGetKey function returns "E0"x value you can not identify it as the character of the national alphabet or as the first byte of the double-byte scancode. |
006 Дополнительно функция yaGetKey позволяет проверить состояние переключателей Caps Lock, Num Lock, Scroll Lock и Insert во время нажатия клавиши, а также какие управляющие клавиши (Alt, Ctrl, Shift) были использованы в комбинации с нажатой клавишей. |
Additionally the yaGetKey function allows you to check the Caps Lock, Num Lock, Scroll Lock and Insert status and the use of Alt, Ctrl and Shift keys. |
007 2. Установка, использование и удаление. Дистрибутивный пакет Yet Another GetKey для REXX представляет собой архивный файл с именем yaGetKeyNNN.zip, где NNN - номер версии. |
2. How Install, Use and Remove. The Yet Another GetKey for REXX distribution package is the archive file named yaGetKeyNNN.zip, where NNN is the version number. |
008 Установка
|
How install
|
009
|
|
010
|
|
011
|
|
012
|
|
013
|
|
014
|
|
015 Использование функций
|
How use
|
call RxFuncAdd 'yaGetKeyLoad','yaGetKey','yaGetKeyLoad' call yaGetKeyLoad |
|
016
|
|
017
|
|
018 Удаление
|
How remove
|
019
|
|
020
|
|
021 3. Функции. |
3. Functions. |
022 3.1. yaGetKey Считывает и возвращает информацию о нажатой клавише из буфера клавиатуры. Если буфер клавиатуры пуст, то ожидает нажатия клавиши. Время ожидания нажатия клавиши можно ограничить указанием интервала. В отличие от SysGetKey не требует повторного вызова для получения сканкода. |
3.1. yaGetKey Reads and returns the keystroke data from the keyboard buffer. If the keyboard buffer is empty, yaGetKey waits until a key is pressed. Wait time can be restricted. Unlike the SysGetKey function, yaGetKey does not require a repeated call for reading the second byte of the scancode. |
023 Синтаксис >---yaGetKey(-+--------------+-)--->< | | +-time-+-------+ | | +-,stem-+ |
Syntax >---yaGetKey(-+--------------+-)--->< | | +-time-+-------+ | | +-,stem-+ |
024 Параметры
|
Parameters
|
025
|
|
026
|
|
027 Если параметр stem задан, то дополнительная информация о нажатой клавише помещается в элемент кортежа со следующим составным именем: |
If the stem is specified, the function stores the additional information about the keystroke in the stem: |
028
|
|
029
|
|
030
|
|
031 Функция также заполняет указанный кортеж информацией о состоянии переключателей в момент нажатия и об использованных в комбинации управляющих клавишах, присваивая значение 0 или 1 элементам кортежа со следующими составными именами: |
Also the function stores the information about additional environment of the keystroke assigning 0 or 1 value to stem elements named as: |
032
|
|
033
|
|
034
|
|
035
|
|
036
|
|
037
|
|
038
|
|
039
|
|
040
|
|
041
|
|
042
|
|
043
|
|
044
|
|
045
|
|
046
|
|
047
|
|
048 При возникновении ошибки значения элементов кортежа не изменяются. |
The stem does not change if an error occured. |
049 Возвращаемое значение Тип и размерность возвращаемого значения зависит от обрабатываемого события: |
Return Value The type and length of the return value depends on the keyboard events: |
050
|
|
051
|
|
052
|
|
053 Обработка ошибок Специальная переменная KBDERRNO может принимать одно из следующих значений: |
Errors The function stores the following values in the REXX special variable, KBDERRNO: |
054
|
|
055
|
|
056
|
|
057
|
|
058
|
|
059 Ограничения применения связаны с особенностями реализации и описываются в разделе 4. Замечания. |
In details restrictions are described in the section 4. Some notes. |
060 3.2. yaGetKeyDrop Сбрасывает регистрацию всех функций библиотеки, что делает их недоступными для использования в текущей сессии. |
3.2. yaGetKeyDrop Drops registration of the library function set. All functions will become unavailable for the current session. |
061 Синтаксис >---yaGetKeyDrop()--->< |
Syntax >---yaGetKeyDrop()--->< |
062 Параметры Отсутствуют. |
Parameters None. |
063 Возвращаемое значение Пустая строка. |
Return Value Empty string. |
064 Обработка ошибок Значение специальной переменной KBDERRNO не изменяется. |
Errors The value of the KBDERRNO special variable does not change. |
065 3.3. yaGetKeyLoad Регистрирует все функции библиотеки, что делает их доступными для использования в текущей сессии. |
3.3. yaGetKeyLoad Registers the library function set. All functions will become available for the current session. |
066 Синтаксис >---yaGetKeyLoad()--->< |
Syntax >---yaGetKeyLoad()--->< |
067 Параметры Отсутствуют. |
Parameters None. |
068 Возвращаемое значение Пустая строка. |
Return Value Empty string. |
069 Обработка ошибок Значение специальной переменной KBDERRNO не изменяется. |
Errors The value of the KBDERRNO special variable does not change. |
070 3.4. yaGetKeyVer Возвращает версию и прочую информацию о библиотеке. |
3.4. yaGetKeyVer Returns the library version and another information. |
071 Синтаксис >---yaGetKeyVer(-+------+-)--->< | | +-stem-+ |
Syntax >---yaGetKeyVer(-+------+-)--->< | | +-stem-+ |
072 Параметры
|
Parameters
|
073 Если параметр stem задан, то функция заполняет указанный кортеж дополнительной информацией о библиотеке, присваивая соответствующие значения элементам кортежа со следующими составными именами: |
If the stem is specified, the function stores the additional information about the library in the stem. The function assigns appropriate values to stem elements named as: |
074
|
|
075
|
|
076
|
|
077
|
|
078 Возвращаемое значение Строка с номером версии библиотеки. |
Return Value The string containing the version information. |
079 Обработка ошибок Значение специальной переменной KBDERRNO не изменяется. |
Errors The value of the KBDERRNO special variable does not change. |
080 3.5. Пример (отсутствует в HTML-версии, смотри INF-версию) |
3.5. Example (remove from HTML document, see INF document) |
081 4. Замечания. Об особенностях реализации Функция yaGetKey основана на функции API KbdCharIn. Поэтому функция yaGetKey возвращает значения только после нажатия тех клавиш, которые в состоянии обработать функция KbdCharIn. |
4. Some Notes. About features of implementation The yaGetKey function is based on the KbdCharIn function. Therefore the yaGetKey function returns values as keystrokes that can be produced by the KbdCharIn function. |
082 Двухбайтовые сканкоды функция yaGetKey возвращает только после нажатия тех клавиш, для которых установлен бит 1 в поле fbStatus структуры KBDKEYINFO, за исключением двух случаев. Поскольку KbdCharIn особым образом обрабатывает нажатия клавиш Enter и Slash (/) на дополнительной цифровой клавиатуре (устанавливает бит 1 в поле fbStatus, но признак сканкода 0xE0 помещает в поле chScan, а в поле chChar помещает оттранслированный символ, а не наоборот), то для этих клавиш функция yaGetKey возвращает однобайтовый символ, полученный из поля chChar, несмотря на установленный бит 1 в поле fbStatus. |
The yaGetKey function returns double-byte scancode only for those keystrokes in which the bit 1 is established in the fbStatus field of KBDKEYINFO structure except two cases. Since KbdCharIn processes the Enter and Slash (/) keystrokes on the additional digital keyboard in a special way (establishes bit 1 in the fbStatus field, but the 0xE0 value puts to the chScan field, and translated character puts to chChar field, and not vice versa), then the yaGetKey function returns the one-byte character (the chChar field) despite the established bit 1 in the fbStatus field for these keys. |
083 О VirtualBox Функция yaGetKey может вернуть недостоверную информацию о состоянии переключателей, если время ожидания нажатия клавиши было ограничено, а возврат из функции произошёл в результате истечения таймаута или изменения состояния переключателей. Это проблемы VirtualBox. |
About VirtualBox If the wait time is restricted and the timeout expired or the switches status changed then the yaGetKey function can return the invalid switches status. It is a VirtualBox problem. |
084 О самостоятельной компиляции Каталог .\SOURCE дистрибутивного пакета содержит всё необходимое для самостоятельной компиляции файлов программ и документации средствами Open Watcom C Compiler v1.9:
|
About unaided compiling The .\SOURCE directory of the distribution package contains everything needed for unaided compiling of program files and documents by tools of Open Watcom C Compiler v1.9:
|
085 Для самостоятельной компиляции требуется:
|
Getting Started:
|
086 5. Об авторах
|
5. About authors
|
087 6. Заявление об авторских правах Copyright (c) 2015 VicTor Smirnoff Данная лицензия разрешает лицам, получившим копию данного программного обеспечения и сопутствующей документации (в дальнейшем именуемыми "Программное Обеспечение"), безвозмездно использовать Программное Обеспечение без ограничений, включая неограниченное право на использование, копирование, изменение, добавление, публикацию, распространение, сублицензирование и/или продажу копий Программного Обеспечения, а также лицам, которым предоставляется данное Программное Обеспечение, при соблюдении следующих условий: |
6. Full Copyright Statement Copyright (c) 2015 VicTor Smirnoff Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: |
088 Указанное выше уведомление об авторском праве и данные условия должны быть включены во все копии или значимые части данного Программного Обеспечения. |
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. |
089 ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ. |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |