Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File7.7.31  vsm_string                                                 TOS

 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