mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-08-23 18:40:37 +02:00
+ Initial implementation
This commit is contained in:
michael
parent
ac4225a280
commit
526bff2b1b
309
docs/keyboard.tex
Normal file
309
docs/keyboard.tex
Normal file
@ -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}
|
||||
Loading…
Reference in New Issue
Block a user