This is an old version from the tos.hyp. The new is on GitHub!

HomeVDIInquire functionsEscape functions

7.7 Input functions

The input functions enable a program to inquire the status of the keyboard and mouse, taking into consideration the input modes. They also offer routines for linking in timer and mouse interrupts. The following functions are available:

• v_hide_c Hides graphic mouse cursor
• v_show_c Displays (unhides) graphic mouse cursor
• vex_butv Moves service routine for mouse-button interrrupts
• vex_curv Draws customized mouse pointer
• vex_motv Moves service routine for mouse movement interrupts
• vex_timv Moves service routine for timer interrupts
• vex_wheelv Service routine for mouse wheel events
• vq_key_s Inquires Shift-key status
• vq_mouse Gets position of graphic cursor
• vrq_choice Awaits keypress (REQUEST)
• vrq_locator Gets position of graphic cursor (REQUEST)
• vrq_string Reads in string from keyboard (REQUEST)
• vrq_valuator Supervision of input devices (REQUEST)
• vsc_form Defines graphic cursor
• vsin_mode Switches between REQUEST and SAMPLE mode
• vsm_choice Gets the key pressed last (SAMPLE)
• vsm_locator Gets position of the graphic cursor (SAMPLE)
• vsm_string Reads in string from keyboard (SAMPLE)
• vsm_valuator Gets the status of input devices (SAMPLE)

Note: These functions are intended primarily for the owner of the physical workstation, i.e. for the AES. Programs should (provided there are no pressing needs for a different procedure) always inquire mouse and keyboard events through the AES's event functions, because otherwise inputs intended for other applications may be intercepted.

See also: VDI workstations   Style guidelines

7.7.1 vex_butv

Name: »Exchange button change vector« - Adapt the interrupt vector for a mouse button press.
Opcode: 125
Syntax: void vex_butv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Description: The call vex_butv permits the installation of a custom routine that is called by the VDI each time a mouse button is pressed. The following apply:
Parameter Meaning
   
handle Workstation identifier
pusrcode Address of the new routine
psavcode Address of the old routine


On entry to pusrcode, the mouse status is contained in register d0 (in the same format as the button return value in vq_mouse). The subroutine must save and restore modified registers and call the old status routine.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   vex_timv   vex_motv   vex_curv

7.7.2 Bindings for vex_butv

C: void vex_butv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Binding: 
void vex_butv (int16_t handle, int16_t (*pusrcode)(),
               int16_t (**psavcode)())
{
   contrl[0] = 125;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;
   contrl[7..8] = pusrcode;

   vdi ();

   *psavcode = contrl[9..10];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 125 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
contrl+14 contrl[7,8] pusrcode
contrl+18 contrl[9,10] psavcode

7.7.3 vex_curv

Name: »Exchange cursor change vector« - Adapt the interrupt vector for cursor pointer drawing.
Opcode: 127
Syntax: void vex_curv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Description: The call vex_curv permits the installation of a routine that is called each time a mouse pointer is drawn, allowing a customized mouse pointer form to replace that drawn by the system. The following apply:
Parameter Meaning
   
handle Workstation identifier
pusrcode Address of the new routine
psavcode Address of the old routine


The routine will be called if the mouse is moved and d0.w/d1.w contain the coordinates of the mouse cursor. The subroutine must save and restore modified registers and call the old interrupt routine.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   vex_timv   vex_butv   vex_motv

7.7.4 Bindings for vex_curv

C: void vex_curv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Binding: 
void vex_curv (int16_t handle, int16_t (*pusrcode)(),
               int16_t (**psavcode)())
{
   contrl[0] = 127;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;
   contrl[7..8] = pusrcode;

   vdi ();

   *psavcode = contrl[9..10];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 127 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
contrl+14 contrl[7..8] pusrcode
contrl+18 contrl[9..10] psavcode

7.7.5 vex_motv

Name: »Exchange mouse movement vector« - Adapt the interrupt vector for mouse movements.
Opcode: 126
Syntax: void vex_motv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Description: The call vex_motv permits the installation of a custom routine that is called by the VDI each time a mouse pointer is moved. The following apply:
Parameter Meaning
   
handle Workstation identifier
pusrcode Address of the new routine
psavcode Address of the old routine


On entry to pusrcode, the mouse's X and Y location is contained in registers d0 and d1 respectively. The subroutine must save and restore modified registers and call the old status routine.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   vex_timv   vex_butv   vex_curv

7.7.6 Bindings for vex_motv

C: void vex_motv ( int16_t handle, int16_t (*pusrcode)(), int16_t (**psavcode)() );
Binding: 
void vex_motv (int16_t handle, int16_t (*pusrcode)(),
               int16_t (**psavcode)())
{
   contrl[0] = 126;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;
   contrl[7..8] = pusrcode;

   vdi ();

   *psavcode = contrl[9..10];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 126 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
contrl+14 contrl[7..8] pusrcode
contrl+18 contrl[9..10] psavcode

7.7.7 vex_timv

Name: »Exchange timer interrupt vector« - Adapt the interrupt vector for the timer.
Opcode: 118
Syntax: void vex_timv ( int16_t handle, int16_t (*tim_addr)(), int16_t (**otim_addr)(), int16_t *tim_conv );
Description: The call vex_timv permits the installation of a user-defined routine that will be called at each timer tick (currently every 50 milliseconds). The following apply:
Parameter Meaning
   
handle Workstation identifier
tim_addr Address of the new timer routine
otim_addr Address of the old timer routine
tim_conv Interrupt interval in ms


The subroutine has to save and restore modified registers and call the old timer routine.

Notes: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.

As this vector is jumped through frequently, the new routine should be very simple to avoid degrading the system performance.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   vex_butv   vex_motv   vex_curv

7.7.8 Bindings for vex_timv

C: void vex_timv ( int16_t handle, int16_t (*tim_addr)(), int16_t (**otim_addr)(), int16_t *tim_conv );
Binding: 
void vex_timv (int16_t handle, int16_t (*tim_addr)(),
               int16_t (**otim_addr)(), int16_t *tim_conv)
{
   contrl[0] = 118;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;
   contrl[7..8] = tim_addr;

   vdi ();

   *otim_addr = contrl[9..10];
   *tim_conv  = intout[0];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 118 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
contrl+14 contrl[7..8] tim_addr
contrl+18 contrl[9..10] otim_addr
intout intout[0] tim_conv

7.7.9 vex_wheelv

Name: »Exchange wheel interrupt vector« - Adapt the interrupt vector for the mouse wheel.
Opcode: 134
Syntax: void vex_wheelv ( int16_t handle, void *new, void **old );
Description: The call vex_wheelv installs a routine which is called by the VDI every time a mouse wheel event occurs. d0.w contain the wheel_number, d1.w contain the wheel_amount of the wheel from the mouse. The subroutine must save and restore modified registers and call the old interrupt routine.
Parameter Meaning
   
handle Workstation identifier
new Address of the new routine
old Address of the old routine
Return value: The function does not return a result.
Availability: As of MilanTOS 4.08 Release 5.10.2002, not yet documented, internals may still change.
Group: Input functions
See also: Binding   vex_butv   vex_motv   vex_curv   vex_timv

7.7.10 Bindings for vex_wheelv

C: void vex_wheelv ( int16_t handle, void *new, void **old );
Binding: 
void vex_wheelv ( int16_t handle, void *new, void **old )
{
   contrl[0] = 134;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;
   contrl[7..8] = new;

   vdi ();

   *old = contrl[9..10];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 134 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
contrl+14 contrl[7..8] new
contrl+18 contrl[9..10] old

7.7.11 vq_key_s

Name: »Sample keyboard state information« - Obtain the status of the Shift etc. keys.
Opcode: 128
Syntax: void vq_key_s ( int16_t handle, int16_t *pstatus );
Description: The call vq_key_s checks the status of the 'special' keys (L & R Shift, Control, Alternate) of the keyboard. The following apply:
Parameter Meaning
   
handle Workstation identifier
pstatus Keyboard state:
Right Shift = 0x0001
Left Shift = 0x0002
Control key = 0x0004
Alternate key = 0x0008


In GEM programs one should use the AES event functions to ensure that only the keyboard status information intended for one's own application is obtained.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES. Therefore it is better to fall back to using graf_mkstate or the event functions instead.
Return value: The function does not return a result.
Availability: Supported by all Atari computers.
Group: Input functions
See also: Binding   evnt_button

7.7.12 Bindings for vq_key_s

C: void vq_key_s ( int16_t handle, int16_t *pstatus );
Binding: 
void vq_key_s (int16_t handle, int16_t *pstatus)
{
   contrl[0] = 128;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

   *pstatus = intout[0];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 128 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
intout intout[0] pstatus

7.7.13 vq_mouse

Name: »Sample mouse button state« - Obtain position and status of the mouse buttons.
Opcode: 124
Syntax: void vq_mouse ( int16_t handle, int16_t *pstatus, int16_t *x, int16_t *y );
Description: The call vq_mouse obtains the current cursor position and the current status of the mouse buttons. The following apply:
Parameter Meaning
   
handle Workstation identifier
pstatus Mouse button state
Bit-0 = Left mouse button
Bit-1 = Right mouse button (etc.)
x X-position of cursor
y Y-position of cursor


In GEM programs one should use the AES function graf_mkstate to ensure that only the information about the position and state of the mouse buttons intended for one's own application is obtained.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES. Therefore it is better to fall back to using graf_mkstate or the event functions instead.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   graf_mkstate

7.7.14 Bindings for vq_mouse

C: void vq_mouse ( int16_t handle, int16_t *pstatus, int16_t *x, int16_t *y );
Binding: 
void vq_mouse (int16_t handle, int16_t *pstatus, int16_t *x,
               int16_t *y)
{
   contrl[0] = 124;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

   *pstatus = intout[0];
   *x = ptsout[0];
   *y = ptsout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 124 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 1 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
intout intout[0] pstatus
ptsout ptsout[0] x
ptsout+2 ptsout[1] y

7.7.15 vrq_choice

Name: »Input choice, Request mode« - Return the status of the 'choice' device (e.g. function keys when one was pressed).
Opcode: 30
Syntax: void vrq_choice ( int16_t handle, int16_t ch_in, int16_t *ch_out );
Description: The call vrq_choice ascertains the actuation of a 'choice' device (e.g. function key) in REQUEST mode. The following apply:
Parameter Meaning
   
handle Workstation identifier
ch_in Starting value for choice device
ch_out Selected key or code number


The number of function keys depends on each individual device. If another key is pressed, the corresponding code number will be returned.
Return value: The function does not return a result.
Availability: Although the function is implemented in ROM, it does not seem to work in any way. The function is not supported by all device drivers.

The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Group: Input functions
See also: Binding   vsm_choice   vsin_mode

7.7.16 Bindings for vrq_choice

C: void vrq_choice ( int16_t handle, int16_t ch_in, int16_t *ch_out );
Binding: 
void vrq_choice (int16_t handle, int16_t ch_in, int16_t *ch_out)
{
   intin[0] = ch_in;

   contrl[0] = 30;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();

   *ch_out = intout[0];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 30 # Function Opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] ch_in
intout intout[0] ch_out

7.7.17 vrq_locator

Name: »Input locator, Request mode« - Obtain the mouse position when a key was pressed.
Opcode: 28
Syntax: void vrq_locator ( int16_t handle, int16_t x, int16_t y, int16_t *xout, int16_t *yout, int16_t *term );
Description: The call vrq_locator ascertains or sets the position of the graphic cursor (the 'locator') in REQUEST mode. The following apply:
Parameter Meaning
   
handle Workstation identifier
x Initial X-coordinate, and
y Y-coordinate of the graphic cursor
xout Final X-coordinate, and
yout Y-coordinate of graphic cursor on return
term The low byte contains a character terminator. For keyboard-terminated locator input, this is the ASCII character code of the key struck to terminate input. For nonkeyboard-terminated input (tablet, mouse, and so on), valid locator terminators begin with 20 Hex (space) and increase from there.


The user only gets the result when a key is pressed. The graphic cursor is always visible on the screen at the specified position in the current form. One should note that any desired key (including the mouse buttons) may be pressed.

Normally the movement of the graphic cursor takes place in large steps when the cursor keys are pressed, or in small steps when these are pressed in combination with the Shift key. On the Atari, however, the Alternate key is required as well.
Return value: The function does not return a result.
Availability: The function is not supported by all device drivers. The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Group: Input functions
See also: Binding   vsm_locator   vsin_mode

7.7.18 Bindings for vrq_locator

C: void vrq_locator ( int16_t handle, int16_t x, int16_t y, int16_t *xout, int16_t *yout, int16_t *term );
Binding: 
void vrq_locator (int16_t handle, int16_t x, int16_t y,
                  int16_t *xout, int16_t *yout, int16_t *term)
{
   ptsin[0] = x;
   ptsin[1] = y;

   contrl[0] = 28;
   contrl[1] = 1;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

   *xout = ptsout[0];
   *yout = ptsout[1];
   *term = intout[0];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 28 # Function Opcode
contrl+2 contrl[1] 1 # Entry in ptsin
contrl+4 contrl[2] 1 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
ptsin ptsin[0] x
ptsin+2 ptsin[1] y
intout intout[0] term
ptsout ptsout[0] xout
ptsout+2 ptsout[1] yout

7.7.19 vrq_string

Name: »Input string, Request mode« - Read in a string in REQUEST mode.
Opcode: 31
Syntax: void vrq_string ( int16_t handle, int16_t max_length, int16_t echo_mode, int16_t *echo_xy, int8_t *string );
Description: The call vrq_string reads a string from the 'string' device (normally the keyboard) in REQUEST mode into a buffer, with an optional echo to the screen. The following apply:
Parameter Meaning
   
handle Workstation identifier
max_length Maximum string length
echo_mode Mode:
0 = No echo
1 = Echo input characters to specified position
echo_xy[0] X-coordinate, and
echo_xy[1] Y-coordinate of echo area
string Address of character string


The echo output is not available on all devices; the text attributes will be paid regard to.

If max_length is negative, the absolute value is considered to be the maximum length and scancodes are returned instead of ASCII values.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function does not return a result.
Availability: This call is not guaranteed to be available with any driver and its use should therefore be restricted.
Group: Input functions
See also: Binding   vswr_mode   vs_color   vst_alignment   vst_height   vst_point   vst_rotation   vst_font   vst_color   vst_effects   vsm_string

7.7.20 Bindings for vrq_string

C: void vrq_string ( int16_t handle, int16_t max_length, int16_t echo_mode, int16_t *echo_xy, int8_t *string );
Binding: 
void vrq_string (int16_t handle, int16_t max_length,
                 int16_t echo_mode, int16_t *echo_xy,
                 int8_t *string)
{
   int16_t tmp;

   intin[0] = max_length;
   intin[1] = echo_mode;
   ptsin[0..1] = echo_xy[0..1];

   contrl[0] = 31;
   contrl[1] = 1;
   contrl[3] = 2;
   contrl[6] = handle;

   vdi ();

   for (tmp = 0; tmp < contrl[4]; tmp++)
      *string++ = intout[tmp];

   *string = 0;
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 31 # Function opcode
contrl+2 contrl[1] 1 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] n # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] max_length
intin+2 intin[1] echo_mode
ptsin ptsin[0..1] echo_xy[0..1]
intout intout[0..n-1] string[0..n-1]

7.7.21 vrq_valuator

Name: »Input valuator, Request mode« - Obtain value changes of input devices.
Opcode: 29
Syntax: void vrq_valuator ( int16_t handle, int16_t valuator_in, int16_t *valuator_out, int16_t *terminator );
Description: The call vrq_valuator obtains a value change that is the result of various key presses (on the valuator device) until a terminating character is entered in REQUEST mode. The following apply:
Parameter Meaning
   
handle Workstation identifier
valuator_in Initial value of valuator device
valuator_out Output value of valuator
terminator Actuated key causing termination


All values lie between 1 and 100. Typcal keys for value changes are cursor-up or cursor-down. With these one gets the following value changes to the value current at the time:

Keypress Value
Cursor-up + 10
Cursor-down - 10
Shift + Cursor-up + 01
Shift + Cursor-down - 01
Return value: The function does not return a result.
Availability: The function is not supported by all device drivers (also not in the ROM). The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Group: Input functions
See also: Binding   vsm_valuator   vsin_mode

7.7.22 Bindings for vrq_valuator

C: void vrq_valuator ( int16_t handle, int16_t valuator_in, int16_t *valuator_out, int16_t *terminator );
Binding: 
void vrq_valuator (int16_t handle, int16_t valuator_in,
                   int16_t *valuator_out, int16_t *terminator)
{
   intin[0] = valuator_in;

   contrl[0] = 29;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();

   *valuator_out = intout[0];
   *terminator   = intout[1];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 29 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 2 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] valuator_in
intout intout[0] valuator_out
intout+2 intout[1] terminator

7.7.23 vsc_form

Name: »Set mouse form« - Set the mouse pointer shape.
Opcode: 111
Syntax: void vsc_form ( int16_t handle, int16_t *pcur_form );
Description: The call vsc_form permits the definition of the shape of the mouse pointer, which is stored in the MFORM structure. The following apply:
Parameter Meaning
   
handle Workstation identifier
pcur_form[0] X-coordinate, and
pcur_form[1] Y-coordinate of hot-spot
pcur_form[2] Number of planes, must be 1
pcur_form[3] Colour index of background mask (should be 0)
pcur_form[4] Colour index of foreground mask (should be 1)
pcur_form[05..20] Definition of background mask
pcur_form[21..36] Definition of foreground mask


Each mask is dimensioned as a 16-WORD field each of 16 bits. Bit 15 of the first WORD is here the top left corner of the mask, and bit 0 of WORD 16 is the bottom right corner.

Under hot-spot one understands the exact position of the active part of the graphic cursor. With an arrow this corresponds to the arrow's tip, with a cross it is the crossing-point. The coordinates are specified relative to the top left corner of the mask.

For setting the mouse pointer shape, all GEM programs should use the AES function graf_mouse. Otherwise the mouse pointer shape management of the AES will become permanently confused.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES. Therefore it is better to fall back to using graf_mouse instead.

Under NVDI it is also possible to obtain the current shape of the mouse pointer (see Binding).
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   graf_mouse   MFORM

7.7.24 Bindings for vsc_form

C: void vsc_form ( int16_t handle, int16_t *pcur_form );
Binding: 
void vsc_form (int16_t handle, int16_t *pcur_form)
{
   intin[0..36] = pcur_form[0..36];

   contrl[0] = 111;
   contrl[1] = 0;
   contrl[3] = 37;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 111 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 37 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0..36] pcur_form[0..36]


Note: Under NVDI it is also possible to obtain the current shape of the mouse pointer. The assignment of the input/output fields for this are as follows:
contrl[0] = 111;
contrl[1] = 0;
contrl[2] = 0;
contrl[3] = 0;
contrl[4] = 37;
contrl[6] = handle;
intout[0..36] = pcur_form[0..36];

7.7.25 vsin_mode

Name: »Set input mode« - Switch between REQUEST and SAMPLE mode.
Opcode: 33
Syntax: int16_t vsin_mode ( int16_t handle, int16_t dev_type, int16_t mode );
Description: The call vsin_mode sets the input mode to REQUEST or SAMPLE for the specified device.
Parameter Meaning
   
handle Workstation identifier
dev_type Type of input device:
1 = Position input (mouse)
2 = Value-altering devices (cursor)
3 = 'Choice' devices (function keys)
4 = Alphanumeric devices (keyboard)
mode Requested input mode:
1 = Request
2 = Sample


In REQUEST mode the input device waits for an input, in SAMPLE mode only the status of the position of the input device will be returned.

Notes: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.

Using this function will cause the AES to operate improperly!
Return value: The function returns the selected input mode.
Availability: Supported in ROM by all Atari computers.
Group: Input functions
See also: Binding

7.7.26 Bindings for vsin_mode

C: int16_t vsin_mode ( int16_t handle, int16_t dev_type, int16_t mode );
Binding: 
int16_t vsin_mode (int16_t handle, int16_t dev_type, int16_t mode)
{
   intin[0] = dev_type;
   intin[1] = mode;

   contrl[0] = 33;
   contrl[1] = 2;
   contrl[3] = 2;
   contrl[6] = handle;

   vdi ();

   /* Warning: Not all bindings provide a
      return value !!! */

   return ( intout[0] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 33 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] 1 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] dev_type
intin+2 intin[1] mode
intout intout[0] Return Value

7.7.27 vsm_choice

Name: »Input choice, Sample mode« - Ascertain which function key was pressed last.
Opcode: 30
Syntax: int16_t vsm_choice ( int16_t handle, int16_t *choice );
Description: The call vsm_choice obtains the current value of the 'choice' device, normally the number of the last pressed function key. The folowing apply:
Parameter Meaning
   
handle Workstation identifier
choice Pressed function key or 0, if none such was struck


The number of function keys depends on the device in each case. If another key has been activated, then the associated code number will be returned.
Return value: The function returns the selection status (0 = no key, 1 = key pressed).
Availability: Although the function is implemented in ROM, it does not seem to work properly. The function is not supported by all device drivers. The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Group: Input functions
See also: Binding   vrq_choice   vsin_mode

7.7.28 Bindings for vsm_choice

C: int16_t vsm_choice ( int16_t handle, int16_t *choice );
Binding: 
int16_t vsm_choice ( int16_t handle, int16_t *choice )
{
   contrl[0] = 30;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

   *choice = intout[0];
   return ( contrl[4] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 30 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] status # Entry in intout
contrl+12 contrl[6] handle
intout intout[0] choice

7.7.29 vsm_locator

Name: »Input locator, Sample mode« - Obtain the position of the graphic cursor.
Opcode: 28
Syntax: int16_t vsm_locator ( int16_t handle, int16_t x, int16_t y, int16_t *xout, int16_t *yout, int16_t *term );
Description: The call vsm_locator sets or obtains the position of the 'locator' (graphic cursor) in SAMPLE mode. The following apply:
Position Meaning
   
handle Workstation identifier
x Initial X-coordinate, and
y Y-coordinate of the graphic cursor
xout Final X-coordinate, and
yout Y-coordinate of graphic cursor on return
term In the low byte, the ASCII code of the terminating key will be filled in; since special keys (mouse buttons, etc.) are assigned values from 32 (left button) and 33 (right button), they cannot be differentiated directly from keys of the keyboard


This function does not make the graphic cursor visible; key presses or cursor movements will only be reported if they have actually taken place.

Notes: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.

Using this call will confuse the AES.
Return value: The function returns coded information about whether the cursor position has changed (bit 0 set) and whether a key was pressed (bit 1 set).
Availability: The function is not supported by all device drivers.
Group: Input functions
See also: Binding   vrq_locator   vsin_mode

7.7.30 Bindings for vsm_locator

C: int16_t vsm_locator ( int16_t handle, int16_t x, int16_t y, int16_t *xout, int16_t *yout, int16_t *term );
Binding: 
int16_t vsm_locator (int16_t handle, int16_t x, int16_t y,
                     int16_t *xout, int16_t *yout,
                     int16_t *term)
{
   ptsin[0] = x;
   ptsin[1] = y;

   contrl[0] = 28;
   contrl[1] = 1;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();

   *xout = ptsout[0];
   *yout = ptsout[1];
   *term = intout[0];

   return ( (contrl[4] << 1) | (contrl[2]) );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 28 # Function opcode
contrl+2 contrl[1] 1 # Entry in ptsin
contrl+4 contrl[2] 0 oder 1 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 oder 1 # Entry in intout
contrl+12 contrl[6] handle
ptsin ptsin[0] x
ptsin+2 ptsin[1] y
intout intout[0] term
ptsout ptsout[0] xout
ptsout+2 ptsout[1] yout

7.7.31 vsm_string

Name: »Input string, Sample mode« - Read in a string in SAMPLE mode.
Opcode: 31
Syntax: int16_t vsm_string ( int16_t handle, int16_t max_length, int16_t echo_mode, int16_t *echo_xy, int8_t *string );
Description: The call vsm_string retrieves input from the 'string' device (normally the keyboard) in SAMPLE mode into a buffer, with an optional echo to the screen. The following apply:
Parameter Meaning
   
handle Workstation identifier
max_length Maximum string length
echo_mode Mode:
0 = No echo
1 = Echo input characters
echo_xy[0] X-coordinate, and
echo_xy[1] Y-coordinate of echo area
string Address of character string buffer


The echo output is not available on all devices; the text attributes will be paid regard to.

If max_length is negative, the absolute value is considered to be the maximum length and scancodes are returned instead of ASCII values, occupying the full WORD in intout rather than just the lower 8 bits.

The input of a character string is terminated by:
  • A carriage return is encountered
  • The intout buffer is full
  • Data is no longer available


If the character string is basically to be terminated with Return, then you should use REQUEST mode with vrq_string.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function returns either the number of read in characters, or NULL if the input was terminated by an invalid key. The text that was input lies in string.
Availability: The function is not supported by all device drivers.
Group: Input functions
See also: Binding   vswr_mode   vs_color   vst_alignment   vst_height   vst_point   vst_rotation   vst_font   vst_color   vst_effects   vrq_string

7.7.32 Bindings for vsm_string

C: int16_t vsm_string ( int16_t handle, int16_t max_length, int16_t echo_mode, int16_t *echo_xy, int8_t *string );
Binding: 
int16_t vsm_string (int16_t handle, int16_t max_length,
                    int16_t echo_mode, int16_t *echo_xy,
                    int8_t *string)
{
   int16_t tmp;

   intin[0] = max_length;
   intin[1] = echo_mode;
   ptsin[0..1] = echo_xy[0..1];

   contrl[0] = 31;
   contrl[1] = 1;
   contrl[3] = 2;
   contrl[6] = handle;

   vdi ();

   for (tmp = 0; tmp < contrl[4]; tmp++)
      *string++ = intout[tmp];

   *string = 0;
   return ( contrl[4] );
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 31 # Function opcode
contrl+2 contrl[1] 1 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 2 # Entry in intin
contrl+8 contrl[4] max_length # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] max_length
intin+2 intin[1] echo_mode
ptsin ptsin[0..1] echo_xy[0..1]
intout intout[0..n-1] string[0..n-1]

7.7.33 vsm_valuator

Name: »Input valuator, Sample mode« - Obtain value changes of input devices in SAMPLE mode.
Opcode: 29
Syntax: void vsm_valuator ( int16_t handle, int16_t val_in, int16_t *val_out, int16_t *term, int16_t *status );
Description: The call vsm_valuator retrieves value changes from the 'valuator' device in SAMPLE mode. The following apply:
Parameter Meaning
   
handle Workstation identifier
val_in Initial value
val_out Final value
term ASCII-code of pressed key
status Evaluation:
0 = No change
1 = Value changed
2 = Key pressed


Values between 1 and 100 are returned if a corresponding event has occurred; otherwise no value is returned.

Note: The function is not supported by all device drivers (also not in the ROM). The input functions of the VDI work only on the physical workstation, which is normally used by the AES.
Return value: The function does not return a result.
Availability: The function is not guaranteeed to be available with any driver and its use should therefore be restricted.
Group: Input functions
See also: Binding   vrq_valuator   vsin_mode

7.7.34 Bindings for vsm_valuator

C: void vsm_valuator ( int16_t handle, int16_t val_in, int16_t *val_out, int16_t *term, int16_t *status );
Binding: 
void vsm_valuator (int16_t handle, int16_t val_in,
                   int16_t *val_out, int16_t *term,
                   int16_t *status)
{
   intin[0] = val_in;

   contrl[0] = 29;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();

   *val_out = intout[0];
   *term    = intout[1];
   *status  = contrl[4];
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 29 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] status # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] val_in
intout intout[0] val_out
intout+2 intout[1] term

7.7.35 v_hide_c

Name: »Hide cursor« - Switch off graphic cursor.
Opcode: 123
Syntax: void v_hide_c ( int16_t handle );
Description: The call v_hide_c switches the mouse cursor off.

In GEM programs, it is imperative that the AES function graf_mouse is used to switch the mouse cursor on and off.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES. Therefore it is better to fall back to using graf_mouse instead.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   v_show_c

7.7.36 Bindings for v_hide_c

C: void v_hide_c ( int16_t handle );
Binding: 
void v_hide_c (int16_t handle)
{
   contrl[0] = 123;
   contrl[1] = 0;
   contrl[3] = 0;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 123 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 0 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle

7.7.37 v_show_c

Name: »Show cursor« - Switch on graphic cursor.
Opcode: 122
Syntax: void v_show_c ( int16_t handle, int16_t reset );
Description: The call v_show_c 'unhides' the graphic cursor, or cancels the call of the v_hide_c function. The following apply:
Parameter Meaning
   
handle Workstation identifier
reset Flag:
  0 = Ignore number of Hide cursor calls
<>0 = Normal Show cursor functionality (cursor is only displayed if the function has been called the same number of times as v_hide_c)


In GEM programs, it is imperative that the AES function graf_mouse is used to switch the mouse cursor on and off.

Note: The input functions of the VDI work only on the physical workstation, which is normally used by the AES. Therefore it is better to fall back to using graf_mouse instead.
Return value: The function does not return a result.
Availability: Supported by all screen drivers.
Group: Input functions
See also: Binding   v_hide_c   graf_mouse

7.7.38 Bindings for v_show_c

C: void v_show_c ( int16_t handle, int16_t reset );
Binding: 
void v_show_c (int16_t handle, int16_t reset)
{
   intin[0] = reset;

   contrl[0] = 122;
   contrl[1] = 0;
   contrl[3] = 1;
   contrl[6] = handle;

   vdi ();
}
GEM-Arrays:

Address Element Contents
contrl contrl[0] 122 # Function opcode
contrl+2 contrl[1] 0 # Entry in ptsin
contrl+4 contrl[2] 0 # Entry in ptsout
contrl+6 contrl[3] 1 # Entry in intin
contrl+8 contrl[4] 0 # Entry in intout
contrl+12 contrl[6] handle
intin intin[0] reset
HomeVDIInquire functionsEscape functions