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

@Node Main "input.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" IND_ADDEVENT " Link "IND_ADDEVENT"}
    @{" IND_ADDHANDLER " Link "IND_ADDHANDLER"}
    @{" IND_REMHANDLER " Link "IND_REMHANDLER"}
    @{" IND_SETMPORT " Link "IND_SETMPORT"}
    @{" IND_SETMTRIG " Link "IND_SETMTRIG"}
    @{" IND_SETMTYPE " Link "IND_SETMTYPE"}
    @{" IND_SETPERIOD " Link "IND_SETPERIOD"}
    @{" IND_SETTHRESH " Link "IND_SETTHRESH"}
    @{" IND_WRITEEVENT " Link "IND_WRITEEVENT"}
    @{" PeekQualifier() " Link "PeekQualifier()"}
@EndNode

@Node "IND_ADDEVENT" "input.device/IND_ADDEVENT"

@{b}   NAME@{ub}
	IND_ADDEVENT -- Parse a synthetic input event and pass it
			to all handlers (V47)

@{b}   FUNCTION@{ub}

@{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_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	IND_ADDEVENT
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	shall be a multiple of
			sizeof(struct InputEvent)
	io_Data		a pointer to the struct InputEvent:
	    ie_NextEvent
			will be ignored.
	    ie_Class	IECLASS_RAWKEY or IECLASS_RAWMOUSE
	    ie_SubClass
	    ie_Code
	    ie_Qualifier
	    ie_X, ie_Y
			as desired
	    ie_TimeStamp
			will be set by this call (V36)

@{b}   NOTES@{ub}
	The contents of the input event are destroyed.

	This function is almost identical to @{"IND_WRITEEVENT" Link "IND_WRITEEVENT"} except
	that the input.device will perform some minimal update
	of its state machine, and as such, will use the provided
	event to synthesize keyboard repeat functions if applicable.
	The received event will update the internal state of the
	device as if it was coming from the keyboard or gameport
	device.
	This function may add multiple events in one single call,
	the number of events is derived from io_Length.
	If you queue multiple events, they shall be all of the same
	type, i.e. IECLASS_RAWKEY or IECLASS_RAWMOUSE, but not
	both types in a single @{"IORequest" Link "INCLUDE:exec/io.h/Main" 16}.

@EndNode

@Node "IND_ADDHANDLER" "input.device/IND_ADDHANDLER"

@{b}   NAME@{ub}
	IND_ADDHANDLER -- Add an input handler to the device

@{b}   FUNCTION@{ub}
	Add a function to the list of functions called to handle
	input events generated by this device.  The function is called
	as
	    newInputEvents = Handler(inputEvents, handlerData);
	    D0			     A0		  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	IND_ADDHANDLER
	io_Data		a pointer to an interrupt structure.
	    is_Data 	the handlerData pointer described above
	    is_Code	the Handler function address

@{b}   NOTES@{ub}
	The interrupt structure is kept by the input device until a
	RemHandler command is satisfied for it.

@EndNode

@Node "IND_REMHANDLER" "input.device/IND_REMHANDLER"

@{b}   NAME@{ub}
	IND_REMHANDLER -- @{"Remove" Link "exec/Remove()"} an input handler from the device

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

@{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	IND_REMHANDLER
	io_Data		a pointer to the interrupt structure.

@{b}   NOTES@{ub}
	This command is not immediate

@EndNode

@Node "IND_SETMPORT" "input.device/IND_SETMPORT"

@{b}   NAME@{ub}
	IND_SETMPORT -- Set the current mouse port

@{b}   FUNCTION@{ub}
	This command sets the gameport port at which the mouse is
	connected.

@{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_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	IND_SETMPORT
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	1
	io_Data		a pointer to a byte that is either 0 or 1,
			indicating that mouse input should be obtained
			from either the left or right controller port,
			respectively.

@EndNode

@Node "IND_SETMTRIG" "input.device/IND_SETMTRIG"

@{b}   NAME@{ub}
	IND_SETMTRIG -- Set the conditions for a mouse port report

@{b}   FUNCTION@{ub}
	This command sets what conditions must be met by a mouse
	before a pending @{"Read" Link "dos/Read()"} request will be satisfied.  The trigger
	specification is that used by the gameport device.

@{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_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	IND_SETMTRIG
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	sizeof(gameportTrigger)
	io_Data		a structure of type GameportTrigger, which
			has the following elements
	    gpt_Keys -
		    GPTB_DOWNKEYS set if button down transitions
		    trigger a report, and GPTB_UPKEYS set if button up
		    transitions trigger a report
	    gpt_Timeout	-
		    a time which, if exceeded, triggers a report;
		    measured in vertical blank units (60/sec)
	    gpt_XDelta	-
		    a distance in x which, if exceeded, triggers a
		    report
	    gpt_YDelta	-
		    a distance in x which, if exceeded, triggers a
		    report

@EndNode

@Node "IND_SETMTYPE" "input.device/IND_SETMTYPE"

@{b}   NAME@{ub}
	IND_SETMTYPE -- Set the current mouse port controller type

@{b}   FUNCTION@{ub}
	This command sets the type of device at the mouse port, so
	the signals at the port may be properly interpreted.

@{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_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	IND_SETMTYPE
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	1
	io_Data		the address of the byte variable describing
			the controller type, as per the equates in
			the gameport include file

@EndNode

@Node "IND_SETPERIOD" "input.device/IND_SETPERIOD"

@{b}   NAME@{ub}
	IND_SETPERIOD -- Set the key repeat period

@{b}   FUNCTION@{ub}
	This command sets the period at which a repeating key repeats.

	This command always executes immediately.

@{b}   IO REQUEST - a timerequest@{ub}
	tr_node.io_Message	mn_ReplyPort set if quick I/O is not possible
	tr_node.io_Device	preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	tr_node.io_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	tr_node.io_Command	IND_SETPERIOD
	tr_node.io_Flags	IOB_QUICK set if quick I/O is possible
	tr_time.tv_secs		the repeat period seconds
	tr_time.tv_micro	the repeat period microseconds

@EndNode

@Node "IND_SETTHRESH" "input.device/IND_SETTHRESH"

@{b}   NAME@{ub}
	IND_SETTHRESH -- Set the key repeat threshold

@{b}   FUNCTION@{ub}
	This command sets the time that a key must be held down before
	it can repeat.  The repeatability of a key may be restricted
	(as, for example, are the shift keys).

	This command always executes immediately.

@{b}   IO REQUEST - a timerequest@{ub}
	tr_node.io_Message	mn_ReplyPort set if quick I/O is not possible
	tr_node.io_Device	preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	tr_node.io_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	tr_node.io_Command	IND_SETTHRESH
	tr_node.io_Flags	IOB_QUICK set if quick I/O is possible
	tr_time.tv_secs		the threshold seconds
	tr_time.tv_micro	the threshold microseconds

@EndNode

@Node "IND_WRITEEVENT" "input.device/IND_WRITEEVENT"

@{b}   NAME@{ub}
	IND_WRITEEVENT -- Propagate an input event to all handlers

@{b}   FUNCTION@{ub}

@{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_Unit		preset by the call to @{"OpenDevice" Link "trackdisk/OpenDevice()"}
	io_Command	IND_WRITEEVENT
	io_Flags	IOB_QUICK set if quick I/O is possible
	io_Length	shall be sizeof(struct InputEvent)
	io_Data		a pointer to the struct InputEvent:
	    ie_NextEvent
			will be ignored.
	    ie_Class
	    ie_SubClass
	    ie_Code
	    ie_Qualifier
	    ie_X, ie_Y
			as desired
	    ie_TimeStamp
			will be set by this call (V36)

@{b}   NOTES@{ub}
	The contents of the input event are destroyed.

	This function was documented in V34 and earlier to allow
	chaining of events via ie_NextEvent.  The implementation
	never allowed that.  The documentation now reflects this.

	ie_TimeStamp is set only in V36 and later.  Software written
	to run on earlier versions should set this field to the
	current time.

@EndNode

@Node "PeekQualifier()" "input.device/PeekQualifier"

@{b}   NAME@{ub}
	PeekQualifier -- get the input device's current qualifiers (V36)

@{b}   SYNOPSIS@{ub}
	qualifier = PeekQualifier()
	d0

	@{"UWORD" Link "INCLUDE:exec/types.h/Main" 116} PeekQualifier( VOID );

@{b}   FUNCTION@{ub}
	This function takes a snapshot of what the input device thinks
	the current qualifiers are.

@{b}   RESULTS@{ub}
	qualifier - a word with the following bits set according to
	    what the input device knows their state to be:
		IEQUALIFIER_LSHIFT, IEQUALIFIER_RSHIFT,
		IEQUALIFIER_CAPSLOCK, IEQUALIFIER_CONTROL,
		IEQUALIFIER_LALT, IEQUALIFIER_RALT,
		IEQUALIFIER_LCOMMAND, IEQUALIFIER_RCOMMAND,
		IEQUALIFIER_LEFTBUTTON, IEQUALIFIER_RBUTTON,
		IEQUALIFIER_MIDBUTTON

@{b}   NOTE@{ub}
	This function is new for V36.

@{b}   SEE ALSO@{ub}
	@{"devices/inputevent.h" Link "INCLUDE:devices/inputevent.h/Main" 0}

@EndNode