From 526bff2b1b7f2c597dfc8fdda7f667da7003663e Mon Sep 17 00:00:00 2001 From: michael Date: Sun, 9 Sep 2001 15:22:31 +0000 Subject: [PATCH] + Initial implementation --- docs/keyboard.tex | 309 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 docs/keyboard.tex diff --git a/docs/keyboard.tex b/docs/keyboard.tex new file mode 100644 index 0000000000..f825b1d48f --- /dev/null +++ b/docs/keyboard.tex @@ -0,0 +1,309 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% The Keyboard unit +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{The KEYBOARD unit} +\FPCexampledir{keybex} + +The \file{KeyBoard} unit implements a keyboard access layer which is system +independent. It can be used to poll the keyboard state and wait for certaine +events. + +\section{Constants, Type and variables } + +\subsection{Constants} + +The following constants define some error constants, which may be returned +by the keyboard functions. +\begin{verbatim} +errKbdBase = 1010; +errKbdInitError = errKbdBase + 0; +errKbdNotImplemented = errKbdBase + 1; +\end{verbatim} +The following constants denote special keyboard keys. The first constants +denote the function keys: +\begin{verbatim} +const + kbdF1 = $FF01; + kbdF2 = $FF02; + kbdF3 = $FF03; + kbdF4 = $FF04; + kbdF5 = $FF05; + kbdF6 = $FF06; + kbdF7 = $FF07; + kbdF8 = $FF08; + kbdF9 = $FF09; + kbdF10 = $FF0A; + kbdF11 = $FF0B; + kbdF12 = $FF0C; + kbdF13 = $FF0D; + kbdF14 = $FF0E; + kbdF15 = $FF0F; + kbdF16 = $FF10; + kbdF17 = $FF11; + kbdF18 = $FF12; + kbdF19 = $FF13; + kbdF20 = $FF14; +\end{verbatim} +Constants \$15 till \$1F are reserved for future function keys. The +following constants denote the curso movement keys: +\begin{verbatim} + kbdHome = $FF20; + kbdUp = $FF21; + kbdPgUp = $FF22; + kbdLeft = $FF23; + kbdMiddle = $FF24; + kbdRight = $FF25; + kbdEnd = $FF26; + kbdDown = $FF27; + kbdPgDn = $FF28; + + kbdInsert = $FF29; + kbdDelete = $FF2A; +\end{verbatim} +Constants \$2B till \$2F are reserved for future keypad key. +The following flags are also defined: +\begin{verbatim} + kbASCII = $00; + kbUniCode = $01; + kbFnKey = $02; + kbPhys = $03; + kbReleased = $04; +\end{verbatim} +They can be used to check And the following shift-state flags: +\begin{verbatim} + kbLeftShift = 1; + kbRightShift = 2; + kbShift = kbLeftShift or kbRightShift; + kbCtrl = 4; + kbAlt = 8; +\end{verbatim} +\subsection{Types} +The \var{TKeyEvent} type is the base type for all keyboard events: +\begin{verbatim} + TKeyEvent = Longint; +\end{verbatim} +The structure of a \var{TKeyEvent} is explained in \seet{keyevent}. +\begin{FPCltable}{lp}{Structure of \var{TKeyEvent}}{keyevent} +Bytes & Meaning \\ \hline +2 bytes & Depending on \var{flags} either the physical representation of a key + (under DOS scancode, ascii code pair), or the translated + ASCII/unicode character.\\ +1 byte & shift-state when this key was pressed (or shortly after) \\ +1 byte & \var{flags}, determining how to read the first two bytes \\ \hline. +\end{FPCltable} +The shift-state can be checked using the various shift-state constants, +and the flags in the last byte can be checked using one of the +kbASCII,kbUniCode,kbFnKey,kbPhys, kbReleased constants. + +If there are two keys returning the same char-code, there's no way to find +out which one was pressed (Gray+ and Simple+). If it needs to be known which +was pressed, the untranslated keycodes must be used, but these are system +dependent. System dependent constants may be defined to cover those, with +possibily having the same name (but different value). +\subsection{Variables} +The following variable contains any pending (i.e. not yet consumed) keyboard +event: +\begin +var + PendingKeyEvent : TKeyEvent; + +\section{Functions and Procedures} + +\begin{procedure}{DoneKeyboard} +\Declaration +Procedure DoneKeyboard +\Description +\var{DoneKeyboard} de-initializes the keyboard interface. +It clears up any allocated memory, or restores the console or terminal +the program was running in to its initial state. This function should +be called on program exit. Failing to do so may leave the terminal in +unusable state. Its exact action depends on the platform on which the +program is running. +\Errors +None. +\SeeAlso +\seep{InitKeyBoard} +\end{procedure} + +\begin{function}{GetKeyEvent} +\Declaration +function GetKeyEvent: TKeyEvent; +\Description +\var{GetKeyEvent} returns the last keyevent if one was stored in +\var{PendingKeyEvent}, or waits for one if none is available. +A non-blocking version is available in \seef{PollKeyEvent}. + +The returned key is encoded as a \var{TKeyEvent} type variable. +See the types section for a description of how the key is described. +\Errors +If no key became available, 0 is returned. +\SeeAlso +\seep{PutKeyEvent}, \seef{PollKeyEvent} +\end{function} + +\begin{function}{GetKeyEventChar} +\Declaration +function GetKeyEventChar(KeyEvent: TKeyEvent): Char; +\Description +\var{GetKeyEventChar} returns the charcode part of the given +\var{KeyEvent}, if it contains a translated keycode. +\Errors +None. +\SeeAlso +\seef{GetKeyEventUniCode}, +\seef{GetKeyEventShiftState}, +\seef{GetKeyEventFlags}, +\seef{GetKeyEventCode}, +\seef{GetKeyEvent} +\end{function} + +\begin{function}{GetKeyEventCode} +\Declaration +function GetKeyEventCode(KeyEvent: TKeyEvent): Word; +\Description +\var{GetKeyEventCode} returns the translated function keycode part of +the given KeyEvent, if it contains a translated function keycode. +\Errors +None. +\SeeAlso +\seef{GetKeyEventUniCode}, +\seef{GetKeyEventShiftState}, +\seef{GetKeyEventFlags}, +\seef{GetKeyEventChar}, +\seef{GetKeyEvent} +\end{function} + +\begin{function}{GetKeyEventFlags} +\Declaration +function GetKeyEventFlags(KeyEvent: TKeyEvent): Byte; +\Description +\var{GetKeyEventFlags} returns the flags part of the given +\var{KeyEvent}. +\Errors +None. +\SeeAlso +\seef{GetKeyEventUniCode}, +\seef{GetKeyEventShiftState}, +\seef{GetKeyEventCode}, +\seef{GetKeyEventChar}, +\seef{GetKeyEvent} +\end{function} + +\begin{function}{GetKeyEventShiftState} +\Declaration +function GetKeyEventShiftState(KeyEvent: TKeyEvent): Byte; +\Description +\var{GetKeyEventShiftState} returns the shift-state values of +the given \var{KeyEvent}. +\Errors +\SeeAlso +\seef{GetKeyEventUniCode}, +\seef{GetKeyEventFlags}, +\seef{GetKeyEventCode}, +\seef{GetKeyEventChar}, +\seef{GetKeyEvent} +\end{function} + +\begin{function}{GetKeyEventUniCode} +\Declaration +function GetKeyEventUniCode(KeyEvent: TKeyEvent): Word; +\Description +\var{GetKeyEventUniCode} returns the unicode part of the +given \var{KeyEvent} if it contains a translated unicode +character. +\Errors +None. +\SeeAlso +\seef{GetKeyEventShiftState}, +\seef{GetKeyEventFlags}, +\seef{GetKeyEventCode}, +\seef{GetKeyEventChar}, +\seef{GetKeyEvent} +\end{function} + +\begin{procedure}{InitKeyBoard} +\Declaration +procedure InitKeyboard; +\Description +\var{InitKeyboard} initializes the keyboard interface, any +additional platform specific parameters should be passed by +setting platform-specific global variables. + +This function should be called once, before using any of the +keyboard functions. +\Errors +None. +\SeeAlso +\seep{DoneKeyBoard} +\end{procedure} + +\begin{function}{IsFunctionKey} +\Declaration +function IsFunctionKey(KeyEvent: TKeyEvent): Boolean; +\Description +\var{IsFunctionKey} returns \var{True} if the given key event +in \var{KeyEvent} was a function key or not. +\Errors +None. +\SeeAlso +\seef{GetKeyEvent} +\end{function} + +\begin{function}{PollKeyEvent} +\Declaration +function PollKeyEvent: TKeyEvent; +\Description +\var{PollKeyEvent} checks whether a key event is available, +and returns it if one is found. If no event is pending, +it returns 0. +\Errors +None. +\SeeAlso +\seep{PutKeyEvent}, \seef{GetKeyEvent} +\end{function} + +\begin{function}{PollShiftStateEvent} +\Declaration +function PollShiftStateEvent: TKeyEvent; +\Description +\var{PollShiftStateEvent} returns the current shiftstate in a +keyevent. This will return 0 if there is no key event pending. +\Errors +None. +\SeeAlso +\seep{PollKeyEvent}, \seef{GetKeyEvent} +\end{function} + +\begin{procedure}{PutKeyEvent} +\Declaration +procedure PutKeyEvent(KeyEvent: TKeyEvent); +\Description +\var{PutKeyEvent} adds the given \var{KeyEvent} to the input +queue. Please note that depending on the implementation this +can hold only one value, i.e. when calling \var{PutKeyEvent} +multiple times, only the last pushed key will be remembered. +\Errors +\SeeAlso +\end{function} + +\begin{function}{TranslateKeyEvent} +\Declaration +function TranslateKeyEvent(KeyEvent: TKeyEvent): TKeyEvent; +\Description +\var{TranslateKeyEvent} performs ASCII translation of the +\var{KeyEvent}. +\Errors +None. +\SeeAlso +\seef{TranslateKeyEventUniCode} +\end{function} + +\begin{function}{TranslateKeyEventUniCode} +\Declaration +function TranslateKeyEventUniCode(KeyEvent: TKeyEvent): TKeyEvent; +\Description +\var{TranslateKeyEventUniCode} performs Unicode translation of the +\var{KeyEvent} +\Errors +\SeeAlso +\end{function}