home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / console.doc < prev    next >
Encoding:
Text File  |  1992-09-12  |  15.1 KB  |  494 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/CloseDevice
  12. console.device/OpenDevice
  13. console.device/RawKeyConvert
  14.  
  15.  
  16. console.device/CD_ASKDEFAULTKEYMAP
  17.  
  18.     NAME
  19.     CD_ASKDEFAULTKEYMAP - get the current default keymap
  20.  
  21.     FUNCTION
  22.     Fill the io_Data buffer with the current console device
  23.     default keymap, which is used to initialize console unit
  24.     keymaps when opened, and by RawKeyConvert with a null
  25.     keyMap parameter.
  26.  
  27.    IO REQUEST
  28.     io_Message    mn_ReplyPort set if quick I/O is not possible
  29.     io_Device    preset by the call to OpenDevice
  30.     io_Unit        preset by the call to OpenDevice
  31.     io_Command    CD_ASKDEFAULTKEYMAP
  32.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  33.     io_Length    sizeof(*keyMap)
  34.     io_Data        struct KeyMap *keyMap
  35.             pointer to a structure that describes 
  36.             the raw keycode to byte stream conversion.
  37.  
  38.     RESULTS
  39.     This function sets the io_Error field in the IOStdReq, and fills
  40.     the structure pointed to by io_Data with the current device 
  41.     default key map.
  42.  
  43.     BUGS
  44.  
  45.     SEE ALSO
  46.     exec/io.h, devices/keymap.h, devices/console.h
  47.  
  48.  
  49. console.device/CD_ASKKEYMAP         console.device/command/CD_ASKKEYMAP
  50.  
  51.     NAME
  52.     CD_ASKKEYMAP - get the current key map structure for this console
  53.  
  54.     FUNCTION
  55.     Fill the io_Data buffer with the current KeyMap structure in
  56.     use by this console unit.
  57.  
  58.     IO REQUEST
  59.     io_Message    mn_ReplyPort set if quick I/O is not possible
  60.     io_Device    preset by the call to OpenDevice
  61.     io_Unit        preset by the call to OpenDevice
  62.     io_Command    CD_ASKKEYMAP
  63.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  64.     io_Length    sizeof(*keyMap)
  65.     io_Data        struct KeyMap *keyMap
  66.             pointer to a structure that describes 
  67.             the raw keycode to byte stream conversion.
  68.  
  69.     RESULTS
  70.     This function sets the io_Error field in the IOStdReq, and fills
  71.     the structure the structure pointed to by io_Data with the current
  72.      key map.
  73.  
  74.     BUGS
  75.  
  76.     SEE ALSO
  77.     exec/io.h, devices/keymap.h, devices/console.h
  78.  
  79.  
  80. console.device/CD_SETDEFAULTKEYMAP
  81.  
  82.     NAME
  83.     CD_SETDEFAULTKEYMAP - set the current default keymap
  84.  
  85.     FUNCTION
  86.     This console command copies the keyMap structure pointed to
  87.     by io_Data to the console device default keymap, which is used
  88.     to initialize console units when opened, and by RawKeyConvert
  89.     with a null keyMap parameter.
  90.  
  91.     IO REQUEST
  92.     io_Message    mn_ReplyPort set if quick I/O is not possible
  93.     io_Device    preset by the call to OpenDevice
  94.     io_Unit        preset by the call to OpenDevice
  95.     io_Command    CD_SETDEFAULTKEYMAP
  96.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  97.     io_Length    sizeof(*keyMap)
  98.     io_Data        struct KeyMap *keyMap
  99.             pointer to a structure that describes 
  100.             the raw keycode to byte stream conversion.
  101.  
  102.     RESULTS
  103.     This function sets the io_Error field in the IOStdReq, and fills
  104.     the current device default key map from the structure pointed to
  105.     by io_Data.
  106.  
  107.     BUGS
  108.  
  109.     SEE ALSO
  110.     exec/io.h, devices/keymap.h, devices/console.h
  111.  
  112.  
  113. console.device/CD_SETKEYMAP         console.device/command/CD_SETKEYMAP
  114.  
  115.     NAME
  116.     CD_SETKEYMAP - set the current key map structure for this console
  117.  
  118.     FUNCTION
  119.     Set the current KeyMap structure used by this console unit to
  120.     the structure pointed to by io_Data.
  121.  
  122.     IO REQUEST
  123.     io_Message    mn_ReplyPort set if quick I/O is not possible
  124.     io_Device    preset by the call to OpenDevice
  125.     io_Unit        preset by the call to OpenDevice
  126.     io_Command    CD_SETKEYMAP
  127.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  128.     io_Length    sizeof(*keyMap)
  129.     io_Data        struct KeyMap *keyMap
  130.             pointer to a structure that describes 
  131.             the raw keycode to byte stream conversion.
  132.  
  133.     RESULTS
  134.     This function sets the io_Error field in the IOStdReq, and fills
  135.     the current key map from the structure pointed to by io_Data.
  136.  
  137.     BUGS
  138.  
  139.     SEE ALSO
  140.     exec/io.h, devices/keymap.h, devices/console.h
  141.  
  142.  
  143. console.device/CDInputHandler
  144.  
  145.     NAME
  146.     CDInputHandler - handle an input event for the console device
  147.  
  148.     SYNOPSIS
  149.     events = CDInputHandler(events, consoleDevice)
  150.                A0      A1
  151.  
  152.     FUNCTION
  153.     Accept input events from the producer, which is usually the
  154.     rom input.task.
  155.  
  156.     INPUTS
  157.     events - a pointer to a list of input events.
  158.     consoleDevice - a pointer to the library base address of the
  159.         console device.  This has the same value as ConsoleDevice
  160.         described below.
  161.  
  162.     RESULTS
  163.     events - a pointer to a list of input events not used by this
  164.         handler.
  165.  
  166.     NOTES
  167.     This function is available for historical reasons.  It is
  168.     preferred that input events be fed to the system via the
  169.     WriteEvent command of the input.device.
  170.  
  171.     This function is different from standard device commands in
  172.     that it is a function in the console device library vectors.
  173.     In order to obtain a valid library base pointer for the 
  174.     console device (a.k.a. ConsoleDevice) call
  175.     OpenDevice("console.device", -1, IOStdReq, 0),
  176.     and then grab the io_Device pointer field out of the IOStdReq
  177.     and use as ConsoleDevice.
  178.  
  179.     BUGS
  180.  
  181.     SEE ALSO
  182.     input.device
  183.  
  184.  
  185. console.device/CMD_CLEAR               console.device/command/CMD_CLEAR
  186.  
  187.     NAME
  188.     CMD_CLEAR - clear console input buffer
  189.  
  190.     FUNCTION
  191.     Remove from the input buffer any reports waiting to satisfy
  192.     read requests.
  193.  
  194.     IO REQUEST
  195.     io_Message    mn_ReplyPort set if quick I/O is not possible
  196.     io_Device    preset by the call to OpenDevice
  197.     io_Unit        preset by the call to OpenDevice
  198.     io_Command    CMD_CLEAR
  199.     io_Flags    IOB_QUICK set if quick I/O is possible, else 0
  200.  
  201.     BUGS
  202.  
  203.     SEE ALSO
  204.     exec/io.h, devices/console.h
  205.  
  206.  
  207. console.device/CMD_READ                 console.device/command/CMD_READ
  208.  
  209.    NAME
  210.     CMD_READ - return the next input from the keyboard
  211.  
  212.    FUNCTION
  213.     Read the next input, generally from the keyboard.  The form of
  214.     this input is as an ANSI byte stream: i.e. either ASCII text
  215.     or control sequences.  Raw input events received by the
  216.     console device can be selectively filtered via the aSRE and aRRE
  217.     control sequences (see the write command).  Keys are converted
  218.     via the keymap associated with the unit, which is modified
  219.     with CD_AKSKEYMAP and CD_SETKEYMAP
  220.  
  221.     If, for example, raw keycodes had been enabled by writing
  222.     <CSI>1{ to the console (where <CSI> is $9B or Esc[), keys
  223.     would return raw keycode reports with the information from
  224.     the input event itself, in the form:
  225.     <CSI>1;0;<keycode>;<qualifiers>;0;0;<seconds>;<microseconds>q
  226.  
  227.     If there is no pending input, this command will not be
  228.     satisfied, but if there is some input, but not as much as can
  229.     fill io_Length, the request will be satisfied with the input
  230.     currently available.
  231.  
  232.     IO REQUEST
  233.     io_Message    mn_ReplyPort set if quick I/O is not possible
  234.     io_Device    preset by the call to OpenDevice
  235.     io_Unit        preset by the call to OpenDevice
  236.     io_Command    CMD_READ
  237.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  238.     io_Length    sizeof(*buffer)
  239.     io_Data        char buffer[]
  240.             a pointer to the destination for the characters to read
  241.             from the keyboard.
  242.  
  243.    RESULTS
  244.     This function sets the error field in the IOStdReq, and fills
  245.         in the io_Data area with the next input, and io_Actual with
  246.         the number of bytes read.
  247.  
  248.     BUGS
  249.  
  250.     SEE ALSO
  251.     exec/io.h, devices/console.h
  252.  
  253.  
  254. console.device/CMD_WRITE               console.device/command/CMD_WRITE
  255.  
  256.     NAME
  257.     CMD_WRITE - write text to the display
  258.  
  259.     FUNCTION
  260.     Write a text record to the display.  Note that the RPort of
  261.     the console window is in use while this write command is
  262.     pending.
  263.  
  264.     IO REQUEST
  265.     io_Message    mn_ReplyPort set if quick I/O is not possible
  266.     io_Device    preset by the call to OpenDevice
  267.     io_Unit        preset by the call to OpenDevice
  268.     io_Command    CMD_WRITE
  269.     io_Flags    IOF_QUICK if quick I/O possible, else zero
  270.     io_Length    sizeof(*buffer), or -1 if null terminated
  271.     io_Data        char buffer[]
  272.             a pointer to a buffer containing the ANSI text
  273.             to write to the console device.
  274.  
  275.     ANSI CODES SUPPORTED
  276.  
  277.     Independent Control Functions (no introducer) --
  278.     Code    Name    Definition
  279.     -----    ---    ----------------------------------------------
  280.     00/ 7    BEL    BELL (actually a DisplayBeep)
  281.     00/ 8    BS    BACKSPACE
  282.     00/ 9    HT    HORIZONTAL TAB
  283.     00/10    LF    LINE FEED
  284.     00/11    VT    VERTICAL TAB
  285.     00/12    FF    FORM FEED
  286.     00/13    CR    CARRIAGE RETURN
  287.     00/14    SO    SHIFT OUT
  288.     00/15    SI    SHIFT IN
  289.     01/11    ESC    ESCAPE
  290.  
  291.     Code or Esc Name Definition
  292.     -----    --- ---- ---------------------------------------------
  293.     08/ 4    D   IND     INDEX: move the active position down one line
  294.     08/ 5    E   NEL     NEXT LINE:
  295.     08/ 8    H   HTS  HORIZONTAL TABULATION SET
  296.     08/13    M   RI     REVERSE INDEX:
  297.     09/11    [   CSI     CONTROL SEQUENCE INTRODUCER: see next list
  298.  
  299.     ISO Compatable Escape Sequences (introduced by Esc) --
  300.     Esc   Name Definition
  301.     ----- ---- ---------------------------------------------------
  302.     c     RIS  RESET TO INITIAL STATE
  303.  
  304.     Control Sequences, with the number of indicated parameters.
  305.     i.e. <CSI><parameters><control sequence letter(s)>.  Note the
  306.     last entries consist of a space and a letter.  CSI is either
  307.     9B or Esc[.  A minus after the number of parameters (#p)
  308.     indicates less is valid.  Parameters are seperated by
  309.     semicolins, e.g. Esc[14;80H sets the cursor position to row
  310.     14, column 80.
  311.     CSI #p    Name Definition
  312.     --- --- ---- -------------------------------------------------
  313.     @   1-    ICH  INSERT CHARACTER
  314.     A   1-    CUU  CURSOR UP
  315.     B   1-    CUD  CURSOR DOWN
  316.     C   1-    CUF  CURSOR FORWARD
  317.     D   1-    CUB  CURSOR BACKWARD
  318.     E   1-    CNL  CURSOR NEXT LINE
  319.     F   1-    CPL  CURSOR PRECEEDING LINE
  320.     H   2-    CUP  CURSOR POSITION
  321.     I   1-    CHT  CURSOR HORIZONTAL TABULATION
  322.     J   1-    ED   ERASE IN DISPLAY (only to end of display)
  323.     K   1-    EL   ERASE IN LINE (only to end of line)
  324.     L   1-    IL   INSERT LINE
  325.     M   1-    DL   DELETE LINE
  326.     P   1-    DCH  DELETE CHARACTER
  327.     R   2    CPR  CURSOR POSITION REPORT (in Read stream only)
  328.     S   1-    SU   SCROLL UP
  329.     T   1-    SD   SCROLL DOWN
  330.     W   n    CTC  CURSOR TABULATION CONTROL
  331.     Z   1-    CBT  CURSOR BACKWARD TABULATION
  332.     f   2-    HVP  HORIZONTAL AND VERTICAL POSITION
  333.     g   1-    TBC  TABULATION CLEAR
  334.     h   n    SM   SET MODE
  335.     l   n    RM   RESET MODE
  336.     m   n    SGR  SELECT GRAPHIC RENDITION
  337.     n   1-    DSR  DEVICE STATUS REPORT
  338.     t   1-    aSLPP SET PAGE LENGTH (private Amiga sequence)
  339.     u   1-    aSLL SET LINE LENGTH (private Amiga sequence)
  340.     x   1-    aSLO SET LEFT OFFSET (private Amiga sequence)
  341.     y   1-    aSTO SET TOP OFFSET (private Amiga sequence)
  342.     {   n    aSRE SET RAW EVENTS (private Amiga sequence)
  343.     |   8    aIER INPUT EVENT REPORT (private Amiga Read sequence)
  344.     }   n    aRRE RESET RAW EVENTS (private Amiga sequence)
  345.     ~   1    aSKR SPECIAL KEY REPORT (private Amiga Read sequence)
  346.      p  1-    aSCR SET CURSOR RENDITION (private Amiga sequence)
  347.      q  0    aWSR WINDOW STATUS REQUEST (private Amiga sequence)
  348.      r  4    aWBR WINDOW BOUNDS REPORT (private Amiga Read sequence)
  349.  
  350.     Modes, set with <CSI><mode-list>h, and cleared with
  351.     <CSI><mode-list>l, where the mode-list is one or more of the
  352.     following parameters, seperated by semicolins --
  353.     Mode    Name Definition
  354.     ------- ---- -------------------------------------------------
  355.     20    LNM  LINEFEED NEWLINE MODE: if a linefeed is a newline
  356.     >1    ASM  AUTO SCROLL MODE: if scroll at bottom of window
  357.     ?7    AWM  AUTO WRAP MODE: if wrap at right edge of window
  358.  
  359.     BUGS
  360.     Does not display cursor in SuperBitMap layers.
  361.  
  362.     SEE ALSO
  363.     ROM Kernal Manual: libraries and devices, exec/io.h
  364.     
  365.  
  366. console.device/CloseDevice
  367.  
  368.     NAME
  369.        Close -- close the console device
  370.  
  371.     SYNOPSIS
  372.        CloseDevice(IOStdReq)
  373.  
  374.     FUNCTION
  375.     This function closes software access to the console device,
  376.     and informs the system that access to this device/unit which was
  377.     previously opened has been concluded.  The device may perform
  378.     certain house-cleaning    operations.  The I/O request structure
  379.     is now free to be recycled.
  380.  
  381.     INPUTS
  382.     IOStdReq - pointer to an IOStdReq structure, set by OpenDevice
  383.  
  384.     BUGS
  385.  
  386.     SEE ALSO
  387.     console.device/OpenDevice, exec/io.h
  388.  
  389.  
  390. console.device/OpenDevice           console.device/function/OpenDevice
  391.  
  392.     NAME
  393.     OpenDevice - a request to open a Console device
  394.  
  395.     SYNOPSIS
  396.     error = OpenDevice("console.device", unit, IOStdReq, 0 )
  397.     D0            A0               D0    A1        D1
  398.  
  399.     FUNCTION
  400.     The open routine grants access to a device.  There are two
  401.     fields in the IOStdReq block that will be filled in: the
  402.     io_Device field and possibly the io_Unit field.
  403.  
  404.     This open command differs from most other device open commands
  405.     in that it requires some information to be supplied in the
  406.     io_Data field of the IOStdReq block.  This initialization
  407.     information supplies the window that is used by the console
  408.     device for output.
  409.  
  410.     The unit number that is a standard parameter for an open call
  411.     is used specially by this device.  A unit of -1 indicates that
  412.     no actual console is to be opened, and is used to get a pointer 
  413.     to the device library vector ( which will be returned in the
  414.     io_Device field of the IOStdReq block ).  A unit of zero binds 
  415.     the supplied window to a unique console.  Sharing a console
  416.     must be done at a level higher than the device.  There are no
  417.     other valid unit numbers.
  418.  
  419.     IO REQUEST
  420.     io_Data        struct Window *window
  421.             This is the window that will be used for this
  422.             console.  It must be supplied if the unit in
  423.             the OpenDevice call is 0 (see above).  The
  424.             RPort of this window is potentially in use by
  425.             the console whenever there is an outstanding
  426.             write command.
  427.     INPUTS
  428.     "console.device" - a pointer to the name of the device to be opened.
  429.     unit - the unit number to open on that device (0, or -1).
  430.     IOStdReq - a pointer to a standard request block
  431.     0 - a flag field of zero
  432.     
  433.     RESULTS
  434.     error - zero if successful, else an error is returned.
  435.     
  436.     BUGS
  437.     If a console.device is attached to a SUPERBITMAP window, the cursor
  438.     will not be displayed.  In this case you are required to TURN OFF the
  439.     console's cursor (with the standard escape sequence), and synthisize
  440.     your own.  Memory loss and compatiblity problems are possible if the
  441.     cursor is not turned off.
  442.  
  443.     SEE ALSO
  444.     console.device/CloseDevice, exec/io.h, intuition/intuition.h
  445.  
  446.  
  447. console.device/RawKeyConvert
  448.  
  449.     NAME
  450.     RawKeyConvert - decode raw input classes
  451.  
  452.     SYNOPSIS
  453.     actual = RawKeyConvert(event, buffer, length, keyMap)
  454.     D0                  A0     A1      D1      A2
  455.  
  456.     ConsoleDevice in A6 if called from Assembly Language.
  457.  
  458.     FUNCTION
  459.     This console function converts input events of type
  460.     IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
  461.     places the result into the buffer.
  462.  
  463.     INPUTS
  464.     event -  an InputEvent structure pointer.
  465.     buffer - a byte buffer large enough to hold all anticipated
  466.         characters generated by this conversion.
  467.     length - maximum anticipation, i.e. the buffer size in bytes.
  468.     keyMap - a KeyMap structure pointer, or null if the default
  469.         console device key map is to be used.
  470.  
  471.     RESULTS
  472.     actual - the number of characters in the buffer, or -1 if
  473.         a buffer overflow was about to occur.
  474.  
  475.     ERRORS
  476.     if actual is -1, a buffer overflow condition was detected.
  477.     Not all of the characters in the buffer are valid.
  478.  
  479.     NOTES
  480.     This function is different from standard device commands in
  481.     that it is a function in the console device library vectors.
  482.     In order to obtain a valid library base pointer for the
  483.     console device (a.k.a. ConsoleDevice) call
  484.     OpenDevice("console.device", -1, IOStdReq, 0),
  485.     and then grab the io_Device pointer field out of the IOStdReq
  486.     and use as ConsoleDevice.
  487.  
  488.     BUGS
  489.  
  490.     SEE ALSO
  491.     console.device/OpenDevice, exec/io.h,
  492.         devices/inputevent.h, devices/keymap.h
  493.  
  494.