home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vxtech02.zip / VXTECH02.TXT
Text File  |  1994-02-11  |  10KB  |  271 lines
  1. ============================================================================
  2.  VX-REXX Tech Note #2:
  3.  
  4.                Using the SendKeyString and PostKeyString methods in VX-REXX
  5.  
  6.                                                           February 11, 1994
  7.  
  8.                                 Applies to VX-REXX Version 1.01B and higher
  9. ----------------------------------------------------------------------------
  10.  
  11.                                                        WATCOM International
  12.                                                        tech@watcom.on.ca
  13.  
  14. ============================================================================
  15.  
  16. Abstract
  17. --------
  18.  
  19. This technical note describes some useful tasks that can be accomplished
  20. using the SendKeyString and PostKeyString methods in VX-REXX.  It is adapted
  21. from articles posted in the VX-REXX CFORUM on IBMLINK.  The text assumes that
  22. you are running VX-REXX version 1.01B or higher.
  23.  
  24.  
  25. Syntax
  26. ------
  27.  
  28. Although the syntax for both methods is documented online, we repeat them
  29. here for clarity:
  30.  
  31.     call VRMethod 'Application', 'SendKeyString', <object>, <string>
  32.     call VRMethod 'Application', 'PostKeyString', <object>, <string>
  33.  
  34. where
  35.  
  36.        <object> is either 1) the name of a VX-REXX object;
  37.                           2) the internal name of a VX-REXX object;
  38.                           3) a Presentation Manager window as returned
  39.                              by the ListWindows method or the HWnd property;
  40.                           4) in the case of SendKeyString only, a null
  41.                              string, which indicates the window with input
  42.                              focus.
  43.  
  44. and
  45.  
  46.        <string> is the a string representing the keystroke(s) to send.
  47.        The syntax is discussed below.
  48.  
  49. For example:
  50.  
  51.     call VRMethod 'Application', 'PostKeyString', VRWindow(), '{Alt}FO'
  52.     call VRMethod 'Application', 'SendKeyString', '', '{Enter}'
  53.  
  54. An object must always be specified with the PostKeyString method.
  55.  
  56.  
  57. Keystroke Syntax
  58. ----------------
  59.  
  60. Keystrokes are described using the same syntax that the KeyString property
  61. uses.  To send the characters 'A', 'B' and 'C' in sequence, just use
  62. the string 'ABC'.  To send a control character, prefix the character
  63. with the string '{Ctrl}' as in '{Ctrl}Z'.  The strings '{Alt}' and
  64. '{Shift}' are used to specify the Alt and Shift keys, as in '{Alt}H'
  65. or '{Shift}{F3}'.  Function keys are specified as '{F1}', '{F2}', and
  66. so on.
  67.  
  68. You can combine the modifiers together:
  69.  
  70.          '{Ctrl}{Shift}J'
  71.          '{Alt}{Ctrl}{F10}'
  72.  
  73. The modifiers only apply to a single keystroke.  The following string
  74. is used to send the two keystrokes 'Alt-F' and 'O':
  75.  
  76.          '{Alt}FO'
  77.  
  78. This example is used to send 'Alt-Z' followed by 'Ctrl-X':
  79.  
  80.          '{Alt}Z{Ctrl}X'
  81.  
  82. There is no fixed limit on the number of keystrokes to send, but it is
  83. recommended that the sequences not be too long.
  84.  
  85.  
  86. Difference Between PostKeyString and SendKeyString
  87. --------------------------------------------------
  88.  
  89. Two things differentiate these methods:
  90.  
  91.     1) PostKeyString sends keystrokes to an object but does not
  92.        wait for them to be processed  (it is 'asynchronous') and the
  93.        keystrokes that are 'posted' will not be translated into
  94.        accelerator sequences.  (Accelerator sequences are sequences
  95.        of keystrokes that an application intercepts and handles
  96.        before they can be passed to the window with input focus.
  97.        Accelerators are usually used as shortcut to activate menu
  98.        items.)
  99.  
  100.     2) SendKeyString sends keystrokes to an object one at a time,
  101.        waiting until each is processed before sending the next.
  102.        Each keystroke will also be checked for accelerator sequences.
  103.  
  104. What this means is that if you send a keystring, a special sequence
  105. such as '{Alt}{F4}' may be handled as an accelerator, but not if it is
  106. posted.  On the other hand, sending keystrokes to other applications
  107. can potentially hang your program if another application is not
  108. responding to keystrokes.
  109.  
  110.  
  111. Controlling Other Applications Using Keystrokes
  112. -----------------------------------------------
  113.  
  114. SendKeyString and PostKeyString can be used within your VX-REXX
  115. program to control other Presentation Manager applications.  There
  116. are two things that you must do:
  117.  
  118.    1) Figure out what keystrokes you need to use and whether they
  119.       involve accelerators.  If accelerators are needed, you must
  120.       use SendKeyString.
  121.  
  122.    2) Figure out which window is to be sent the keystrokes.  If you
  123.       want to send them to the window with input focus, you must use
  124.       SendKeyString.
  125.  
  126. The first step requires that you run the application you wish to control
  127. and write down the series of keystrokes you use to accomplish your task.
  128.  
  129. The second step requires some programming if you cannot simply assume
  130. that the destination window will be the window with the input focus.
  131. To find the window you want to send keystrokes to, use the ListWindows
  132. method to list the top-level windows that are currently on your desktop.
  133. Then by looking at either the 'Caption' or 'ClassName' property you
  134. can decide which one is appropriate.  You may then have to use the
  135. 'FirstChild' and 'Sibling' properties to traverse the window tree to
  136. find the one you're interested in.
  137.  
  138.  
  139. Controlling a Multi-Line Entry Field (MLE)
  140. ------------------------------------------
  141.  
  142. The MLE object can be controlled quite extensively with keystrokes.
  143. Here is the list of keystrokes that a MLE understands:
  144.  
  145.    {Del}         Deletes the selected section or the
  146.                  character to the right of the cursor.
  147.    {Shift}{Del}  Cuts the contents of the selected
  148.                  region to the clipboard.
  149.    {Ins}         Toggles between insert & overstrike mode.
  150.    {Shift}{Ins}  Paste the clipboard contents into the
  151.                  currently selected region.
  152.    {Backspace}   Deletes the selected section or the
  153.                  character to the left of the cursor.
  154.  
  155.    {Down}        These all move the cursor.  If you add
  156.    {Up}          a {Shift} character, they move the cursor
  157.    {Left}        and select text as well.
  158.    {Right}
  159.  
  160.    {Ctrl}{Left}  Move to the previous/next word.
  161.    {Ctrl}{Right}
  162.  
  163.    {Ctrl}{Shift}{Left}   Select until the previous/next word.
  164.    {Ctrl}{Shift}{Right}
  165.  
  166.    {PageUp}      Move up/down a page.
  167.    {PageDown}
  168.  
  169.    {Ctrl}{PageUp}   Scroll the screen to the left/right.
  170.    {Ctrl}{PageDown}
  171.  
  172.    {Home}        Move to the beginning of the line.
  173.    {End}         Move to the end of the line.
  174.  
  175.    {Shift}{Home} Select from the current point to the
  176.    {Shift}{End}  beginning/end of the line.
  177.  
  178.    {Ctrl}{Home}  Move to the beginning/end of file.
  179.    {Ctrl}{End}
  180.  
  181.    {Ctrl}{Shift}{Home} Select from the current point to
  182.    {Ctrl}{Shift}{End}  the beginning/end of the file.
  183.  
  184. You can easily control an MLE in your application by defining a
  185. procedure such as this:
  186.  
  187.     SendToMLE: procedure
  188.         call VRMethod 'Application', 'PostKeyString', arg(1), arg(2)
  189.         return
  190.  
  191. and calling it as follows:
  192.  
  193.     call SendToMLE 'MLE_1', '{Ctrl}{Home}'
  194.  
  195. Note that PostKeyString is used in case the control sequences the MLE
  196. understands conflict with accelerators that you have defined in your
  197. application.
  198.  
  199.  
  200. Sending keys to DOS and OS/2 Windows
  201. ------------------------------------
  202.  
  203. Because of a limitation in OS/2 itself, only other Presentation Manager
  204. applications can be controlled by the direct sending of keystrokes.
  205. Windowed DOS and OS/2 sessions can be sent some keystrokes, however,
  206. using the following method:
  207.  
  208.     1) Copy the string of keys you wish to send into the clipboard
  209.        using the PutClipboard method.  Note that the special sequences
  210.        '{Alt}', '{Ctrl}' and so on will not be translated.  If you wish
  211.        to send a special character, you must do the translation yourself,
  212.        by finding the appropriate hexadecimal value for the character.  For
  213.        example, to add a CTRL-M (carriage return) to the end of text
  214.        (which is what pressing ENTER would typically do) you would do
  215.        the following:
  216.  
  217.              str = str || '0d'x
  218.  
  219.        because CTRL-M maps to 0D hexadecimal.
  220.  
  221.  
  222.     2) Find the frame window for the DOS or OS/2 session that interests
  223.        you.  The ListWindows method can be used for this.
  224.  
  225.     3) Send the string 'p' to the system menu of the frame window. You can
  226.        use the undocumented 'Id' property to help you find the system menu.
  227.        The characters from the clipboard are now "pasted" into the session.
  228.        (See the example below.)
  229.  
  230. Here is a simple example of how to send the 'dir' command to a DOS or
  231. OS/2 window, using the call:
  232.  
  233.         call TypeInWindow win, 'dir' || '0d'x
  234.  
  235. The code is:
  236.  
  237.     /*
  238.      * This function sends a set of keystrokes to an OS/2 or DOS window.
  239.      */
  240.     
  241.     TypeInWindow: procedure
  242.        parse arg frame, keys
  243.        if( VRGet( frame, 'ClassName' ) \= 'WC_FRAME' )then return 0
  244.     
  245.        call VRMethod 'Application', 'PutClipboard', keys
  246.        call PasteToWindow frame
  247.        return
  248.     
  249.     /*
  250.      * Pass a frame window handle as the argument.  It searches for the system
  251.      * menu and sends it an Alt-P to invoke the paste function.  Uses the 'ID'
  252.      * property to get the window ID of the window.  All system menus have
  253.      * a window ID of 32770.
  254.      */
  255.     
  256.     PasteToWindow: procedure
  257.        parse arg frame
  258.        if( VRGet( frame, 'ClassName' ) \= 'WC_FRAME' )then return 0
  259.     
  260.        child = VRGet( frame, 'FirstChild' )
  261.        do while( child \= '' )
  262.            if( VRGet( child, 'ClassName' ) = 'WC_MENU' & ,
  263.                VRGet( child, 'Id' ) = 32770 )then do
  264.                call VRMethod 'Application', 'SendKeyString', child, 'p'
  265.            end
  266.            child = VRGet( child, 'Sibling' )
  267.        end
  268.        return 1
  269.  
  270. ============================================================================
  271.