@database "keyboard"
@master "AMIDEV:NDK/Autodocs/keyboard.doc"

@Node Main "keyboard.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" CMD_CLEAR " Link "CMD_CLEAR"}
    @{" KBD_ADDRESETHANDLER " Link "KBD_ADDRESETHANDLER"}
    @{" KBD_READEVENT " Link "KBD_READEVENT"}
    @{" KBD_READMATRIX " Link "KBD_READMATRIX"}
    @{" KBD_REMRESETHANDLER " Link "KBD_REMRESETHANDLER"}
    @{" KBD_RESETHANDLERDONE " Link "KBD_RESETHANDLERDONE"}
@EndNode

@Node "CMD_CLEAR" "keyboard.device/CMD_CLEAR"

@{b}   NAME@{ub}
	CMD_CLEAR -- Clear the keyboard input buffer.

@{b}   FUNCTION@{ub}
	@{"Remove" Link "exec/Remove()"} from the input buffer any keys transitions waiting to
	satisfy read requests.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set if quick I/O is not possible
	io_Device	preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	CMD_CLEAR
	io_Flags	IOB_QUICK set if quick I/O is possible

@EndNode

@Node "KBD_ADDRESETHANDLER" "keyboard.device/KBD_ADDRESETHANDLER"

@{b}   NAME@{ub}
	KBD_ADDRESETHANDLER -- Add a keyboard reset handler.

@{b}   FUNCTION@{ub}
	Add a function to the list of functions called to clean up
	before a hard reset generated at the keyboard.  The reset
	handler is called as:
	    ResetHandler(handlerData)
	                 a1

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	KBD_ADDRESETHANDLER
	io_Data		a pointer to an interrupt structure.
	    is_Data 	the handlerData pointer described above
	    is_Code	the Handler function address

@{b}   NOTES@{ub}
	Few of the Amiga keyboard models generate the communication codes
	used to implement this reset processing.  Specifically, only the
	Euro a1000 (rare), and the B2000 keyboard generate them.

	The interrupt structure is kept by the keyboard device until a
	RemResetHandler command is satisfied for it, but the
	KBD_ADDRESETHANDLER command itself is replied immediately.

@EndNode

@Node "KBD_READEVENT" "keyboard.device/KBD_READEVENT"

@{b}   NAME@{ub}
	KBD_READEVENT -- Return the next keyboard event.

@{b}   FUNCTION@{ub}
	@{"Read" Link "dos/Read()"} raw keyboard events from the keyboard and put them in the
	data area of the iORequest.  If there are no pending keyboard
	events, this command will not be satisfied, but if there are
	some events, but not as many as can fill IO_LENGTH, the
	request will be satisfied with those currently available.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set if quick I/O is not possible
	io_Device	preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	KBD_READEVENT
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	the size of the io_Data area in bytes: there
			are sizeof(inputEvent) bytes per input event.
	io_Data		a buffer area to fill with input events.  The
			fields of the input event are:
	    ie_NextEvent
			links the events returned
	    ie_Class
			is IECLASS_RAWKEY
	    ie_Code
			contains the next key up/down reports
	    ie_Qualifier
			only the shift and numeric pad bits are set
	    ie_SubClass, ie_X, ie_Y, ie_TimeStamp
			are not used, and set to zero

@{b}   RESULTS@{ub}
	This function sets the error field in the @{"IORequest" Link "INCLUDE:exec/io.h/Main" 16}, and fills
	the @{"IORequest" Link "INCLUDE:exec/io.h/Main" 16} with the next keyboard events (but not partial
	events).

@EndNode

@Node "KBD_READMATRIX" "keyboard.device/KBD_READMATRIX"

@{b}   NAME@{ub}
	KBD_READMATRIX -- @{"Read" Link "dos/Read()"} the current keyboard key matrix.

@{b}   FUNCTION@{ub}
	This function reads the up/down state of every key in the
	key matrix.

@{b}   IO REQUEST INPUT@{ub}
	io_Message	mn_ReplyPort set if quick I/O is not possible
	io_Device	preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	KBD_READMATRIX
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	the size of the io_Data area in bytes: this
			must be big enough to hold the key matrix.
	io_Data		a buffer area to fill with the key matrix:
			an array of bytes whose component bits reflect
			each keys state: the state of the key for
			keycode n is at bit (n MOD 8) in byte
			(n DIV 8) of this matrix.

@{b}   IO REQUEST OUTPUT@{ub}
	io_Error
	     IOERR_BADLENGTH - the io_Length was not exactly 13 bytes.
			The buffer is unchanged.  This is only returned
			by V33/V34 kickstart.
	io_Actual	the number of bytes filled in io_Data with key
			matrix data, i.e. the minimum of the supplied
			length and the internal key matrix size.

@{b}   NOTE@{ub}
	For V33/V34 Kickstart, io_Length must be set to exactly 13 bytes.

@{b}   RESULTS@{ub}
	This function sets the error field in the @{"IORequest" Link "INCLUDE:exec/io.h/Main" 16}, and sets
	matrix to the current key matrix.

@EndNode

@Node "KBD_REMRESETHANDLER" "keyboard.device/KBD_REMRESETHANDLER"

@{b}   NAME@{ub}
	KBD_REMRESETHANDLER -- @{"Remove" Link "exec/Remove()"} a keyboard reset handler.

@{b}   FUNCTION@{ub}
	@{"Remove" Link "exec/Remove()"} a function previously added to the list of reset
	handler functions with @{"KBD_ADDRESETHANDLER" Link "KBD_ADDRESETHANDLER"}.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	KBD_REMRESETHANDLER
	io_Data		a pointer to the handler interrupt structure.

@EndNode

@Node "KBD_RESETHANDLERDONE" "keyboard.device/KBD_RESETHANDLERDONE"

@{b}   NAME@{ub}
	KBD_RESETHANDLERDONE -- Indicate that reset handling is done.

@{b}   FUNCTION@{ub}
	Indicate that reset cleanup associated with the handler has
	completed.  This command should be issued by all keyboard
	reset handlers so that the reset may proceed.

@{b}   IO REQUEST@{ub}
	io_Message	mn_ReplyPort set
	io_Device	preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Unit		preset by @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	KBD_RESETHANDLERDONE
	io_Data		a pointer to the handler interrupt structure.

@{b}   NOTES@{ub}
	The keyboard processor itself performs the hardware reset, and
	will time out and perform the reset even if some reset handlers
	have not indicated yet that the reset may proceed.  This
	timeout is several seconds.

@EndNode