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