home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / RXANSI12.ZIP / RXANSI.DOC < prev   
Text File  |  1991-04-03  |  15KB  |  412 lines
  1.                                      RXANSI - Rexx eXtension for ANSI
  2.                                                           Version 1.2                   
  3.                                                       Steve Mullarkey
  4.                                                        3rd.April 1991
  5.  
  6.  
  7.                                NOTICE
  8.  
  9.  
  10.      RXANSI is distributed as Shareware.  This means that if you find
  11.      the product useful you must  pay  for it.  Continued use  of the
  12.      product after any evaluation period is only allowed once payment 
  13.      has been received.                                           
  14.      To register RXANSI, send £15.00 to the following address ;
  15.  
  16.               95 Greenville Drive, 
  17.               Low Moor,
  18.           Bradford,
  19.           West Yorkshire,
  20.           England.
  21.           BD12 0PT.
  22.  
  23.      In return you will get the latest version on either 5.25" or
  24.      3.5" disk plus you will be sent the next new release.
  25.  
  26.      NB This price is for the UK only.
  27.       
  28.      The latest version is available from the following BBS's ;
  29.       
  30.          The Mainframe BBS - (0274) 602788
  31.          TJD support BBS   - (0535) 665345
  32.  
  33.      As with all good software, you use this at your own risk. If
  34.      you have any problems leave a message on my BBS and I'll try and
  35.      help but I will not be responsible for any problems caused etc.  
  36.  
  37.  
  38.  
  39. Description.
  40.    RXANSI is a REXX extension for OS/2 1.2 EE and OS/2 1.3 SE. It was
  41.    developed due to the lack of power available in REXX to perform    
  42.    screen I/O.
  43.     
  44.    Native REXX has two commands available, namely 'SAY', which displays
  45.    a line of text followed by a CR/LF, and PULL, which displays a
  46.    blank line then a question mark before accepting user input. These
  47.    two commands tend to make REXX procedures look unprofessional.
  48.  
  49.    The RXANSI extensions provide the following ;
  50.       o  Move cursor to any point on the screen
  51.       o  Display text without the CR/LF
  52.       o  Get keystrokes a key at a time (including function keys,
  53.          Home, Insert etc)
  54.       o  Get input from a field of a give size.
  55.       o  Change forground and background colours.
  56.       o  Draw lines and Boxes
  57.       o  Display Horizontal and vertical menus
  58.       o  Do all of the above in local and/or remote
  59.       o  Provide basic mouse support
  60.        
  61. Installation.
  62.    To install RXANSI copy RXANSI.DLL to any directory on your LIBPATH.
  63.    
  64. Demonstration.
  65.   After the DLL has been put in a suitable directory, run RXANSI.CMD.
  66.   This briefly demonstrates what is available with the package.
  67.    
  68. Function Use.
  69.   RXANSI consists of the following functions ; 
  70.  
  71.     o  RxAnsiInit()  
  72.        Enable use of ANSI screen controls
  73.  
  74.     o  RxGoTo(x,y)
  75.        Position cursor at point x,y on the screen
  76.  
  77.     o  RxGetChar()
  78.        Return the next keyboard character
  79.  
  80.     o  RxGetChars()
  81.        Get input from a field of a given size.
  82.  
  83.     o  RxPutChars(x)
  84.        Display characters x at the current cursor position without a CR/LF.
  85.  
  86.     o  RxLine(x1,y1,x2,y2,n)  
  87.        Draw a line from (x1,y1) to (x2,y2), with optional joining
  88.        characters every n bytes.
  89.  
  90.     o  RxBox(x1,y1,x2,y2,Fill)
  91.        Draw a box with (x1,y1) at the top right and (x2,y2) at the
  92.        bottom left and optionally fill with the current background colour.
  93.  
  94.     o  RxHMenu(x1,y1,options)
  95.        Draw a menu bar horizontally across the screen
  96.  
  97.     o  RxVMenu(x1,y1,options)
  98.        Draw a menu bar vertically down the screen
  99.  
  100.     o  RxMode(mode,handle)
  101.        Select between local and/or remote modes
  102.  
  103.     o  RxLineType(V,H)
  104.        Select either single or double lines for both horizontal and
  105.        vertical lines.
  106.       
  107.     o  RxMouse( < ON | OFF > )
  108.        Activate or deactivate mouse support. 
  109.  
  110.  
  111.  
  112.   Before any function can be used it must be registered with the REXX
  113.   interpreter. this is done by the following calls ;
  114.  
  115.   CALL RxFuncAdd 'RxAnsiInit','RXANSI','RxAnsiInit'
  116.   CALL RxFuncAdd 'RxGoTo',    'RXANSI','RxGoTo'
  117.   etc.
  118.  
  119.   This need only be done once as it is a global definition.
  120.  
  121.  
  122.   After you have used the functions and before you exit the
  123.   procedure, you can de-register the functions as follows ;
  124.  
  125.   CALL RxFuncDrop 'RxAnsiInit'
  126.   CALL RxFuncDrop 'RxGoTo'
  127.   etc
  128.  
  129.   This is only required if you want to move or delete the DLL.
  130.   If you do drop the function definitions, they will be dropped for
  131.   all processes, not just the one issuing the delete.
  132.  
  133.    
  134.  
  135. Function Descriptions.
  136.  
  137.   Name     : RxAnsiInit()
  138.   Returns  : OK if all OK
  139.   Function : This function sets variables in the REXX variable pool
  140.              to enable the following functions ;
  141.  
  142.            Foreground colour   Background colour
  143.                  White           On_White  
  144.                  Red             On_Red  
  145.                  Cyan            On_Cyan  
  146.                  Blue            On_Blue   
  147.                  Magenta         On_Magenta
  148.                  Green           On_Green  
  149.                  Yellow          On_Yellow 
  150.                  Black           On_Black  
  151.  
  152.            The following commands are also provided ;
  153.  
  154.          CLS - clear the screen
  155.          HOME - move cursor to topp of screen
  156.          SAVECUR - save current cursor position
  157.          RESTCUR - restore cursor position from previous SAVECUR
  158.          BLINK - set subsequent text to blink
  159.          INTENSE - set text to intense
  160.          INVERSE - set text to inverse display
  161.          RESET - set everything back to normal
  162.  
  163.  
  164.   Example  : rc = RxAnsiInit() 
  165.              SAY cls Red On_Black 'Hello World'
  166.  
  167.          This would initialise ANSI support then the second
  168.          line would clear the screen and display the message
  169.          'Hello world' in red on a black background.
  170.  
  171.  --------------------------------------------------------------------------
  172.  
  173.   Name     : RxGoTo(x,y)
  174.   Returns  : OK if all OK
  175.   Function : This function moves the cursor to line x and column y.
  176.  
  177.   Example  : rc = RxGoTo(10,30)
  178.  
  179.              This would place the cursor in the middle of the screen.
  180.  
  181.  --------------------------------------------------------------------------
  182.  
  183.   Name     : RxGetChar()
  184.   Returns  : Character value of next keystroke.
  185.   Function : This function waits for the next keystroke.
  186.          If a non-display key is hit the following could be
  187.              returned in local mode ;
  188.  
  189.          F1-F12, ENTER, ESCAPE, DELETE, INSERT, HOME, END,
  190.          PAGEUP, PAGEDOWN, LEFT, RIGHT, UP, DOWN, BACKSPACE
  191.           or ERROR for anything else. 
  192.  
  193.          In remote mode, the following can be returned ;
  194.          LEFT, RIGHT, UP, DOWN, ESCAPE, ENTER, HOME & END
  195.  
  196.  
  197.  
  198.   Example  : ch = RxGetChar()
  199.  
  200.              This would place the value of the next key hit in
  201.              variable ch.
  202.  
  203.  --------------------------------------------------------------------------
  204.  
  205.   Name     : RxGetChars(x1,y1,n,<default>)
  206.   Returns  : User input and sets variable 'LASTKEY' to last key hit.
  207.   Function : This function displays a line at X1,Y1 for 'n' bytes in
  208.              the current background colour. Data may be entered in
  209.              the field upto the defined size. Basic editing keys are
  210.          also available. Once either ENTER or ESCAPE is hit, the
  211.           text entered is returned by the function and the
  212.              variable 'LASTKEY' is set to either ESCAPE or ENTER.
  213.          
  214.  
  215.   Example  : ch = RxGetChars(4,10,20,'TEST.CMD')
  216.  
  217.              This would display an input field of 20 bytes at line 4,
  218.              column 10 with the default value of TEST.CMD. This could
  219.          be edited and whatever is on the screen when either enter
  220.          or escape is hit will be returned.
  221.  
  222.  --------------------------------------------------------------------------
  223.  
  224.   Name     : RxGetChar()
  225.   Returns  : Character value of next keystroke.
  226.   Function : This function waits for the next keystroke.
  227.          If a non-display key is hit the following could be
  228.              returned in local mode ;
  229.  
  230.          F1-F12, ENTER, ESCAPE, DELETE, INSERT, HOME, END,
  231.          PAGEUP, PAGEDOWN, LEFT, RIGHT, UP, DOWN, BACKSPACE
  232.           or ERROR for anything else. 
  233.  
  234.          If mouse support is enabled, the following can also
  235.          be returned in local mode ;
  236.  
  237.          BUTTON_1, BUTTON_2.
  238.  
  239.          In remote mode, the following can be returned ;
  240.          LEFT, RIGHT, UP, DOWN, ESCAPE, ENTER, HOME & END
  241.  
  242.  
  243.  
  244.   Example  : ch = RxGetChar()
  245.  
  246.              This would place the value of the next key hit in
  247.              variable ch.
  248.  
  249.  
  250.  --------------------------------------------------------------------------
  251.  
  252.   Name     : RxPutChars(x)
  253.   Returns  : OK if all OK.
  254.   Function : This function displays the text x at the current cursor
  255.            location. A CR/LF is not added to the end.     
  256.  
  257.   Example  : rc = RxPutChars('Hello World')
  258.  
  259.              This would display 'Hello world' at the current cursor
  260.              location.
  261.  
  262.  --------------------------------------------------------------------------
  263.  
  264.   Name     : RxLine(x1,y1,x2,y2,<n>)
  265.   Returns  : OK if all OK.
  266.   Function : This function draws a line between (x1,y1) and (x2,y2).
  267.            The fifth parameter is optional, and will provide a
  268.              joining character every 'n' bytes.
  269.  
  270.  
  271.   Example  : rc = RxLine(1,1,1,80,10)
  272.  
  273.              This would display a line across the top of the screen,
  274.              with a joining character every 10 bytes.
  275.  
  276.  --------------------------------------------------------------------------
  277.  
  278.   Name     : RxBox(x1,y1,x2,y2,<Fill>)
  279.   Returns  : OK if all OK.
  280.   Function : This function draws a box with x1,y1 as the top, right
  281.              hand corner and x2,y2 the bottom,left hand corner. The
  282.          optional fifth parameter will fill the box with the
  283.          current background colour. 
  284.  
  285.   Example  : rc = RxBox(1,1,25,80)
  286.  
  287.              This would draw a box round the edge of the screen.
  288.  
  289.  --------------------------------------------------------------------------
  290.  
  291.   Name     : RxLineType(V,H)
  292.   Returns  : OK if all OK.
  293.   Function : This function changes the characters used for drawing
  294.              lines. Possible values are 'S' for single and 'D' for
  295.          double. The first parameter is for Vertical lines and
  296.          the second for horizontal lines. Corners of boxes etc.
  297.          are also changed.     
  298.  
  299.   Example  : rc = RxLineType(D,S)
  300.  
  301.              This would make all vertical lines double and all
  302.              horizontal ones signle.
  303.  
  304.  --------------------------------------------------------------------------
  305.  
  306.   Name     : RxMode(Mode,<handle>)
  307.   Returns  : OK if all OK.
  308.   Function : This function changes all subsequent I/O to be either
  309.              local, if mode is 'LOCAL',remote if mode is 'REMOTE' or
  310.          MIXED, where input is from the remote and output is sent
  311.              to both the local and remote screens. For REMOTE and
  312.              MIXED, the file handle of the comm.port must be passed.
  313.      
  314.          NB All I/O is done directly, so any programs used which
  315.              buffer I/O will cause the buffered characters to be lost. 
  316.          This is necessary so cursor movement keystrokes etc.can be
  317.          picked up. 
  318.  
  319.          If the user hangs up while in remote mode, the variable
  320.          'LASTKEY' is set to 'USER GONE' and the next function 
  321.          call which reads from the remote user will fail with a
  322.          syntax error. This is so you don't have to check each
  323.          return code for 'USER GONE', just put a statement such as ;
  324.             SIGNAL SYNTAX ON NAME USERGONE
  325.          at the start of your procedure, then when the user hangs
  326.              up, control will be passed to the label at 'USERGONE'.
  327.          Remember to check that the LASTUSER variable is set to
  328.          'USER GONE' to ensure it's not a coding bug in the REXX
  329.              procedure !
  330.  
  331.          See the RXANSI.CMD for an example of how to do this.
  332.  
  333.          If a user hangs up, RxANISIInit must be called before
  334.              any other function to reset the carrier watchdog code. 
  335.          This will normally be done when the next user calls the
  336.              program.
  337.  
  338.  
  339.   Example  : rc = RxMode(REMOTE,Commhndl)
  340.  
  341.              This would direct all subsequent I/O to the file handle
  342.              in variable CommHndl.
  343.  
  344.  --------------------------------------------------------------------------
  345.  
  346.   Name     : RxHMenu(x1,y1,Options)
  347.   Returns  : Name of option chosen.
  348.   Function : This function displays a horizontal menu at location
  349.              x1,y1. Left and Right Cursor movement keys will
  350.              highlight the different options, any other key will exit.     
  351.          The value of the key pressed is put in variable 'LASTKEY'.
  352.  
  353.   Example  : rc = RxHMenu(1,1,'Files','Messages','Bulletins',Doors')
  354.  
  355.              This would display a menu across the top of the screen
  356.              consisting of four items. 
  357.  
  358.  --------------------------------------------------------------------------
  359.  
  360.   Name     : RxVMenu(x1,y1,Options)
  361.   Returns  : Name of option chosen.
  362.   Function : This function displays a vertical menu at location
  363.              x1,y1. Up and Down Cursor movement keys will
  364.              highlight the different options, any other key will exit.     
  365.          The value of the key pressed is put in variable 'LASTKEY'.
  366.  
  367.   Example  : rc = RxVMenu(2,3,'Area','Upload','Download')
  368.  
  369.              This would display a menu down the screen consisting of
  370.          three items. 
  371.  
  372.  --------------------------------------------------------------------------
  373.  
  374.   Name     : RxMouse( state )
  375.   Returns  : OK.
  376.   Function : This function turns mouse support on or off. This will
  377.              return the row and column on the mouse pointer when a
  378.          button was hit in variables MOUSE_X and MOUSE_Y and set
  379.          the variable LASTKEY to either BUTTON1 or BUTTON2.
  380.  
  381.          If mouse support is on when a menu is displayed, the
  382.              mouse can be used to select an option. The left button
  383.          acts as escape, and the right one almost like enter. You
  384.              may highlight an option by clicking the right button once,
  385.          and select it by clicking again.
  386.  
  387.          You should call RxMouse with a parm of OFF on exiting
  388.              the procedure, otherwise the mouse pointer could remain
  389.          on the screen.
  390.  
  391.   Example  : rc = RxMouse(ON)
  392.  
  393.              This would display a mouse pointer in the centre of the
  394.              screen. 
  395.  
  396.  --------------------------------------------------------------------------
  397.  
  398.  Revision History.
  399.    1.0 - Initial release.
  400.    1.1 - RxLine and RxBox commands added. 
  401.             All function names prefixed with 'RX'.
  402.    1.2 - Local and remote added.
  403.          ANSI code generation optimised.
  404.      Menu support added.
  405.      More variables set during call to RxAnsiInit.
  406.      Field input added.
  407.      Mouse support added.
  408.  
  409. Suggestions.
  410.   Please send all queries or suggestions to the Mainframe BBS 
  411.   (0274 - 602788).
  412.