TABLE OF CONTENTS input.device/IND_ADDEVENT input.device/IND_ADDHANDLER input.device/IND_ADDNOTIFY input.device/IND_GETHANDLERLIST input.device/IND_GETKDEVICE input.device/IND_GETMDEVICE input.device/IND_GETPERIOD input.device/IND_GETTHRESH input.device/IND_IMMEDIATEADDNOTIFY input.device/IND_REMHANDLER input.device/IND_REMOVENOTIFY input.device/IND_SETKDEVICE input.device/IND_SETMDEVICE input.device/IND_SETMPORT input.device/IND_SETMTRIG input.device/IND_SETMTYPE input.device/IND_SETPERIOD input.device/IND_SETTHRESH input.device/IND_WRITEEVENT input.device/PeekQualifier input.device/IND_ADDEVENT input.device/IND_ADDEVENT NAME IND_ADDEVENT -- Propagate an input event to all handlers, updating event qualifiers (V50) FUNCTION IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to OpenDevice io_Command IND_ADDEVENT io_Flags IOB_QUICK set if quick I/O is possible io_Length must be a multiple of sizeof(struct InputEvent) io_Data a pointer to the first struct InputEvent: ie_NextEvent will be ignored. ie_Class must be IECLASS_RAWMOUSE, IECLASS_RAWKEY, IECLASS_MOUSEWHEEL or IECLASS_EXTENDEDRAWKEY. ie_SubClass ie_Code ie_Qualifier ie_X, ie_Y as desired ie_TimeStamp will be set by this call RESULTS io_Actual a multiple of sizeof(struct InputEvent), which indicates how many events were written. NOTES The contents of the input event are destroyed. This command only supports raw mouse and raw keyboard events. All other event types will be ignored. More than one event may be written at a time, as indicated by io_Length. Unlike IND_WRITEEVENT, the internal input.device qualifier state information will be updated as the events are written. This does not, however, relieve you of the duty to fill in the qualifiers for the event type to be sent. This means, for example, that for an IECLASS_RAWMOUSE event you will have to fill in the IEQUALIFIER_LEFTBUTTON flag for as long as the left mouse button is being held down, and when the button is finally released, a corresponding input event will have to be sent with the IEQUALIFIER_LEFTBUTTON flag cleared. To generate proper raw mouse events, use relative coordinates for ie_X and ie_Y and set the IEQUALIFIER_RELATIVEMOUSE qualifier flag. IECLASS_RAWMOUSE events will be merged if their qualifiers match. The ie_X and ie_Y delta values will be added up. A relationship between qualifiers and the ie_Code value is assumed: the ie_Code value of the first event is copied to all following input events which share the same set of qualifiers and are of the IECLASS_RAWMOUSE type. IECLASS_MOUSEWHEEL and IECLASS_EXTENDEDRAWKEY support was added in V51.1. SEE ALSO devices/inputevent.h input.device/IND_WRITEEVENT input.device/IND_ADDHANDLER input.device/IND_ADDHANDLER NAME IND_ADDHANDLER -- Add an input handler to the device FUNCTION 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); IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by 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 NOTES The interrupt structure is kept by the input device until a IND_REMHANDLER command is satisfied for it. input.device/IND_ADDNOTIFY input.device/IND_ADDNOTIFY NAME IND_ADDNOTIFY -- Add a hook which will be invoked whenever an input.device configuration option is changed. (V50) FUNCTION The commands IND_SETTHRESH, IND_SETPERIOD, IND_SETMPORT, IND_SETMTYPE, IND_SETMTRIG, IND_SETMDEVICE, and IND_SETKDEVICE will change input.device configuration options which may be of interest to external input event feeds. Notifications of the change can be propagated as soon as the change is complete by having input.device call a Hook for every interested feed. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to OpenDevice io_Command IND_ADDNOTIFY io_Flags IOB_QUICK set if quick I/O is possible io_Length must be set to sizeof(struct Hook) io_Data the address of the Hook to be installed. NOTES Whenever a change occurs, the notification hooks installed will be invoked with the following parameters: hook_func(hook,reserved,message) A0 A2 A1 VOID hook_func(struct Hook *hook,APTR reserved,APTR message); The 'reserved' parameter will be NULL. The 'message' parameter will point to a message structure specific to the change that has taken place: struct IDThresholdNotifyMsg (key repeat threshold) struct IDPeriodNotifyMsg (key repeat period) struct IDMousePortNotifyMsg (mouse port) struct IDMouseTypeNotifyMsg (mouse type) struct IDMouseTriggerNotifyMsg (mouse trigger) struct IDMouseDeviceNotifyMsg (mouse device) struct IDKeyboardDeviceNotifyMsg (keyboard device) To find out which kind of message your hook has received, look at the 'idnm_Type' field of the parameter: IDNOTIFY_Threshold (struct IDThresholdNotifyMsg) IDNOTIFY_Period (struct IDPeriodNotifyMsg) IDNOTIFY_MousePort (struct IDMousePortNotifyMsg) IDNOTIFY_MouseType (struct IDMouseTypeNotifyMsg) IDNOTIFY_MouseTrigger (struct IDMouseTriggerNotifyMsg) IDNOTIFY_MouseDevice (struct IDMouseDeviceNotifyMsg) IDNOTIFY_KeyboardDevice (struct IDKeyboardDeviceNotifyMsg) All the data your hook will receive is read-only and must not be modified. Your hook code will be executed on the context of the task which is responsible for change that has taken place. Do not expect much stack space to be available, do not break a Forbid() state and complete your work as quickly as possible. While your hook code is invoked, normal event processing will be on hold. The hooks will be invoked only if the change that was triggered could be completed successfully. SEE ALSO input.device/IND_IMMEDIATEADDNOTIFY input.device/IND_REMOVENOTIFY input.device/IND_GETHANDLERLIST input.device/IND_GETHANDLERLIST NAME IND_GETHANDLERLIST -- Obtain a pointer to the list of input handlers (V50) FUNCTION This command will retrieve a pointer to the list of input handlers currently installed. This list is read-only and should be examined only under Forbid() conditions. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to OpenDevice io_Command IND_GETHANDLERLIST io_Flags IOB_QUICK set if quick I/O is possible io_Length must be set to sizeof(struct List **) io_Data the address of a 'struct List *' pointer to be filled in NOTES This command will fill in a List pointer, not a List structure itself. Thus you would invoke it as follows: struct List * handler_list; ior->io_Command = IND_GETHANDLERLIST; ior->io_Flags = IOF_QUICK; ior->io_Length = sizeof(&handler_list); ior->io_Data = &handler_list; Forbid(); /* IND_GETHANDLERLIST is guaranteed not to break a Forbid() if invoked using quick I/O */ BeginIO(ior); if(ior->io_Error == 0) { /* access the list, and quickly, please! */ } Permit(); This command always executes immediately. input.device/IND_GETKDEVICE input.device/IND_GETKDEVICE NAME IND_GETKDEVICE -- Query the name and unit number of the device keyboard input events are collected from (V50) FUNCTION The default source of keyboard events is keyboard.device, unit 0. But this need not be the case. This command will identify the device name and unit number in use. IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command IND_GETKDEVICE io_Data points to a 'struct InputDeviceOption' which will be filled in io_Length must be set to sizeof(struct InputDeviceOption) NOTES Before this command is invoked, the Name and NameSize fields of the InputDeviceOption structure must be filled in. The Name field must point to a buffer to store the device name in. The NameSize field must contain the number of bytes in the name buffer, including the terminating NUL. If successful, this command will copy the name of the current keyboard device to the Name buffer and put the current keyboard device unit into the Unit field. input.device/IND_GETMDEVICE input.device/IND_GETMDEVICE NAME IND_GETMDEVICE -- Query the name and unit number of the device mouse input events are collected from (V50) FUNCTION The default source of mouse events is gameport.device, unit 0. But this need not be the case. This command will identify the device name and unit number in use. IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command IND_GETMDEVICE io_Data points to a 'struct InputDeviceOption' which will be filled in io_Length must be set to sizeof(struct InputDeviceOption) NOTES Before this command is invoked, the Name and NameSize fields of the InputDeviceOption structure must be filled in. The Name field must point to a buffer to store the device name in. The NameSize field must contain the number of bytes in the name buffer, including the terminating NUL. If successful, this command will copy the name of the current mouse device to the Name buffer and put the current mouse device unit into the Unit field. The unit field corresponds to the mouse port number. input.device/IND_GETPERIOD input.device/IND_GETPERIOD NAME IND_GETPERIOD -- Get the key repeat period (V50) FUNCTION This command retrieves the period at which a repeating key repeats. IO REQUEST - a TimeRequest Request.io_Message mn_ReplyPort set if quick I/O is not possible Request.io_Device preset by the call to OpenDevice Request.io_Unit preset by the call to OpenDevice Request.io_Command IND_GETPERIOD Request.io_Flags IOB_QUICK set if quick I/O is possible RESULTS Time.Seconds the repeat period seconds Time.Microseconds the repeat period microseconds NOTES This command always executes immediately. input.device/IND_GETTHRESH input.device/IND_GETTHRESH NAME IND_GETTHRESH -- Get the key repeat threshold (V50) FUNCTION This command retrieves 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). IO REQUEST - a TimeRequest Request.io_Message mn_ReplyPort set if quick I/O is not possible Request.io_Device preset by the call to OpenDevice Request.io_Unit preset by the call to OpenDevice Request.io_Command IND_GETTHRESH Request.io_Flags IOB_QUICK set if quick I/O is possible RESULTS Time.Seconds the threshold seconds Time.Microseconds the threshold microseconds NOTES This command always executes immediately. input.device/IND_IMMEDIATEADDNOTIFY input.device/IND_IMMEDIATEADDNOTIFY NAME IND_IMMEDIATEADDNOTIFY -- Add a hook which will be invoked whenever an input.device configuration option is changed. The hook will be invoked on the current configuration first. (V50) FUNCTION This command is functionally identical to IND_ADDNOTIFY, except that once the hook has been installed, it will be invoked with the current input.device settings. This is similar in operation to the dos.library/StartNotify call with a NotifyRequest that has the NRF_NOTIFY_INITIAL flag set. IO REQUEST Identical to IND_ADDNOTIFY SEE ALSO input.device/IND_ADDNOTIFY input.device/IND_REMOVENOTIFY dos.library/StartNotify input.device/IND_REMHANDLER input.device/IND_REMHANDLER NAME IND_REMHANDLER -- Remove an input handler from the device FUNCTION Remove a function previously added to the list of handler functions. IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command IND_REMHANDLER io_Data a pointer to the interrupt structure. NOTES This command is not immediate input.device/IND_REMOVENOTIFY input.device/IND_REMOVENOTIFY NAME IND_REMOVENOTIFY -- Remove a hook previously installed with the IND_ADDNOTIFY command. (V50) FUNCTION This command is the counterpart to IND_ADDNOTIFY and the related IND_IMMEDIATEADDNOTIFY command. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to OpenDevice io_Command IND_ADDNOTIFY io_Flags IOB_QUICK set if quick I/O is possible io_Length must be set to sizeof(struct Hook) io_Data the address of the Hook to be removed. SEE ALSO input.device/IND_ADDNOTIFY input.device/IND_IMMEDIATEADDNOTIFY input.device/IND_SETKDEVICE input.device/IND_SETKDEVICE NAME IND_SETKDEVICE -- Choose the device to collect keyboard input events from (V50) FUNCTION The default source of keyboard events is keyboard.device, unit 0. To switch to a different device, specify the name and unit number to open. IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command IND_SETKDEVICE io_Data points to a 'struct InputDeviceOption' which identifies the name of the device to use and the unit number io_Length must be set to sizeof(struct InputDeviceOption) NOTES This command can fail. In this case, the input.device will attempt to reopen keyboard.device unit 0 and return an error code. The device driver to produce keyboard events must work exactly like keyboard.device. In particular, this means that the input.device must be able to queue a read request for more than one input event at a time. The following fields of the InputDeviceOption structure must be filled in: Name Unit The NameSize field will be ignored. input.device/IND_SETMDEVICE input.device/IND_SETMDEVICE NAME IND_SETMDEVICE -- Choose the device to collect mouse input events from (V50) FUNCTION The default source of mouse events is gameport.device, unit 0. To switch to a different device, specify the name and unit number to open. IO REQUEST io_Message mn_ReplyPort set io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command IND_SETMDEVICE io_Data points to a 'struct InputDeviceOption' which identifies the name of the device to use and the unit number io_Length must be set to sizeof(struct InputDeviceOption) NOTES This command can fail. In this case, the input.device will attempt to reopen gameport.device unit 0 and return an error code. The device driver to produce mouse events must work exactly like gameport.device. In particular, this means that the input.device must be able to queue a read request for more than one input event at a time. The following fields of the InputDeviceOption structure must be filled in: Name Unit The NameSize field will be ignored. input.device/IND_SETMPORT input.device/IND_SETMPORT NAME IND_SETMPORT -- Set the current mouse port FUNCTION This command sets the gameport port at which the mouse is connected. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to 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. input.device/IND_SETMTRIG input.device/IND_SETMTRIG NAME IND_SETMTRIG -- Set the conditions for a mouse port report FUNCTION This command sets what conditions must be met by a mouse before a pending Read request will be satisfied. The trigger specification is that used by the gameport device. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to 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 SEE ALSO devices/gameport.h input.device/IND_SETMTYPE input.device/IND_SETMTYPE NAME IND_SETMTYPE -- Set the current mouse port controller type FUNCTION This command sets the type of device at the mouse port, so the signals at the port may be properly interpreted. IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to 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 input.device/IND_SETPERIOD input.device/IND_SETPERIOD NAME IND_SETPERIOD -- Set the key repeat period FUNCTION This command sets the period at which a repeating key repeats. IO REQUEST - a TimeRequest Request.io_Message mn_ReplyPort set if quick I/O is not possible Request.io_Device preset by the call to OpenDevice Request.io_Unit preset by the call to OpenDevice Request.io_Command IND_SETPERIOD Request.io_Flags IOB_QUICK set if quick I/O is possible Time.Seconds the repeat period seconds Time.Microseconds the repeat period microseconds NOTES This command always executes immediately. input.device/IND_SETTHRESH input.device/IND_SETTHRESH NAME IND_SETTHRESH -- Set the key repeat threshold FUNCTION 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). IO REQUEST - a TimeRequest Request.io_Message mn_ReplyPort set if quick I/O is not possible Request.io_Device preset by the call to OpenDevice Request.io_Unit preset by the call to OpenDevice Request.io_Command IND_SETTHRESH Request.io_Flags IOB_QUICK set if quick I/O is possible Time.Seconds the threshold seconds Time.Microseconds the threshold microseconds NOTES This command always executes immediately. input.device/IND_WRITEEVENT input.device/IND_WRITEEVENT NAME IND_WRITEEVENT -- Propagate an input event to all handlers FUNCTION IO REQUEST io_Message mn_ReplyPort set if quick I/O is not possible io_Device preset by the call to OpenDevice io_Unit preset by the call to OpenDevice io_Command IND_WRITEEVENT io_Flags IOB_QUICK set if quick I/O is possible io_Length must 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) NOTES 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. SEE ALSO devices/inputevent.h input.device/PeekQualifier input.device/PeekQualifier NAME PeekQualifier -- get the input device's current qualifiers (V36) SYNOPSIS qualifier = PeekQualifier() UWORD PeekQualifier( VOID ); FUNCTION This function takes a snapshot of what the input device thinks the current qualifiers are. RESULTS 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 NOTE This function is new for V36. SEE ALSO devices/inputevent.h