11.2 Functions and Procedures

DoneKeyboard

Declaration:: Procedure DoneKeyboard;
Description:: DoneKeyboard de-initializes the keyboard interface if the keyboard driver is active. If the keyboard driver is not active, the function does nothing.
This will cause the keyboard driver to clear up any allocated memory, or restores the console or terminal the program was running in to its initial state before the call to InitKeyBoard (299). This function should be called on program exit. Failing to do so may leave the terminal or console window in an unusable state. Its exact action depends on the platform on which the program is running.
Errors:: None.
See also:: InitKeyBoard (299)

For an example, see most other functions.

FunctionKeyName

Declaration:: Function FunctionKeyName (KeyCode : Word) : String;
Description:: FunctionKeyName returns a string representation of the function key with code KeyCode. This can be an actual function key, or one of the cursor movement keys.
Errors:: In case KeyCode does not contain a function code, the SUnknownFunctionKey string is returned, appended with the KeyCode.
See also:: ShiftStateToString (304) KeyEventToString (300)

Listing: kbdex/ex8.pp

Program Example8;

{ Program to demonstrate the FunctionKeyName function. }

Uses keyboard;

Var
  K : TkeyEvent;

begin
  InitKeyboard;
  Writeln('Press function keys, press "q" to end.');
  Repeat
    K:=GetKeyEvent;
    K:=TranslateKeyEvent(K);
    If IsFunctionKey(k) then
      begin
      Write('Got function key : ');
      Writeln(FunctionKeyName(TkeyRecord(K).KeyCode));
      end;
  Until (GetKeyEventChar(K)='q');
  DoneKeyboard;
end.

GetKeyboardDriver

Declaration:: Procedure GetKeyboardDriver (Var Driver : TKeyboardDriver);
Description:: GetKeyBoardDriver returns in Driver the currently active keyboard driver. This function can be used to enhance an existing keyboarddriver.
For more information on getting and setting the keyboard driver section 11.4, page 313.
Errors:: None.
See also:: SetKeyboardDriver (303)

GetKeyEvent

Declaration:: function GetKeyEvent: TKeyEvent;
Description:: GetKeyEvent returns the last keyevent if one was stored in PendingKeyEvent, or waits for one if none is available. A non-blocking version is available in PollKeyEvent (301).
The returned key is encoded as a TKeyEvent type variable, and is normally the physical key scan code, (the scan code is driver dependent) which can be translated with one of the translation functions TranslateKeyEvent (304) or TranslateKeyEventUniCode (304). See the types section for a description of how the key is described.
Errors:: If no key became available, 0 is returned.
See also:: PutKeyEvent (302), PollKeyEvent (301), TranslateKeyEvent (304), TranslateKeyEventUniCode (304)

Listing: kbdex/ex1.pp

program example1;

{ This program demonstrates the GetKeyEvent function }

uses keyboard;

Var
  K : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press keys, press "q" to end.');
  Repeat
    K:=GetKeyEvent;
    Write('Got key event with ');
    Case GetKeyEventFlags(K) of
      kbASCII    : Writeln('ASCII key');
      kbUniCode  : Writeln('Unicode key');
      kbFnKey    : Writeln('Function key');
      kbPhys     : Writeln('Physical key');
      kbReleased : Writeln('Released key event');
    end;
    K:=TranslateKeyEvent(K);
    Writeln('Got key : ',KeyEventToString(K));
  Until (GetKeyEventChar(K)='q');
  DoneKeyBoard;
end.

GetKeyEventChar

Declaration:: function GetKeyEventChar(KeyEvent: TKeyEvent): Char;
Description:: GetKeyEventChar returns the charcode part of the given KeyEvent, if it contains a translated character key keycode. The charcode is simply the ascii code of the character key that was pressed.
It returns the null character if the key was not a character key, but e.g. a function key.
Errors:: None.
See also:: GetKeyEventUniCode (299), GetKeyEventShiftState (298), GetKeyEventFlags (297), GetKeyEventCode (297), GetKeyEvent (295)

For an example, see GetKeyEvent (295)

GetKeyEventCode

Declaration:: function GetKeyEventCode(KeyEvent: TKeyEvent): Word;
Description:: GetKeyEventCode returns the translated function keycode part of the given KeyEvent, if it contains a translated function key.
If the key pressed was not a function key, the null character is returned.
Errors:: None.
See also:: GetKeyEventUniCode (299), GetKeyEventShiftState (298), GetKeyEventFlags (297), GetKeyEventChar (296), GetKeyEvent (295)

Listing: kbdex/ex2.pp

Program Example2;

{ Program to demonstrate the GetKeyEventCode function. }

Uses keyboard;

Var
  K : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press function keys, or press "q" to end.');
  Repeat
    K:=GetKeyEvent;
    K:=TranslateKeyEvent(K);
    If (GetKeyEventFlags(K)<>KbfnKey) then
      Writeln('Not a function key')
    else
      begin
      Write('Got key (',GetKeyEventCode(K));
      Writeln(') : ',KeyEventToString(K));
      end;
  Until (GetKeyEventChar(K)='q');
  DoneKeyboard;
end.

GetKeyEventFlags

Declaration:: function GetKeyEventFlags(KeyEvent: TKeyEvent): Byte;
Description:: GetKeyEventFlags returns the flags part of the given KeyEvent.
Errors:: None.
See also:: GetKeyEventUniCode (299), GetKeyEventShiftState (298), GetKeyEventCode (297), GetKeyEventChar (296), GetKeyEvent (295)

For an example, see GetKeyEvent (295)

GetKeyEventShiftState

Declaration:: function GetKeyEventShiftState(KeyEvent: TKeyEvent): Byte;
Description:: GetKeyEventShiftState returns the shift-state values of the given KeyEvent. This can be used to detect which of the modifier keys Shift, Alt or Ctrl were pressed. If none were pressed, zero is returned.
Note that this function does not always return expected results; In a unix X-Term, the modifier keys do not always work.
Errors:: None.
See also:: GetKeyEventUniCode (299), GetKeyEventFlags (297), GetKeyEventCode (297), GetKeyEventChar (296), GetKeyEvent (295)

Listing: kbdex/ex3.pp

Program Example3;

{ Program to demonstrate the GetKeyEventShiftState function. }

Uses keyboard;

Var
  K : TKeyEvent;
  S : Byte;

begin
  InitKeyBoard;
  Write('Press keys combined with CTRL/SHIFT/ALT');
  Writeln(', or press "q" to end.');
  Repeat
    K:=GetKeyEvent;
    K:=TranslateKeyEvent(K);
    S:=GetKeyEventShiftState(K);
    If (S=0) then
      Writeln('No special keys pressed')
    else
      begin
      Writeln('Detected special keys : ',ShiftStateToString(K,False));
      Writeln('Got key : ',KeyEventToString(K));
      end;
  Until (GetKeyEventChar(K)='q');
  DoneKeyboard;
end.

GetKeyEventUniCode

Declaration:: function GetKeyEventUniCode(KeyEvent: TKeyEvent): Word;
Description:: GetKeyEventUniCode returns the unicode part of the given KeyEvent if it contains a translated unicode character.
Errors:: None.
See also:: GetKeyEventShiftState (298), GetKeyEventFlags (297), GetKeyEventCode (297), GetKeyEventChar (296), GetKeyEvent (295)

No example available yet.

InitKeyBoard

Declaration:: procedure InitKeyboard;
Description:: InitKeyboard initializes the keyboard driver. If the driver is already active, it does nothing. When the driver is initialized, it will do everything necessary to ensure the functioning of the keyboard, including allocating memory, initializing the terminal etc.
This function should be called once, before using any of the keyboard functions. When it is called, the DoneKeyboard (294) function should also be called before exiting the program or changing the keyboard driver with SetKeyboardDriver (303).
Errors:: None.
See also:: DoneKeyboard (294), SetKeyboardDriver (303)

For an example, see most other functions.

IsFunctionKey

Declaration:: function IsFunctionKey(KeyEvent: TKeyEvent): Boolean;
Description:: IsFunctionKey returns True if the given key event in KeyEvent was a function key or not.
Errors:: None.
See also:: GetKeyEvent (295)

Listing: kbdex/ex7.pp

program example1;

{ This program demonstrates the GetKeyEvent function }

uses keyboard;

Var
  K : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press keys, press "q" to end.');
  Repeat
    K:=GetKeyEvent;
    K:=TranslateKeyEvent(K);
    If IsFunctionKey(K) then
      Writeln('Got function key : ',KeyEventToString(K))
    else
      Writeln('not a function key.');
  Until (GetKeyEventChar(K)='q');
  DoneKeyBoard;
end.

KeyEventToString

Declaration:: Function KeyEventToString(KeyEvent : TKeyEvent) : String;
Description:: KeyEventToString translates the key event in KeyEvent to a human-readable description of the pressed key. It will use the constants described in the constants section to do so.
Errors:: If an unknown key is passed, the scancode is returned, prefixed with the SScanCode string.
See also:: FunctionKeyName (294), ShiftStateToString (304)

For an example, see most other functions.

PollKeyEvent

Declaration:: function PollKeyEvent: TKeyEvent;
Description:: PollKeyEvent checks whether a key event is available, and returns it if one is found. If no event is pending, it returns 0.
Note that this does not remove the key from the pending keys. The key should still be retrieved from the pending key events list with the GetKeyEvent (295) function.
Errors:: None.
See also:: PutKeyEvent (302), GetKeyEvent (295)

Listing: kbdex/ex4.pp

program example4;

{ This program demonstrates the PollKeyEvent function }

uses keyboard;

Var
  K : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press keys, press "q" to end.');
  Repeat
    K:=PollKeyEvent;
    If k<>0 then
      begin
      K:=GetKeyEvent;
      K:=TranslateKeyEvent(K);
      writeln;
      Writeln('Got key : ',KeyEventToString(K));
      end
    else
      write('.');
  Until (GetKeyEventChar(K)='q');
  DoneKeyBoard;
end.

PollShiftStateEvent

Declaration:: function PollShiftStateEvent: TKeyEvent;
Description:: PollShiftStateEvent returns the current shiftstate in a keyevent. This will return 0 if there is no key event pending.
Errors:: None.
See also:: PollKeyEvent (301), GetKeyEvent (295)

Listing: kbdex/ex6.pp

program example6;

{ This program demonstrates the PollShiftStateEvent function }

uses keyboard;

Var
  K : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press keys, press "q" to end.');
  Repeat
    K:=PollKeyEvent;
    If k<>0 then
      begin
      K:=PollShiftStateEvent;
      Writeln('Got shift state : ',ShiftStateToString(K,False));
      // Consume the key.
      K:=GetKeyEvent;
      K:=TranslateKeyEvent(K);
      end
{    else
      write('.')};
  Until (GetKeyEventChar(K)='q');
  DoneKeyBoard;
end.

PutKeyEvent

Declaration:: procedure PutKeyEvent(KeyEvent: TKeyEvent);
Description:: PutKeyEvent adds the given KeyEvent to the input queue. Please note that depending on the implementation this can hold only one value, i.e. when calling PutKeyEvent multiple times, only the last pushed key will be remembered.
Errors:: None
See also:: PollKeyEvent (301), GetKeyEvent (295)

Listing: kbdex/ex5.pp

program example5;

{ This program demonstrates the PutKeyEvent function }

uses keyboard;

Var
  K,k2 : TKeyEvent;

begin
  InitKeyBoard;
  Writeln('Press keys, press "q" to end.');
  K2:=0;
  Repeat
    K:=GetKeyEvent;
    If k<>0 then
      begin
      if (k2 mod 2)=0 then
        K2:=K+1
      else
        K2:=0;
      K:=TranslateKeyEvent(K);
      Writeln('Got key : ',KeyEventToString(K));
      if (K2<>0) then
        begin
        PutKeyEvent(k2);
        K2:=TranslateKeyEVent(K2);
        Writeln('Put key : ',KeyEventToString(K2))
        end
      end
  Until (GetKeyEventChar(K)='q');
  DoneKeyBoard;
end.

SetKeyboardDriver

Declaration:

Function SetKeyboardDriver (Const Driver : TKeyboardDriver) : Boolean;

Description:

SetKeyBoardDriver sets the keyboard driver to Driver, if the current keyboard driver is not yet initialized. If the current keyboard driver is initialized, then SetKeyboardDriver does nothing. Before setting the driver, the currently active driver should be disabled with a call to DoneKeyboard (294).

The function returns True if the driver was set, False if not.

For more information on setting the keyboard driver, see section 11.4, page 313.

Errors:

None.

See also:

GetKeyboardDriver (295), DoneKeyboard (294).

ShiftStateToString

Declaration:: Function ShiftStateToString(KeyEvent : TKeyEvent; UseLeftRight : Boolean) : String;
Description:: ShiftStateToString returns a string description of the shift state of the key event KeyEvent. This can be an empty string.
The shift state is described using the strings in the SShift constant.
Errors:: None.
See also:: FunctionKeyName (294), KeyEventToString (300)

For an example, see PollShiftStateEvent (301).

TranslateKeyEvent

Declaration:: function TranslateKeyEvent(KeyEvent: TKeyEvent): TKeyEvent;
Description:: TranslateKeyEvent performs ASCII translation of the KeyEvent. It translates a physical key to a function key if the key is a function key, and translates the physical key to the ordinal of the ascii character if there is an equivalent character key.
Errors:: None.
See also:: TranslateKeyEventUniCode (304)

For an example, see GetKeyEvent (295)

TranslateKeyEventUniCode

Declaration:: function TranslateKeyEventUniCode(KeyEvent: TKeyEvent): TKeyEvent;
Description:: TranslateKeyEventUniCode performs Unicode translation of the KeyEvent. It is not yet implemented for all platforms.
Errors:: If the function is not yet implemented, then the ErrorCode of the system unit will be set to errKbdNotImplemented
See also:

No example available yet.

[next] [prev] [prev-tail] [front] [up]