home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / CBMDevKit1.dms / CBMDevKit1.adf / autodocs.lha / doc / console.doc < prev    next >
Encoding:
Text File  |  1993-10-15  |  23.4 KB  |  665 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.      s  0    aSDSS SET DEFAULT SGR SETTINGS (private Amiga sequence-V39)
  365.      v  1    aRAV  RIGHT AMIGA V PRESS (private Amiga Read sequence-V37)
  366.  
  367.     Modes, set with <CSI><mode-list>h, and cleared with
  368.     <CSI><mode-list>l, where the mode-list is one or more of the
  369.     following parameters, separated by semicolons --
  370.     Mode    Name Definition
  371.     ------- ---- -------------------------------------------------
  372.     20    LNM  LINEFEED NEWLINE MODE: if a linefeed is a newline
  373.     >1    ASM  AUTO SCROLL MODE: if scroll at bottom of window
  374.     ?7    AWM  AUTO WRAP MODE: if wrap at right edge of window
  375.  
  376.     NOTES
  377.     The console.device recognizes these SGR sequences.
  378.     Note that some of these are new to V36.
  379.  
  380.     SGR (SELECT GRAPHICS RENDITION)
  381.         Selects colors, and other display characteristics
  382.         for text.
  383.  
  384.     Syntax:
  385.         <ESC>[graphic-rendition...m
  386.  
  387.     Example:
  388.         <ESC>[1;7m   (sets bold, and reversed text)
  389.  
  390.     Parameters:
  391.  
  392.         0    - Normal colors, and attributes
  393.         1    - Set bold
  394.         2    - Set faint (secondary color)
  395.         3    - Set italic
  396.         4    - Set underscore
  397.         7    - Set reversed character/cell colors
  398.         8    - Set concealed mode.
  399.         22    - Set normal color, not bold    (V36)
  400.         23    - Italic off            (V36)
  401.         24    - Underscore off        (V36)
  402.         27    - Reversed off            (V36)
  403.         28    - Concealed off            (V36)
  404.  
  405.         30-37    - Set character color
  406.         39    - Reset to default character color
  407.  
  408.         40-47    - Set character cell color
  409.         49    - Reset to default character cell color
  410.  
  411.         >0-7    - Set background color        (V36)
  412.               Used to set the background color before
  413.               any text is written.  The numeric parameter
  414.               is prefixed by ">".  This also means that if
  415.               you issue an SGR command with more than one
  416.               parameter, you must issue the digit only
  417.               parameters first, followed by any prefixed
  418.               parameters.                    
  419.  
  420.     V39 console.device takes advantage of the ability to mask
  421.     bitplanes for faster scrolling, clearing, and rendering.
  422.     The actual number of bitplanes scrolled depends on which
  423.     colors you set via the SGR sequences.  For those using
  424.     the defaults of PEN color 1, and cell color 0, console.device
  425.     only needs to scroll 1 bitplane.  The actual number
  426.     of bitplanes scrolled is reset when ESCc is sent, and when
  427.     the console window is entirely cleared (e.g., FF).  In
  428.     general this should cause no compatability problems, unless
  429.     you are mixing console rendering with graphic.library calls
  430.     in the same portions of your window.  Console.device considers
  431.     the number of bitplanes it must scroll, and the screen display
  432.     depth so that interleaved bitplane scrolling can be taken
  433.     advantage of in cases where performance is not significantly
  434.     affected (interleaved scrolling, and masking are mutually
  435.     exclusive).  The determination of how many planes to scroll
  436.     is undefined, and may change in the future.
  437.  
  438.     V39 console.device supports a new private sequence (aSDSS)
  439.     intended for use by users who prefer to change their default
  440.     SGR settings.  When this private Amiga sequence is sent to the
  441.     console, the current Pen color, Cell color, Text style, and
  442.     Reverse mode (on or off), are set as defaults.  When ESC[0m
  443.     is issued, the settings are restored to the preferred settings.
  444.     ESC[39m, and ESC[49m are likewise affected.  In general
  445.     applications should not make use of this private sequence as it
  446.     is intended for users who would normally include it as part of
  447.     their shell startup script.  The normal defaults are reset
  448.     when ESCc is issued.
  449.  
  450.     BUGS
  451.     Does not correctly display cursor in SuperBitMap layers for
  452.     versions prior to V36.
  453.  
  454.     Concealed mode should not be used prior to V39 console.device.
  455.     Prior to V39 concealed mode masked all rastport output, the
  456.     effect of which varied.  As of V39, text output is simply
  457.     hidden by setting the pen colors.  Scrolling, clearing,
  458.     cursor rendering, etc., are unaffected.  For maximum
  459.     compatability it is recommended you simply set the colors
  460.     yourself, and not used concealed mode.
  461.  
  462.     V36-V37 character mapped mode console.device windows could
  463.     crash, or behave erratically if you scroll text DOWN more
  464.     than a full window's worth of text.  This bug has been fixed
  465.     in V39 console.  The only work-around is to avoid sending
  466.     scroll down, or cursor up commands which exceed the window
  467.     rows (this is not a problem for unit 0 console windows).
  468.  
  469.     SEE ALSO
  470.     ROM Kernel Manual (Volume 1), exec/io.h
  471.     
  472. console.device/OpenDevice                           console.device/OpenDevice
  473.  
  474.     NAME
  475.     OpenDevice -- a request to open a Console device
  476.  
  477.     SYNOPSIS
  478.     error = OpenDevice("console.device", unit, IOStdReq, flags )
  479.     d0            a0               d0    a1        d1
  480.  
  481.     FUNCTION
  482.     The open routine grants access to a device.  There are two
  483.     fields in the IOStdReq block that will be filled in: the
  484.     io_Device field and possibly the io_Unit field.
  485.  
  486.     As of (V37) the flags field may also be filled in with
  487.     a value described below (see conunit.h or conunit.i).
  488.  
  489.     This open command differs from most other device open commands
  490.     in that it requires some information to be supplied in the
  491.     io_Data field of the IOStdReq block.  This initialization
  492.     information supplies the window that is used by the console
  493.     device for output.
  494.  
  495.     The unit number that is a standard parameter for an open call
  496.     is used specially by this device.  See conunit.h, or conunit.i
  497.     for defined valid unit numbers.
  498.  
  499.  
  500.     unit number: -1 (CONU_LIBRARY)
  501.  
  502.         Used to get a pointer to the device library vector
  503.     which is returned in the io_Device field of the IOStdReq
  504.     block.  No actual console is opened.  You must still close
  505.     the device when you are done with it.
  506.  
  507.     unit number: 0 (CONU_STANDARD)
  508.  
  509.         A unit number of zero binds the supplied window to
  510.     a unique console.  Sharing a console must be done at a level
  511.     higher than the device.
  512.  
  513.  
  514.     unit number: 1 (CONU_CHARMAP) (V36)
  515.  
  516.         A unit number of one is similar to a unit number of
  517.     zero, but a console map is also created, and maintained by
  518.     the console.device.  The character map is used by the console
  519.     device to restore obscured portions of windows which are
  520.     revealed, and to redraw a window after a resize.  Character
  521.     mapped console.device windows must be opened as SIMPLE REFRESH
  522.     windows.
  523.  
  524.         The character map is currently for internal use
  525.     only, and is not accessible by the programmer.  The character
  526.     map stores characters, attributes, and style information for
  527.     each character written with the CMD_WRITE command. 
  528.  
  529.     unit number: 3 (CONU_SNIPMAP) (V36)
  530.  
  531.         A unit number of three is similar to a unit number
  532.     of one, but also gives the user the ability to highlight
  533.     text with the mouse which can be copied by pressing
  534.     RIGHT AMIGA C.  See NOTES below.
  535.  
  536.  
  537.     flags: 0 (CONFLAG_DEFAULT)
  538.  
  539.         The flags field should be set to 0 under V34, or less.
  540.  
  541.     flags: 1 (CONFLAG_NODRAW_ON_NEWSIZE) (V37)
  542.  
  543.         The flags field can be set to 0, or 1 as of V37.  The
  544.     flags field is ignored under V36, so can be set, though it
  545.     will have no effect.  When set to 1, it means that you don't
  546.     want the console.device to redraw the window when the window
  547.     size is changed (assuming you have opened the console.device
  548.     with a character map - unit numbers 1, or 3).  This flag is
  549.     ignored if you have opened a console.device with a unit
  550.     number of 0.  Typically you would use this flag when you
  551.     want to perform your own window refresh on a newsize, and
  552.     you want the benefits of a character mapped console.
  553.     
  554.     IO REQUEST
  555.     io_Data        struct Window *window
  556.             This is the window that will be used for this
  557.             console.  It must be supplied if the unit in
  558.             the OpenDevice call is 0 (see above).  The
  559.             RPort of this window is potentially in use by
  560.             the console whenever there is an outstanding
  561.             write command.
  562.     INPUTS
  563.     "console.device" - a pointer to the name of the device to be opened.
  564.     unit - the unit number to open on that device.
  565.     IOStdReq - a pointer to a standard request block
  566.     0 - a flag field of zero (CONFLAG_DEFAULT)
  567.     1 - a flag field of one  (CONFLAG_NODRAW_ON_NEWSIZE) (V37)
  568.  
  569.     RESULTS
  570.     error - zero if successful, else an error is returned.
  571.     
  572.     NOTES
  573.     As noted above, opening the console.device with a unit number of 3
  574.     allows the user to drag select text, and copy the selection with
  575.     RIGHT AMIGA C.  The snip is copied to a private buffered managed
  576.     by the console.device (as of V36).  The snip can be copied to
  577.     any console.device window unless you are running a console to
  578.     clipboard utility such as that provided with V37.
  579.  
  580.     The user pastes text into console.device windows by pressing
  581.     RIGHT AMIGA V.  Both RIGHT AMIGA V, and RIGHT AMIGA C are swallowed
  582.     by the console.device (unless you have asked for key presses as
  583.     RAW INPUT EVENTS).  Text pasted in this way appears in the
  584.     console read stream as if the user had typed all of the characters
  585.     manually.  Additional input (e.g., user input, RAW INPUT EVENTS)
  586.     are queued up after pastes.  Pastes can theoretically be quite
  587.     large, though they are no larger than the amount of text
  588.     which is visible in a console.device window.
  589.  
  590.     When running the console to clipboard utility, text snips
  591.     are copied to the clipboard.device, and RIGHT AMIGA V key
  592.     presses are broadcast as an escape sequence as part of the 
  593.     console.device read stream ("<CSI>0 v" - $9B,$30,$20,$76).
  594.  
  595.     It is left up to the application to decide what to do when this
  596.     escape sequence is received.  Ideally the application
  597.     will read the contents of the clipboard, and paste the text
  598.     by using successive writes to the console.device.
  599.  
  600.     Because the contents of the clipboard.device can be quite
  601.     large, your program should limit the size of writes to something
  602.     reasonable (e.g., no more than 1K characters per CMD_WRITE, and
  603.     ideally no more than 256 characters per write).  Your program
  604.     should continue to read events from the console.device looking
  605.     for user input, and possibly RAW INPUT EVENTS.  How you decide
  606.     to deal with these events is left up to the application.
  607.  
  608.     If you are using a character mapped console you should receive
  609.     Intuition events as RAW INPUT EVENTS from the console.device.
  610.     By doing this you will hear about these events after the console
  611.     device does.  This allows the console.device to deal with events
  612.     such as window resizing, and refresh before your application.
  613.  
  614.     BUGS
  615.  
  616.     SEE ALSO
  617.     exec/io.h, intuition/intuition.h
  618.  
  619. console.device/RawKeyConvert                     console.device/RawKeyConvert
  620.  
  621.     NAME
  622.     RawKeyConvert -- decode raw input classes
  623.  
  624.     SYNOPSIS
  625.     actual = RawKeyConvert(event, buffer, length, keyMap)
  626.     D0                  A0     A1      D1      A2
  627.  
  628.     ConsoleDevice in A6 if called from Assembly Language.
  629.  
  630.     FUNCTION
  631.     This console function converts input events of type
  632.     IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
  633.     places the result into the buffer.
  634.  
  635.     INPUTS
  636.     event -  an InputEvent structure pointer.
  637.     buffer - a byte buffer large enough to hold all anticipated
  638.         characters generated by this conversion.
  639.     length - maximum anticipation, i.e. the buffer size in bytes.
  640.     keyMap - a KeyMap structure pointer, or null if the default
  641.         console device key map is to be used.
  642.  
  643.     RESULTS
  644.     actual - the number of characters in the buffer, or -1 if
  645.         a buffer overflow was about to occur.
  646.  
  647.     ERRORS
  648.     if actual is -1, a buffer overflow condition was detected.
  649.     Not all of the characters in the buffer are valid.
  650.  
  651.     NOTES
  652.     This function is different from standard device commands in
  653.     that it is a function in the console device library vectors.
  654.     In order to obtain a valid library base pointer for the
  655.     console device (a.k.a. ConsoleDevice) call
  656.     OpenDevice("console.device", -1, IOStdReq, 0),
  657.     and then grab the io_Device pointer field out of the IOStdReq
  658.     and use as ConsoleDevice.
  659.  
  660.     BUGS
  661.  
  662.     SEE ALSO
  663.     exec/io.h, devices/inputevent.h, devices/keymap.h
  664.  
  665.