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.

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

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

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

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

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

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

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-position of cursor

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

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:

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

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:

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

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:

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

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:

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

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

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:

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

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] = 0;
   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:

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

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:

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

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:

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

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:

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

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

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

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

VDI

Inquire functions

Escape functions