home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / console.doc < prev    next >
Text File  |  1992-09-01  |  22KB  |  619 lines
  1. TABLE OF CONTENTS
  2.  
  3. console.device/CD_ASKDEFAULTKEYMAP
  4. console.device/CD_ASKKEYMAP
  5. console.device/CD_SETDEFAULTKEYMAP
  6. console.device/CD_SETKEYMAP
  7. console.device/CDInputHandler
  8. console.device/CMD_CLEAR
  9. console.device/CMD_READ
  10. console.device/CMD_WRITE
  11. console.device/OpenDevice
  12. console.device/RawKeyConvert
  13. console.device/CD_ASKDEFAULTKEYMAP         console.device/CD_ASKDEFAULTKEYMAP
  14.  
  15.     NAME
  16.     CD_ASKDEFAULTKEYMAP -- get the current default keymap
  17.  
  18.     FUNCTION
  19.     Fill the io_Data buffer with the current console device
  20.     default keymap, which is used to initialize console unit
  21.     keymaps when opened, and by RawKeyConvert with a null
  22.     keyMap parameter.
  23.  
  24.    IO REQUEST
  25.     io_Message    mn_ReplyPort set if quick I/O is not possible
  26.     io_Device    preset by the call to OpenDevice
  27.     io_Unit        preset by the call to OpenDevice
  28.     io_Command    CD_ASKDEFAULTKEYMAP
  29.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  30.     io_Length    sizeof(*keyMap)
  31.     io_Data        struct KeyMap *keyMap
  32.             pointer to a structure that describes 
  33.             the raw keycode to byte stream conversion.
  34.  
  35.     RESULTS
  36.     This function sets the io_Error field in the IOStdReq, and fills
  37.     the structure pointed to by io_Data with the current device 
  38.     default key map.
  39.  
  40.     BUGS
  41.  
  42.     SEE ALSO
  43.     exec/io.h, devices/keymap.h, devices/console.h
  44.  
  45. console.device/CD_ASKKEYMAP                       console.device/CD_ASKKEYMAP
  46.  
  47.    NAME
  48.     CD_ASKKEYMAP -- Get the current key map structure for this console.
  49.  
  50.     FUNCTION
  51.     Fill the io_Data buffer with the current KeyMap structure in
  52.     use by this console unit.
  53.  
  54.     IO REQUEST INPUT
  55.     io_Message    mn_ReplyPort set if quick I/O is not possible
  56.     io_Device    preset by the call to OpenDevice
  57.     io_Unit        preset by the call to OpenDevice
  58.     io_Command    CD_ASKKEYMAP
  59.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  60.     io_Length    sizeof(*keyMap)
  61.     io_Data        struct KeyMap *keyMap
  62.             pointer to a structure that describes 
  63.             the raw keycode to byte stream conversion.
  64.  
  65.     IO REQUEST RESULT
  66.     This function sets the io_Error field in the IOStdReq, and fills
  67.     the structure the structure pointed to by io_Data with the current
  68.      key map.
  69.  
  70.     SEE ALSO
  71.     exec/io.h, devices/keymap.h, devices/console.h
  72.  
  73. console.device/CD_SETDEFAULTKEYMAP         console.device/CD_SETDEFAULTKEYMAP
  74.  
  75.     NAME
  76.     CD_SETDEFAULTKEYMAP -- set the current default keymap
  77.  
  78.     FUNCTION
  79.     This console command copies/uses the keyMap structure pointed to
  80.     by io_Data to the console device default keymap, which is used
  81.     to initialize console units when opened, and by RawKeyConvert
  82.     with a null keyMap parameter.
  83.  
  84.     IO REQUEST
  85.     io_Message    mn_ReplyPort set if quick I/O is not possible
  86.     io_Device    preset by the call to OpenDevice
  87.     io_Unit        preset by the call to OpenDevice
  88.     io_Command    CD_SETDEFAULTKEYMAP
  89.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  90.     io_Length    sizeof(*keyMap)
  91.     io_Data        struct KeyMap *keyMap
  92.             pointer to a structure that describes 
  93.             the raw keycode to byte stream conversion.
  94.  
  95.     RESULTS
  96.     This function sets the io_Error field in the IOStdReq, and fills
  97.     the current device default key map from the structure pointed to
  98.     by io_Data.
  99.  
  100.     BUGS
  101.     As of V36, this command no longer copies the keymap structure,
  102.     and the keymap must remain in memory until the default key map
  103.     is changed.  In general there is no reason for applications to
  104.     use this command.  The default key map will generally be set by
  105.     the user using a system provided command/tool.
  106.  
  107.     SEE ALSO
  108.     exec/io.h, devices/keymap.h, devices/console.h
  109.  
  110. console.device/CD_SETKEYMAP                       console.device/CD_SETKEYMAP
  111.  
  112.     NAME
  113.     CD_SETKEYMAP -- set the current key map structure for this console
  114.  
  115.     FUNCTION
  116.     Set the current KeyMap structure used by this console unit to
  117.     the structure pointed to by io_Data.
  118.  
  119.     IO REQUEST
  120.     io_Message    mn_ReplyPort set if quick I/O is not possible
  121.     io_Device    preset by the call to OpenDevice
  122.     io_Unit        preset by the call to OpenDevice
  123.     io_Command    CD_SETKEYMAP
  124.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  125.     io_Length    sizeof(*keyMap)
  126.     io_Data        struct KeyMap *keyMap
  127.             pointer to a structure that describes 
  128.             the raw keycode to byte stream conversion.
  129.  
  130.     RESULTS
  131.     This function sets the io_Error field in the IOStdReq, and fills
  132.     the current key map from the structure pointed to by io_Data.
  133.  
  134.     BUGS
  135.  
  136.     SEE ALSO
  137.     exec/io.h, devices/keymap.h, devices/console.h
  138.  
  139. console.device/CDInputHandler                   console.device/CDInputHandler
  140.  
  141.     NAME
  142.     CDInputHandler -- handle an input event for the console device
  143.  
  144.     SYNOPSIS
  145.     events = CDInputHandler(events, consoleDevice)
  146.                a0      a1
  147.  
  148.     FUNCTION
  149.     Accept input events from the producer, which is usually the
  150.     rom input.task.
  151.  
  152.     INPUTS
  153.     events - a pointer to a list of input events.
  154.     consoleDevice - a pointer to the library base address of the
  155.         console device.  This has the same value as ConsoleDevice
  156.         described below.
  157.  
  158.     RESULTS
  159.     events - a pointer to a list of input events not used by this
  160.         handler.
  161.  
  162.     NOTES
  163.     This function is available for historical reasons.  It is
  164.     preferred that input events be fed to the system via the
  165.     WriteEvent command of the input.device.
  166.  
  167.     This function is different from standard device commands in
  168.     that it is a function in the console device library vectors.
  169.     In order to obtain a valid library base pointer for the 
  170.     console device (a.k.a. ConsoleDevice) call
  171.     OpenDevice("console.device", -1, IOStdReq, 0),
  172.     and then grab the io_Device pointer field out of the IOStdReq
  173.     and use as ConsoleDevice.
  174.  
  175.     BUGS
  176.  
  177.     SEE ALSO
  178.     input.device
  179.  
  180. console.device/CMD_CLEAR                             console.device/CMD_CLEAR
  181.  
  182.     NAME
  183.     CMD_CLEAR -- Clear console input buffer.
  184.  
  185.     FUNCTION
  186.     Remove from the console input buffer any reports waiting to
  187.     satisfy read requests.
  188.  
  189.     IO REQUEST INPUT
  190.     io_Message    mn_ReplyPort set if quick I/O is not possible
  191.     io_Device    preset by the call to OpenDevice
  192.     io_Unit        preset by the call to OpenDevice
  193.     io_Command    CMD_CLEAR
  194.     io_Flags    IOB_QUICK set if quick I/O is possible, else 0
  195.  
  196.     SEE ALSO
  197.     exec/io.h, devices/console.h
  198.  
  199. console.device/CMD_READ                               console.device/CMD_READ
  200.  
  201.    NAME
  202.     CMD_READ -- return the next input from the keyboard
  203.  
  204.    FUNCTION
  205.     Read the next input, generally from the keyboard.  The form of
  206.     this input is as an ANSI byte stream: i.e. either ASCII text
  207.     or control sequences.  Raw input events received by the
  208.     console device can be selectively filtered via the aSRE and aRRE
  209.     control sequences (see the write command).  Keys are converted
  210.     via the keymap associated with the unit, which is modified
  211.     with AskKeyMap and SetKeyMap
  212.  
  213.     If, for example, raw keycodes had been enabled by writing
  214.     <CSI>1{ to the console (where <CSI> is $9B or Esc[), keys
  215.     would return raw keycode reports with the information from
  216.     the input event itself, in the form:
  217.     <CSI>1;0;<keycode>;<qualifiers>;0;0;<seconds>;<microseconds>q
  218.  
  219.     If there is no pending input, this command will not be
  220.     satisfied, but if there is some input, but not as much as can
  221.     fill io_Length, the request will be satisfied with the input
  222.     currently available.
  223.  
  224.     IO REQUEST
  225.     io_Message    mn_ReplyPort set if quick I/O is not possible
  226.     io_Device    preset by the call to OpenDevice
  227.     io_Unit        preset by the call to OpenDevice
  228.     io_Command    CMD_READ
  229.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  230.     io_Length    sizeof(*buffer)
  231.     io_Data        char buffer[]
  232.             a pointer to the destination for the characters to read
  233.             from the keyboard.
  234.  
  235.    RESULTS
  236.     This function sets the error field in the IOStdReq, and fills
  237.         in the io_Data area with the next input, and io_Actual with
  238.         the number of bytes read.
  239.  
  240.     BUGS
  241.  
  242.     SEE ALSO
  243.     exec/io.h, devices/console.h
  244.  
  245. console.device/CMD_WRITE                             console.device/CMD_WRITE
  246.  
  247.    NAME
  248.     CMD_WRITE -- Write ANSI text to the console display.
  249.  
  250.    FUNCTION
  251.     Write a text record to the display.  Interpret the ANSI
  252.     control characters in the data as described below.  Note
  253.     that the RPort of the console window is in use while this
  254.     write command is pending.
  255.  
  256.    IO REQUEST INPUT
  257.     io_Message    mn_ReplyPort set if quick I/O is not possible
  258.     io_Device    preset by the call to OpenDevice
  259.     io_Unit        preset by the call to OpenDevice
  260.     io_Command    CMD_WRITE
  261.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  262.     io_Length    sizeof(*buffer), or -1 if io_Data is null
  263.             terminated
  264.     io_Data        a pointer to a buffer containing the ANSI text
  265.             to write to the console device.
  266.  
  267.    IO REQUEST RESULTS
  268.     io_Error    the error result (no errors are reported as of V36)
  269.     io_Actual    the number of bytes written from io_Data
  270.     io_Length    zero
  271.     io_Data        original io_Data plus io_Actual
  272.  
  273.    ANSI CODES SUPPORTED
  274.  
  275.     Codes are specified in the standard fashion for ANSI documents,
  276.     as the two 4 bit nibbles that comprise the character code,
  277.     high nibble first, separated by a slash.  Thus 01/11 (ESC) is
  278.     a character with the hex value 1B (or the decimal value 27).
  279.  
  280.     A character on the Amiga falls into one of the following four
  281.     ranges:
  282.     00/ 0-01/15    C0: ASCII control characters.  See below.
  283.     02/ 0-07/15    G0: ASCII graphic characters.  These characters
  284.             have an image that is displayed.  Note that the
  285.             DEL character is displayed by the Console Device:
  286.             it is not treated as control character here.
  287.     08/ 0-09/15    C1: ANSI 3.41 control characters.  See below.
  288.     10/ 0-15/15    G1: ECMA 94 Latin 1 graphic characters.
  289.  
  290.     Independent Control Functions (no introducer) --
  291.     Code    Name    Definition
  292.     -----    ---    ----------------------------------------------
  293.     00/ 7    BEL    BELL: actually an Intuition DisplayBeep()
  294.     00/ 8    BS    BACKSPACE
  295.     00/ 9    HT    HORIZONTAL TAB
  296.     00/10    LF    LINE FEED
  297.     00/11    VT    VERTICAL TAB
  298.     00/12    FF    FORM FEED
  299.     00/13    CR    CARRIAGE RETURN
  300.     00/14    SO    SHIFT OUT: causes all subsequent G0 (ASCII)
  301.             characters to be shifted to G1 (ECMA 94/1)
  302.             characters.
  303.     00/15    SI    SHIFT IN: cancels the effect of SHIFT OUT.
  304.     01/11    ESC    ESCAPE
  305.  
  306.     Code or Esc Name Definition
  307.     -----    --- ---- ---------------------------------------------
  308.     08/ 4    D   IND     INDEX: move the active position down one line.
  309.     08/ 5    E   NEL     NEXT LINE
  310.     08/ 8    H   HTS  HORIZONTAL TABULATION SET
  311.     08/13    M   RI     REVERSE INDEX
  312.     09/11    [   CSI     CONTROL SEQUENCE INTRODUCER: see next list
  313.  
  314.     ISO Compatible Escape Sequences (introduced by Esc) --
  315.     Esc   Name Definition
  316.     ----- ---- ---------------------------------------------------
  317.     c     RIS  RESET TO INITIAL STATE: reset the console display.
  318.  
  319.     Control Sequences, with the number of indicated parameters.
  320.     i.e. <CSI><parameters><control sequence letter(s)>.  Note the
  321.     last entries consist of a space and a letter.  CSI is either
  322.     9B or Esc[.  A minus after the number of parameters (#p)
  323.     indicates less is valid.  Parameters are separated by
  324.     semicolons, e.g. Esc[14;80H sets the cursor position to row
  325.     14, column 80.
  326.     CSI #p    Name Definition
  327.     --- --- ---- -------------------------------------------------
  328.     @   1-    ICH  INSERT CHARACTER
  329.     A   1-    CUU  CURSOR UP
  330.     B   1-    CUD  CURSOR DOWN
  331.     C   1-    CUF  CURSOR FORWARD
  332.     D   1-    CUB  CURSOR BACKWARD
  333.     E   1-    CNL  CURSOR NEXT LINE
  334.     F   1-    CPL  CURSOR PRECEDING LINE
  335.     H   2-    CUP  CURSOR POSITION
  336.     I   1-    CHT  CURSOR HORIZONTAL TABULATION
  337.     J   1-    ED   ERASE IN DISPLAY (only to end of display)
  338.     K   1-    EL   ERASE IN LINE (only to end of line)
  339.     L   1-    IL   INSERT LINE
  340.     M   1-    DL   DELETE LINE
  341.     P   1-    DCH  DELETE CHARACTER
  342.     R   2    CPR  CURSOR POSITION REPORT (in Read stream only)
  343.     S   1-    SU   SCROLL UP
  344.     T   1-    SD   SCROLL DOWN
  345.     W   n    CTC  CURSOR TABULATION CONTROL
  346.     Z   1-    CBT  CURSOR BACKWARD TABULATION
  347.     f   2-    HVP  HORIZONTAL AND VERTICAL POSITION
  348.     g   1-    TBC  TABULATION CLEAR
  349.     h   n    SM   SET MODE: see modes below.
  350.     l   n    RM   RESET MODE: see modes below.
  351.     m   n    SGR  SELECT GRAPHIC RENDITION
  352.     n   1-    DSR  DEVICE STATUS REPORT
  353.     t   1-    aSLPP SET PAGE LENGTH (private Amiga sequence)
  354.     u   1-    aSLL SET LINE LENGTH (private Amiga sequence)
  355.     x   1-    aSLO SET LEFT OFFSET (private Amiga sequence)
  356.     y   1-    aSTO SET TOP OFFSET (private Amiga sequence)
  357.     {   n    aSRE SET RAW EVENTS (private Amiga sequence)
  358.     |   8    aIER INPUT EVENT REPORT (private Amiga Read sequence)
  359.     }   n    aRRE RESET RAW EVENTS (private Amiga sequence)
  360.     ~   1    aSKR SPECIAL KEY REPORT (private Amiga Read sequence)
  361.      p  1-    aSCR SET CURSOR RENDITION (private Amiga sequence)
  362.      q  0    aWSR WINDOW STATUS REQUEST (private Amiga sequence)
  363.      r  4    aWBR WINDOW BOUNDS REPORT (private Amiga Read sequence)
  364.      v  1    aRAV RIGHT AMIGA V PRESS (private Amiga Read sequence-V37)
  365.  
  366.     Modes, set with <CSI><mode-list>h, and cleared with
  367.     <CSI><mode-list>l, where the mode-list is one or more of the
  368.     following parameters, separated by semicolons --
  369.     Mode    Name Definition
  370.     ------- ---- -------------------------------------------------
  371.     20    LNM  LINEFEED NEWLINE MODE: if a linefeed is a newline
  372.     >1    ASM  AUTO SCROLL MODE: if scroll at bottom of window
  373.     ?7    AWM  AUTO WRAP MODE: if wrap at right edge of window
  374.  
  375.     NOTES
  376.     The console.device recognizes these SGR sequences.
  377.     Note that some of these are new to V36.
  378.  
  379.     SGR (SELECT GRAPHICS RENDITION)
  380.         Selects colors, and other display characteristics
  381.         for text.
  382.  
  383.     Syntax:
  384.         <ESC>[graphic-rendition...m
  385.  
  386.     Example:
  387.         <ESC>[1;7m   (sets bold, and reversed text)
  388.  
  389.     Parameters:
  390.  
  391.         0    - Normal colors, and attributes
  392.         1    - Set bold
  393.         2    - Set faint (secondary color)
  394.         3    - Set italic
  395.         4    - Set underscore
  396.         7    - Set reversed character/cell colors
  397.         8    - Set concealed mode.
  398.         22    - Set normal color, not bold    (V36)
  399.         23    - Italic off            (V36)
  400.         24    - Underscore off        (V36)
  401.         27    - Reversed off            (V36)
  402.         28    - Concealed off            (V36)
  403.  
  404.         30-37    - Set character color
  405.         39    - Reset to default character color
  406.  
  407.         40-47    - Set character cell color
  408.         49    - Reset to default character cell color
  409.  
  410.         >0-7    - Set background color        (V36)
  411.               Used to set the background color before
  412.               any text is written.  The numeric parameter
  413.               is prefixed by ">".  This also means that if
  414.               you issue an SGR command with more than one
  415.               parameter, you must issue the digit only
  416.               parameters first, followed by any prefixed
  417.               parameters.                    
  418.  
  419.     BUGS
  420.     Does not correctly display cursor in SuperBitMap layers for
  421.     versions prior to V36.
  422.  
  423.     SEE ALSO
  424.     ROM Kernal Manual (Volume 1), exec/io.h
  425.     
  426. console.device/OpenDevice                           console.device/OpenDevice
  427.  
  428.     NAME
  429.     OpenDevice -- a request to open a Console device
  430.  
  431.     SYNOPSIS
  432.     error = OpenDevice("console.device", unit, IOStdReq, flags )
  433.     d0            a0               d0    a1        d1
  434.  
  435.     FUNCTION
  436.     The open routine grants access to a device.  There are two
  437.     fields in the IOStdReq block that will be filled in: the
  438.     io_Device field and possibly the io_Unit field.
  439.  
  440.     As of (V37) the flags field may also be filled in with
  441.     a value described below (see conunit.h or conunit.i).
  442.  
  443.     This open command differs from most other device open commands
  444.     in that it requires some information to be supplied in the
  445.     io_Data field of the IOStdReq block.  This initialization
  446.     information supplies the window that is used by the console
  447.     device for output.
  448.  
  449.     The unit number that is a standard parameter for an open call
  450.     is used specially by this device.  See conunit.h, or conunit.i
  451.     for defined valid unit numbers.
  452.  
  453.  
  454.     unit number: -1 (CONU_LIBRARY)
  455.  
  456.         Used to get a pointer to the device library vector
  457.     which is returned in the io_Device field of the IOStdReq
  458.     block.  No actual console is opened.  You must still close
  459.     the device when you are done with it.
  460.  
  461.     unit number: 0 (CONU_STANDARD)
  462.  
  463.         A unit number of zero binds the supplied window to
  464.     a unique console.  Sharing a console must be done at a level
  465.     higher than the device.
  466.  
  467.  
  468.     unit number: 1 (CONU_CHARMAP) (V36)
  469.  
  470.         A unit number of one is similar to a unit number of
  471.     zero, but a console map is also created, and maintained by
  472.     the console.device.  The character map is used by the console
  473.     device to restore obscured portions of windows which are
  474.     revealed, and to redraw a window after a resize.  Character
  475.     mapped console.device windows must be opened as SIMPLE REFRESH
  476.     windows.
  477.  
  478.         The character map is currently for internal use
  479.     only, and is not accessible by the programmer.  The character
  480.     map stores characters, attributes, and style information for
  481.     each character written with the CMD_WRITE command. 
  482.  
  483.     unit number: 3 (CONU_SNIPMAP) (V36)
  484.  
  485.         A unit number of three is similar to a unit number
  486.     of one, but also gives the user the ability to highlight
  487.     text with the mouse which can be copied by pressing
  488.     RIGHT AMIGA C.  See NOTES below.
  489.  
  490.  
  491.     flags: 0 (CONFLAG_DEFAULT)
  492.  
  493.         The flags field should be set to 0 under V34, or less.
  494.  
  495.     flags: 1 (CONFLAG_NODRAW_ON_NEWSIZE) (V37)
  496.  
  497.         The flags field can be set to 0, or 1 as of V37.  The
  498.     flags field is ignored under V36, so can be set, though it
  499.     will have no effect.  When set to 1, it means that you don't
  500.     want the console.device to redraw the window when the window
  501.     size is changed (assuming you have opened the console.device
  502.     with a character map - unit numbers 1, or 3).  This flag is
  503.     ignored if you have opened a console.device with a unit
  504.     number of 0.  Typically you would use this flag when you
  505.     want to perform your own window refresh on a newsize, and
  506.     you want the benefits of a character mapped console.
  507.     
  508.     IO REQUEST
  509.     io_Data        struct Window *window
  510.             This is the window that will be used for this
  511.             console.  It must be supplied if the unit in
  512.             the OpenDevice call is 0 (see above).  The
  513.             RPort of this window is potentially in use by
  514.             the console whenever there is an outstanding
  515.             write command.
  516.     INPUTS
  517.     "console.device" - a pointer to the name of the device to be opened.
  518.     unit - the unit number to open on that device.
  519.     IOStdReq - a pointer to a standard request block
  520.     0 - a flag field of zero (CONFLAG_DEFAULT)
  521.     1 - a flag field of one  (CONFLAG_NODRAW_ON_NEWSIZE) (V37)
  522.  
  523.     RESULTS
  524.     error - zero if successful, else an error is returned.
  525.     
  526.     NOTES
  527.     As noted above, opening the console.device with a unit number of 3
  528.     allows the user to drag select text, and copy the selection with
  529.     RIGHT AMIGA C.  The snip is copied to a private buffered managed
  530.     by the console.device (as of V36).  The snip can be copied to
  531.     any console.device window unless you are running a console to
  532.     clipboard utility such as that provided with V37.
  533.  
  534.     The user pastes text into console.device windows by pressing
  535.     RIGHT AMIGA V.  Both RIGHT AMIGA V, and RIGHT AMIGA C are swallowed
  536.     by the console.device (unless you have asked for key presses as
  537.     RAW INPUT EVENTS).  Text pasted in this way appears in the
  538.     console read stream as if the user had typed all of the characters
  539.     manually.  Additional input (e.g., user input, RAW INPUT EVENTS)
  540.     are queued up after pastes.  Pastes can theoretically be quite
  541.     large, though they are no larger than the amount of text
  542.     which is visible in a console.device window.
  543.  
  544.     When running the console to clipboard utility, text snips
  545.     are copied to the clipboard.device, and RIGHT AMIGA V key
  546.     presses are broadcast as an escape sequence as part of the 
  547.     console.device read stream ("<CSI>0 v" - $9B,$30,$20,$76).
  548.  
  549.     It is left up to the application to decide what to do when this
  550.     escape sequence is received.  Ideally the application
  551.     will read the contents of the clipboard, and paste the text
  552.     by using successive writes to the console.device.
  553.  
  554.     Because the contents of the clipboard.device can be quite
  555.     large, your program should limit the size of writes to something
  556.     reasonable (e.g., no more than 1K characters per CMD_WRITE, and
  557.     ideally no more than 256 characters per write).  Your program
  558.     should continue to read events from the console.device looking
  559.     for user input, and possibly RAW INPUT EVENTS.  How you decide
  560.     to deal with these events is left up to the application.
  561.  
  562.     If you are using a character mapped console you should receive
  563.     Intuition events as RAW INPUT EVENTS from the console.device.
  564.     By doing this you will hear about these events after the console
  565.     device does.  This allows the console.device to deal with events
  566.     such as window resizing, and refresh before your application.
  567.  
  568.     BUGS
  569.  
  570.     SEE ALSO
  571.     exec/io.h, intuition/intuition.h
  572.  
  573. console.device/RawKeyConvert                     console.device/RawKeyConvert
  574.  
  575.     NAME
  576.     RawKeyConvert -- decode raw input classes
  577.  
  578.     SYNOPSIS
  579.     actual = RawKeyConvert(event, buffer, length, keyMap)
  580.     D0                  A0     A1      D1      A2
  581.  
  582.     ConsoleDevice in A6 if called from Assembly Language.
  583.  
  584.     FUNCTION
  585.     This console function converts input events of type
  586.     IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
  587.     places the result into the buffer.
  588.  
  589.     INPUTS
  590.     event -  an InputEvent structure pointer.
  591.     buffer - a byte buffer large enough to hold all anticipated
  592.         characters generated by this conversion.
  593.     length - maximum anticipation, i.e. the buffer size in bytes.
  594.     keyMap - a KeyMap structure pointer, or null if the default
  595.         console device key map is to be used.
  596.  
  597.     RESULTS
  598.     actual - the number of characters in the buffer, or -1 if
  599.         a buffer overflow was about to occur.
  600.  
  601.     ERRORS
  602.     if actual is -1, a buffer overflow condition was detected.
  603.     Not all of the characters in the buffer are valid.
  604.  
  605.     NOTES
  606.     This function is different from standard device commands in
  607.     that it is a function in the console device library vectors.
  608.     In order to obtain a valid library base pointer for the
  609.     console device (a.k.a. ConsoleDevice) call
  610.     OpenDevice("console.device", -1, IOStdReq, 0),
  611.     and then grab the io_Device pointer field out of the IOStdReq
  612.     and use as ConsoleDevice.
  613.  
  614.     BUGS
  615.  
  616.     SEE ALSO
  617.     exec/io.h, devices/inputevent.h, devices/keymap.h
  618.  
  619.