========
lowlevel
========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`AddKBInt()`_                           `AddTimerInt()`_                        `AddVBlankInt()`_                       `ElapsedTime()`_                        
`GetKey()`_                             `GetLanguageSelection()`_               `QueryKeys()`_                          `ReadJoyPort()`_                        
`RemKBInt()`_                           `RemTimerInt()`_                        `RemVBlankInt()`_                       `SetJoyPortAttrsA()`_                   
`StartTimerInt()`_                      `StopTimerInt()`_                       `SystemControlA()`_                     
======================================= ======================================= ======================================= ======================================= 

-----------

AddKBInt()
==========

Synopsis
~~~~~~~~
::

 APTR AddKBInt(
          APTR intRoutine,
          APTR intData );

Function
~~~~~~~~
::

        register a callback that is called whenever a keyboard
        input event occurs.


Inputs
~~~~~~
::

     intRoutine - the routine to invoke every vblank. This routine should
                  be as short as possible to minimize its effect on overall
                  system performance.
     intData - data passed to the routine in register A1. If more than one
               long word of data is required this should be a pointer to
               a structure that contains the required data.



----------

AddTimerInt()
=============

Synopsis
~~~~~~~~
::

 APTR AddTimerInt(
          APTR intRoutine,
          APTR intData );

Function
~~~~~~~~
::


 Add a callback function that should be executed every time the timer
 interrupt triggers.
 
 The timer will be allocated, but not configured or enabled - StartIntTimer()
 must be called to initalize the correct paramaters.


Inputs
~~~~~~
::


 intRoutine  --  the callback function to invoke each vertical blank
 intData     --  data passed to the callback function


Result
~~~~~~
::


 A handle used to manipulate the interrupt or NULL if the call failed.


Bugs
~~~~
::

     This function is unimplemented.



----------

AddVBlankInt()
==============

Synopsis
~~~~~~~~
::

 APTR AddVBlankInt(
          APTR intRoutine,
          APTR intData );

Function
~~~~~~~~
::


 Add a callback function that should be executed every vertical blank.
 If your program can exit without rebooting the machine, RemVBlankInt()
 has to be called prior to exiting.
     Only one interrupt routine may be added; always check the return
 value of this function in case some other program already has used this
 function.


Inputs
~~~~~~
::


 intRoutine  --  the callback function to invoke each vertical blank
 intData     --  data passed to the callback function


Result
~~~~~~
::


 A handle used to manipulate the interrupt or NULL if the call failed.



See also
~~~~~~~~

`RemVBlankInt()`_ 

----------

ElapsedTime()
=============

Synopsis
~~~~~~~~
::

 ULONG ElapsedTime(
          struct EClockVal * context );

Bugs
~~~~
::

     This function is unimplemented.



----------

GetKey()
========

Synopsis
~~~~~~~~
::

 ULONG GetKey();

Function
~~~~~~~~
::

     returns the currently pressed 'qualifier' and 'key' combination.


Inputs
~~~~~~
::

     none


Result
~~~~~~
::

     0xFF if no key is pressed otherwise it returns the actual key in the low word,
     and qualifier in the high word -:
     
     'qualifier'     key equivalent
     LLKB_LSHIFT     Left Shift
     LLKB_RSHIFT     Rigt Shift
     LLKB_CAPSLOCK   Caps Lock
     LLKB_CONTROL    Control
     LLKB_LALT       Left Alt
     LLKB_RALT       Right Alt
     LLKB_LAMIGA     Left Amiga
     LLKB_RAMIGA     Right Amiga



----------

GetLanguageSelection()
======================

Synopsis
~~~~~~~~
::

 ULONG GetLanguageSelection();


----------

QueryKeys()
===========

Synopsis
~~~~~~~~
::

 VOID QueryKeys(
          struct KeyQuery * queryArray,
          UBYTE arraySize );

Bugs
~~~~
::

     This function is unimplemented.



----------

ReadJoyPort()
=============

Synopsis
~~~~~~~~
::

 ULONG ReadJoyPort(
          ULONG port );

Notes
~~~~~
::

     This function isn't implemented on all platforms.



----------

RemKBInt()
==========

Synopsis
~~~~~~~~
::

 VOID RemKBInt(
          APTR intHandle );

Function
~~~~~~~~
::

        remove a keyboard interrupt previously registerd
        with addkbint.



----------

RemTimerInt()
=============

Synopsis
~~~~~~~~
::

 VOID RemTimerInt(
          APTR intHandle );

Bugs
~~~~
::

     This function is unimplemented.



----------

RemVBlankInt()
==============

Synopsis
~~~~~~~~
::

 VOID RemVBlankInt(
          APTR intHandle );

Function
~~~~~~~~
::


 Remove a vertical blank interrupt routine previously added by a call to
 AddVBlankInt().


Inputs
~~~~~~
::


 intHandle  --  return value from AddVBlankInt(); may be NULL in which case
                this function is a no-op.



See also
~~~~~~~~

`AddVBlankInt()`_ 

----------

SetJoyPortAttrsA()
==================

Synopsis
~~~~~~~~
::

 BOOL SetJoyPortAttrsA(
          ULONG portNumber,
          struct TagItem * tagList );
 
 BOOL SetJoyPortAttrs(
          ULONG portNumber,
          TAG tag, ... );

Function
~~~~~~~~
::

     Allows control over the behaviour of a joystick or game controller
     port handled by lowlevel.library.  Each port normally operates in
     automatic detection mode, identifying whether a mouse, joystick, or
     other controller is connected.  This function can override that
     behaviour or reset a port to its default state.

     The attributes are supplied as a tag list.  Only the tags listed
     below are defined by the standard lowlevel.library interface and
     compatible Poseidon (USB stack) extensions.

     Tag meanings:

         SJA_Type (ULONG)
             Sets the controller type for the given port.  Possible values:

                 SJA_TYPE_AUTOSENSE  - Enable automatic device detection (default)
                 SJA_TYPE_MOUSE      - Force mouse mode
                 SJA_TYPE_JOYSTK     - Force joystick mode
                 SJA_TYPE_GAMECTLR   - Force game controller mode

             When set to anything other than AUTOSENSE, lowlevel.library
             will not attempt to detect the connected device type
             automatically.  It is the callers responsibility to restore
             AUTOSENSE before exiting.

         SJA_Reinitialize (VOID)
             Resets the specified port to its initial state, freeing any
             allocated resources and returning it to AUTOSENSE mode.

         -- Poseidon (USB stack) extensions --

         SJA_RumbleSetSlowMotor (ULONG)
             Activates the slow (low-frequency) rumble motor of a
             compatible game controller.  The parameter specifies the
             intensity level as a 32-bit value from 0 (off) to 0xFFFFFFFF
             (maximum).  Values outside this range are clamped.

         SJA_RumbleSetFastMotor (ULONG)
             Activates the fast (high-frequency) rumble motor of a
             compatible game controller.  The parameter specifies the
             intensity level as a 32-bit value from 0 (off) to 0xFFFFFFFF
             (maximum).

         SJA_RumbleOff (VOID)
             Disables all active rumble motors immediately.  Equivalent
             to setting both SJA_RumbleSetSlowMotor and
             SJA_RumbleSetFastMotor to zero.

     These rumble control tags are supported only if the underlying port
     driver or Poseidon class implements force feedback support.  On
     systems without such support, the tags are ignored without error.


Inputs
~~~~~~
::

     portNumber - Index of the controller port to modify (typically 03).
     tagList    - Pointer to a TagItem list describing attributes to set.
                  May be NULL, in which case the function performs no action
                  but returns TRUE.


Result
~~~~~~
::

     Returns TRUE if successful, or FALSE if the specified port number or
     tag was invalid or if the operation could not be completed.



See also
~~~~~~~~

`ReadJoyPort()`_ `SystemControlA()`_ utility.library/TagItem 

----------

StartTimerInt()
===============

Synopsis
~~~~~~~~
::

 VOID StartTimerInt(
          APTR intHandle,
          ULONG timeInterval,
          BOOL continuous );

Bugs
~~~~
::

     This function is unimplemented.



----------

StopTimerInt()
==============

Synopsis
~~~~~~~~
::

 VOID StopTimerInt(
          APTR intHandle );

Bugs
~~~~
::

     This function is unimplemented.



----------

SystemControlA()
================

Synopsis
~~~~~~~~
::

 ULONG SystemControlA(
          struct TagItem * tags );
 
 ULONG SystemControl(
          TAG tag, ... );

Function
~~~~~~~~
::

     Provides a mechanism to enable or disable selected system-level
     input and multitasking features under program control.  This
     function is intended for use by games or multimedia applications
     that require exclusive access to hardware input devices or
     want to temporarily suppress normal OS behaviour (such as
     keyboard shortcuts or multitasking).

     The desired controls are specified using a TagItem list.
     Each tag corresponds to a particular system feature or behaviour
     that may be disabled, enabled, or queried.

     This call is advisory and may not be implemented fully on all
     systems.  Unsupported tags are ignored.

     Recognized tags (as defined in <libraries/lowlevel.h>):

         SCON_AllowIRQ (ULONG)
             If set to FALSE, prevents lowlevel.library from generating
             certain input interrupts.  Default is TRUE.

         SCON_StopTaskSwitch (ULONG)
             When set to TRUE, temporarily halts task switching,
             effectively freezing multitasking.  This should be used
             with great caution and released as soon as possible.

         SCON_StopKeyRepeat (ULONG)
             If set to TRUE, disables key auto-repeat from the input.device.

         SCON_EnableECSKeys (ULONG)
             Enables extended keyboard keys on some hardware (e.g., F11/F12).

         SCON_RequestExclusive (ULONG)
             Requests exclusive access to input devices such as keyboard
             and mouse, preventing other applications from receiving events.


Inputs
~~~~~~
::

     tags - Pointer to a TagItem list specifying the system control
            operations to perform.  May be NULL, in which case the call
            does nothing and returns 0.


Result
~~~~~~
::

     Returns a bitmask of results depending on the requested operations.
     The exact meaning of returned bits is implementation-dependent.
     Typically, a non-zero value indicates success or the current state
     of queried controls.


Bugs
~~~~
::

     This functions implementation is incomplete and not all control
     tags are acted upon in current releases.



See also
~~~~~~~~

`SetJoyPortAttrsA()`_ `ReadJoyPort()`_ utility.library/TagItem 

