home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vxcliser.zip / VRCS.1 / TUTBOOK.INF (.txt) < prev    next >
OS/2 Help File  |  1994-09-29  |  114KB  |  863 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Welcome ΓòÉΓòÉΓòÉ
  3.  
  4. Welcome to the demonstration version of VX-REXX. 
  5.  
  6. Click the Forward button to continue. 
  7.  
  8.  
  9. ΓòÉΓòÉΓòÉ 2. Introduction to VX-REXX ΓòÉΓòÉΓòÉ
  10.  
  11. The VX-REXX visual development environment for OS/2 REXX is an easy to use, 
  12. powerful and fully integrated environment for creating applications that 
  13. exploits the graphical user interface capabilities of OS/2 2.x and Presentation 
  14. Manager. The product combines a project management facility, visual designer, 
  15. and an interactive source-level debugger to deliver a very approachable and 
  16. highly productive visual development environment. 
  17.  
  18. Design applications visually 
  19.  
  20. Create rich graphical applications quickly and easily using the visual design 
  21. environment. With the visual designer, you can graphically create Presentation 
  22. Manager objects, quickly customize their properties, and easily attach REXX 
  23. routines to the objects. 
  24.  
  25. Intergrated development environment 
  26.  
  27. Build, test, and debug your applications without leaving the development 
  28. environment. Then package your applications as an EXE file or PM macro for 
  29. royalty-free redistribution. The power of the integrated development 
  30. environment can also be used with your existing REXX applications. 
  31.  
  32. Powerful open environment 
  33.  
  34. Enjoy the simplicity of event-driven programming together with global editing 
  35. capabilities essential for professional project management. The Watcom visual 
  36. development environment is open and extensible through IBM's object oriented 
  37. System Object Model (SOM) technology. You can access all standard REXX APIs 
  38. including DB2/2 because the VX-REXX is based on the OS/2 2.x system REXX. 
  39.  
  40. Highlights 
  41.  
  42.    o Easy to use visual development environment 
  43.    o Create and modify objects dynamically at both edit and run time 
  44.    o Powerful project management facility 
  45.    o Advanced interactive source-level debugger 
  46.    o Package your applications as EXE files or PM macros 
  47.    o Access standard REXX APIs including DB2/2 
  48.    o Create REXX code visually using drag and drop programming 
  49.    o System Object Model (SOM) based object manager 
  50.    o Support for multi-threaded applications 
  51.    o Include OS/2 style help and hints in your applications 
  52.    o Supports SAA CUA '91 objects 
  53.    o Autosizing and alignment of objects 
  54.    o Integrated console window support for existing REXX programs 
  55.    o Royalty-free run time library 
  56.    o Multiple modeless window support 
  57.    o Create PM macros for applications supporting REXX as a macro language 
  58.  
  59.  
  60. ΓòÉΓòÉΓòÉ 3. Watcom VX-REXX Client/Server Edition ΓòÉΓòÉΓòÉ
  61.  
  62. The VX-REXX Client/Server Edition includes the powerful features of VX-REXX 
  63. plus database objects that simplify GUI client/server application development 
  64. on OS/2. This demonstration version includes all of the Client/Server Edition 
  65. features. 
  66.  
  67. o Simplify Database Development 
  68.  
  69.   The database connection and query objects make GUI client/server application 
  70.   development simple and approachable. With these objects you can quickly build 
  71.   windows to display and update data from a wide range of database systems. 
  72.   Just point and click on a connection object and enter parameters to connect 
  73.   to the database. With a query object you can visually design and test a SQL 
  74.   query. You can then automatically populate a window with objects that display 
  75.   data from the query and provide search and update capabilities. The package 
  76.   also includes a database administrator which lets you easily create new 
  77.   databases, define tables and set the column types and relationships. 
  78.  
  79. o Support from DB2 and More 
  80.  
  81.   VX-REXX Client/Server Edition makes it easy to connect to a wide range of 
  82.   databases. You can create OS/2 client applications which connect to DB2/2 or 
  83.   DB2/6000. VX-REXX Client/Server Edition can also use IBM's DRDA support on 
  84.   OS/2 to access DB2 for MVS, DB2/400 for AS/400, and DB2/VSE and VM (SQL/DS) 
  85.   for VM and VSE. Also supported are Watcom SQL and ODBC enabled databases. 
  86.  
  87. o Visualize Your Data 
  88.  
  89.   Create more than a dozen types of charts with the chart object. Customize 
  90.   your charts from 150 display options including chart type, 3D view and 
  91.   titles. Charts can be bound directly to SQL queries making it easy to create 
  92.   rich visual client/server applications. You can even build interactive charts 
  93.   since the charting object supports run-time events. 
  94.  
  95. Click the Forward button to continue. 
  96.  
  97.  
  98. ΓòÉΓòÉΓòÉ 4. How to use this tutorial ΓòÉΓòÉΓòÉ
  99.  
  100. This tutorial shows you how to create applications with VX-REXX. The first two 
  101. parts show you how to use the tools and the system to create applications. The 
  102. third part of the manual is an alphabetical reference for all components of the 
  103. VX-REXX software. 
  104.  
  105. At any point in the tutorial, you can click the Back button to review a 
  106. previous page. You can also press Forward to skip ahead. To see an outline of 
  107. the whole tutorial, press the Contents button. 
  108.  
  109.  
  110. ΓòÉΓòÉΓòÉ 5. Samples included with the demonstration version ΓòÉΓòÉΓòÉ
  111.  
  112. A number of sample programs come with the demonstration version of VX-REXX. 
  113. They are located in the Samples folder, in your Watcom VX-REXX folder. All 
  114. samples come ready to run with full source code. Here is a list of the sample 
  115. programs: 
  116.  
  117. Bounce              A globe bounces around a window, driven by a timer. 
  118.  
  119. Button              A simple first application with push buttons. 
  120.  
  121. Calculator          A four function calculator. 
  122.  
  123. CUA 91 Skeleton     The CUA 91 sample demonstrates several VX-REXX features and 
  124.                     programming techniques relevant to developing CUA'91 
  125.                     compliant applications. It also demonstrates how to use 
  126.                     subroutines contained in OBJECT.VRS to simplify the 
  127.                     process. 
  128.  
  129. DDE Explorer        A program that lets you converse with DDE servers. 
  130.  
  131. DragDrop            A simple example of adding drag-drop to your programs. 
  132.  
  133. Employee Database   A database sample that uses the REXX API to IBM DB2/2 or 
  134.                     Watcom SQL. 
  135.  
  136. File browser        A program that lists various information about files in a 
  137.                     container. 
  138.  
  139. Hint and Help       A demonstration of the run time help facility in VX-REXX. 
  140.  
  141. Hocus focus         This program displays the PM window handle of the window 
  142.                     that currently has the input focus. 
  143.  
  144. Mind Game           A pattern guessing game. 
  145.  
  146. MMW                 An example of modal and modeless windows. 
  147.  
  148. Movies              A multimedia sample that plays OS/2 movies (AVI files). 
  149.  
  150. Notebook            A simple program that uses the notebook object. 
  151.  
  152. Popup               A demonstration of using pop-up menus. 
  153.  
  154. Printing            Sends a file to printer. 
  155.  
  156. RGB                 Display colors using a value set object and some sliders. 
  157.  
  158. Scan                An EPM macro that scans through the current file looking 
  159.                     for REXX labels. 
  160.  
  161. Threads             A sample of a multithreaded program. 
  162.  
  163. Window Controller   This program lists the top level frame windows on the 
  164.                     desktop and lets you minimize, maximize, restore, and shake 
  165.                     them. 
  166.  
  167. There are a number of samples that use the database objects available in the 
  168. Client/Server Edition of VX-REXX. They are located in the Database Samples 
  169. folder which is in your Watcom VX-REXX folder: 
  170.  
  171. Sample Database Generator This program creates a sample database used in the 
  172.                     other database sample programs. This program can create 
  173.                     DB2/2 or Watcom SQL databases. 
  174.  
  175. Getting Started     This is a simple project that uses bound objects to display 
  176.                     database values. 
  177.  
  178. Master/Detail       This program illustrates a sample master-detail form. This 
  179.                     is a window with two queries, one for the master table and 
  180.                     one for the detail table. 
  181.  
  182. Order Entry Application This program is an order entry system for a fictitious 
  183.                     company. It stores information about customers, products, 
  184.                     and orders in a sample database. It is a more complex 
  185.                     example that shows how to use a number of queries on many 
  186.                     windows. 
  187.  
  188. There are a number of samples that use the chart object available in the 
  189. Client/Server Edition of VX-REXX. They are located in the Chart Samples folder 
  190. which is in your Watcom VX-REXX folder: 
  191.  
  192. Chart titles        This sample program shows how to change title options. 
  193.  
  194. Click               This sample shows you how to respond to events on chart 
  195.                     objects. 
  196.  
  197. Data                This program demonstrates changing chart data values, row 
  198.                     names, and column names. 
  199.  
  200. Drill Down          This program shows how to use the Click event to drill down 
  201.                     into a chart. 
  202.  
  203. Database Charting 1 
  204.  
  205. Database Charting 2 These programs shows the use of bound charts that display 
  206.                     data directly from a database. 
  207.  
  208. Group Options       This program shows how to set the slice cut for a section 
  209.                     in a pie chart. 
  210.  
  211. Mouse               This sample shows you how to respond to right mouse clicks 
  212.                     on chart objects. 
  213.  
  214. Print               Use this sample to see how you can print charts. 
  215.  
  216. Row and Column      This sample shows the way to add rows and columns to a 
  217.                     chart at run time. 
  218.  
  219. Simple Click        This program shows how to find out what part of the chart a 
  220.                     user clicked on. 
  221.  
  222.  
  223. ΓòÉΓòÉΓòÉ 6. About the demonstration version of the software ΓòÉΓòÉΓòÉ
  224.  
  225. The demonstration version of VX-REXX differs from the full version in a number 
  226. of ways: 
  227.  
  228. o You cannot save projects, make standalone executables, or make macro files 
  229.   using the demonstration version. 
  230.  
  231. o The IBM Help Compiler (IPFC) is included in the Client/Server Edition, but 
  232.   not in this demonstration version. 
  233.  
  234. o The EXEHDR utility is included in the Client/Server Edition, but not in this 
  235.   demonstration version. 
  236.  
  237.  
  238. ΓòÉΓòÉΓòÉ 7. System requirements ΓòÉΓòÉΓòÉ
  239.  
  240. The minimum recommended configuration for Watcom VX-REXX is a 20 megahertz 386 
  241. personal computer with 8 megabytes of memory. About 6 megabytes of hard disk 
  242. space are required to install the base software; another 7 megabytes are 
  243. required if you install the Client/Server Objects (database and charting). 
  244.  
  245. IBM OS/2 version 2.0 with the OS/2 Service Pak or higher must be installed 
  246. prior to installing VX-REXX. If you are running OS/2 2.0 without the OS/2 
  247. Service Pak, you must obtain it from IBM and install it to make sure that all 
  248. features of VX-REXX work correctly. The Service Pak required is IBM number 
  249. XR06055. You can obtain it from the IBM OS/2 BBS, from CompuServe, or directly 
  250. from IBM. Contact your IBM representative for more information. 
  251.  
  252. The OS/2 REXX interpreter and the REXX information must also be installed prior 
  253. to installing VX-REXX. 
  254.  
  255.  
  256. ΓòÉΓòÉΓòÉ 8. How to contact Watcom ΓòÉΓòÉΓòÉ
  257.  
  258.  
  259. ΓòÉΓòÉΓòÉ 8.1. In North America (and all other locations not listed below) ΓòÉΓòÉΓòÉ
  260.  
  261. Watcom International Corporation. 
  262.  
  263. 415 Phillip Street, Waterloo, Ontario, CANADA, N2L 3X2 
  264.  
  265. Technical Support
  266. hot-line:   (519) 886-3700
  267. fax:        (519) 747-4547
  268. BBS:        (519) 884-2100
  269. Internet:   tech@watcom.on.ca
  270. Compuserve: type GO WATCOM
  271.  
  272. General Inquiries
  273. tel: (519)886-3700
  274. fax: (519)747-4971
  275.  
  276. Sales, upgrades, other product
  277. orders, and reseller inquiries/orders:
  278. 1-800-265-4555 (toll free in North America)
  279.  
  280.  
  281. ΓòÉΓòÉΓòÉ 8.2. In Europe ΓòÉΓòÉΓòÉ
  282.  
  283. Watcom Europe Limited. 
  284.  
  285. PO Box 64, LIVINGSTON, West Lothian, EH54 7AE, UNITED KINGDOM 
  286.  
  287. Technical Support
  288.     United Kingdom
  289.         tel: 0506 460112
  290.         fax: 0506 460115
  291.  
  292.     Other Locations
  293.         tel: (44) 506 460112
  294.         fax: (44) 506 460115
  295.  
  296.     BBS: (519) 884-2103
  297.     Internet: tech@watcom.on.ca
  298.     Compuserve: type GO WATCOM
  299.  
  300. General Inquiries
  301.     United Kingdom
  302.         tel: 0506 460112
  303.         fax: 0506 460115
  304.  
  305.     Other Locations
  306.         tel: (44) 506 460112
  307.         fax: (44) 506 460115
  308.  
  309. Sales, Upgrades, other product orders, and reseller inquiries/orders:
  310.     United Kingdom Toll Free
  311.         tel: 0800 44 44 55
  312.         fax: 0800 55 54 55
  313.  
  314.     Germany Toll Free
  315.         tel: 0130 81 88 62
  316.         fax: 0130 81 88 63
  317.  
  318.     France Toll Free
  319.         tel: 05 90 81 35
  320.         fax: 05 90 81 36
  321.  
  322.     All Other Locations
  323.         tel: (44) 506 460112
  324.         fax: (44) 506 460115
  325.  
  326.  
  327. ΓòÉΓòÉΓòÉ 8.3. In Japan ΓòÉΓòÉΓòÉ
  328.  
  329. Lifeboat, Inc. 
  330.  
  331. 3-6 Kanda -- Nishikicho, Chiyoda-ku, Tokyo, Japan, 101 
  332.  
  333.     Japan
  334.         tel: (03) 3293-4711
  335.         fax: (03) 3293-4710
  336.  
  337.  
  338. ΓòÉΓòÉΓòÉ 9. A simple program ΓòÉΓòÉΓòÉ
  339.  
  340. This chapter provides a brief introduction to the VX-REXX development 
  341. environment through a tutorial. We will learn how to start and stop VX-REXX and 
  342. create, and run a simple application. In addition, the drag and drop 
  343. programming feature of VX-REXX will be used to reduce the time and effort 
  344. needed for writing code. The same steps used in this tutorial can be used to 
  345. develop all VX-REXX applications. Subsequent chapters provide more details 
  346. about each step. 
  347.  
  348. In this tutorial, you will create an application which consists of an entry 
  349. field, push button, and list box. When run, text typed in the entry field will 
  350. be added to the list box using the push button. 
  351.  
  352.  
  353. ΓòÉΓòÉΓòÉ 9.1. Starting VX-REXX ΓòÉΓòÉΓòÉ
  354.  
  355. You can start VX-REXX by double clicking on the VX-REXX icon in the Watcom 
  356. VX-REXX folder on your desktop. After it starts, you will see a window similar 
  357. to Figure 1. 
  358.  
  359. Figure 1  The initial VX-REXX screen.
  360.  
  361. The VX-REXX interface consists of a menu bar, a tool palette, and a project 
  362. window containing a grid of dots. The menu bar contains the commands that are 
  363. used to create and run applications. The tool palette contains the objects 
  364. which can be placed in the project window to create the user interface for an 
  365. application. 
  366.  
  367. Note:  The demonstration version of VX-REXX automatically opens the tutorial 
  368. book when it starts up. 
  369.  
  370.  
  371. ΓòÉΓòÉΓòÉ 9.2. Creating an application ΓòÉΓòÉΓòÉ
  372.  
  373. There are three basic steps to building a VX-REXX application: 
  374.  
  375.  1. Creating the user interface by adding objects to the project window. 
  376.  
  377.  2. Customizing each object's properties. 
  378.  
  379.  3. Attaching code to each object. 
  380.  
  381. We will go through these steps in the following sections to create a simple 
  382. application. 
  383.  
  384.  
  385. ΓòÉΓòÉΓòÉ 9.3. Creating the user interface ΓòÉΓòÉΓòÉ
  386.  
  387. Creating the user interface is the first step in building an application. The 
  388. interface to this application has three objects: an entry field, a push button, 
  389. and a list box. We will start by adding the entry field to the window: 
  390.  
  391.  1. Click on the Tools menu and then choose EntryField. 
  392.  
  393.  2. Position the mouse pointer near the top left corner of the project window. 
  394.  
  395.     The cursor will change to a cross while it is positioned on the project 
  396.     window. 
  397.  
  398.  3. Hold down mouse button 1 and drag the mouse down and to the right until the 
  399.     entry field is approximately the size of the one shown in Figure 2. 
  400.  
  401.         Figure 2  The entry field added to the window.
  402.  
  403.  4. Release the mouse button. 
  404.  
  405. Add the push button to the window using a similar procedure: 
  406.  
  407.  1. Click on the Tools menu and then choose PushButton. 
  408.  
  409.  2. Position the cursor below the bottom left corner of the entry field. 
  410.  
  411.  3. Hold down mouse button 1 and drag the mouse down and to the right until the 
  412.     push button  is approximately the size of the one shown in Figure 3. 
  413.  
  414.         Figure 3  The push button added to the window.
  415.  
  416.  4. Release the mouse button. 
  417.  
  418. Repeat the above steps using the ListBox item from the Tools menu to make your 
  419. window similar in appearance to Figure 4. 
  420.  
  421. Figure 4  The entry field, push button and list box on the window.
  422.  
  423. Finally, to improve the appearance of the window, center the three objects on 
  424. the window as follows: 
  425.  
  426.  1. Position the cursor on the entry field. 
  427.  
  428.  2. Press and hold down mouse button 1. Sizing handles will appear along the 
  429.     border of the entry field. Move the cursor over the push button and then 
  430.     over the list box. Now all three objects will have sizing handles along 
  431.     their borders. The screen should look similar to  Figure 5. 
  432.  
  433.         Figure 5  The entry field, push button and list box are selected.
  434.  
  435.  3. Release mouse button 1. 
  436.  
  437.  4. Position the cursor on the entry field once again and press mouse button 2 
  438.     to invoke the VX-REXX pop-up menu. 
  439.  
  440.  5. Select the Align menu item using mouse button 1. A second menu will appear. 
  441.     From this menu, click on the menu item used for centering objects as shown 
  442.     in Figure 6. 
  443.  
  444.         Figure 6  The menu item used to centre objects.
  445.     The push button and the list box will now be centered underneath the entry 
  446.     field. 
  447.  
  448.  6. Position the cursor over the right border of the window. The cursor shape 
  449.     should change to a sizing arrow. 
  450.  
  451.  7. Hold down mouse button 1 and move the cursor left or right to adjust the 
  452.     width of the window until the objects are centered. 
  453.  
  454.  8. Click on the window background to deselect the objects. 
  455.  
  456. The screen should appear as in  Figure 7. 
  457.  
  458. Figure 7  The objects centred on the window.
  459.  
  460. All the objects we need have been created. Now their properties must be 
  461. customized. 
  462.  
  463.  
  464. ΓòÉΓòÉΓòÉ 9.4. Customizing object properties ΓòÉΓòÉΓòÉ
  465.  
  466. Each VX-REXX object has properties such as color and size which can be 
  467. customized. An object is given default property values when it is first 
  468. created. Often, these properties need to be changed. 
  469.  
  470. The entry field has a font property which determines the font used to display 
  471. text. The height of the entry field should be set according to the size of the 
  472. font being used. This step can be done automatically using the entry field's 
  473. Autosize property. If this property is set to 1, the height of the entry field 
  474. will be adjusted automatically based on the font being used. Initially, the 
  475. Autosize property is set to 0. Change it to 1 as follows: 
  476.  
  477.  1. Click mouse button 2 anywhere over the entry field. A pop-up menu will be 
  478.     displayed. 
  479.  
  480.  2. Choose the Open... menu and then choose the Properties menu item. A 
  481.     property notebook will be displayed. 
  482.  
  483.  3. Click on the Size index tab. The Size page will be displayed as in Figure 
  484.     8. 
  485.  
  486.         Figure 8  The size page of the property notebook.
  487.  
  488.  4. Click on the check box marked Autosize. 
  489.  
  490.  5. Close the entry field's property notebook by double clicking on the title 
  491.     bar icon in the upper left corner. 
  492.  
  493. The text which appears on a push button is called the caption and is determined 
  494. by the push button's Caption property. To set the caption of the push button to 
  495. Add Item: 
  496.  
  497.  1. Click mouse button 2 anywhere over the push button, choose the Open... menu 
  498.     and then choose Properties to open the push button's property notebook. 
  499.  
  500.  2. Click on the Text index tab. The Text page will be displayed as in Figure 
  501.     9. 
  502.  
  503.         Figure 9  The text page of the property notebook.
  504.  
  505.  3. Click on the Caption entry field and type: 
  506.  
  507.         Add Item
  508.  
  509.  4. Close the property notebook. The text Add Item will appear on the push 
  510.     button. 
  511.  
  512. Lines in a list box are displayed one below another, beginning at the top. The 
  513. last line in the list box may not appear completely, depending on the height of 
  514. the list box. The height must be adjusted if this characteristic is 
  515. undesirable. To have the height adjusted automatically, set the AdjustHeight 
  516. property of the list box as follows: 
  517.  
  518.  1. Open the property notebook for the list box using the same method as 
  519.     before. 
  520.  
  521.  2. Turn to the Size page by clicking on the Size index tab. 
  522.  
  523.  3. Click on the AdjustHeight check box. 
  524.  
  525. By default, items in a list box will be sorted in ascending order. For our 
  526. application, we want items to be listed in the order they are added to the list 
  527. box. The list box's Sort property must be changed: 
  528.  
  529.  1. With the list box property notebook open, turn to the List page by clicking 
  530.     on the List index tab. 
  531.  
  532.  2. Click on the scroll arrows in the Sort drop down combobox. 
  533.  
  534.  3. Choose none from the drop down list. 
  535.  
  536.  4. Close the property notebook by double clicking on its title bar icon. 
  537.  
  538. Finally, set the text that will appear on the window title bar: 
  539.  
  540.  1. Open the property notebook for the window. Note that the cursor must be 
  541.     positioned on the window but not over any object in the window when 
  542.     pressing mouse button 2. 
  543.  
  544.  2. Index tabs for all pages in the notebook cannot be seen at once. The tab 
  545.     scroll arrows at the top and bottom right corners of the notebook, as shown 
  546.     in Figure 10, must be used to view all the index tabs. Press mouse button 1 
  547.     on the bottom right tab scroll arrow until the Text index tab appears. 
  548.  
  549.         Figure 10  The window's property notebook.
  550.  
  551.  3. Open the Text page of the notebook by clicking on the Text index tab. 
  552.  
  553.  4. Click on the Caption entry field and type: 
  554.  
  555.         Sample
  556.  
  557.  5. Close the property notebook. 
  558.  
  559. The first two steps in developing the sample application are complete: creating 
  560. the objects and customizing their properties. 
  561.  
  562.  
  563. ΓòÉΓòÉΓòÉ 9.5. A preliminary run ΓòÉΓòÉΓòÉ
  564.  
  565. Although the sample program is not finished you can run it to see what it will 
  566. look like when complete. To run it, click on the Run menu and choose Run 
  567. project. This will hide VX-REXX and run the application, which should appear 
  568. similar to Figure 11: 
  569.  
  570. Figure 11  A test run of the sample program.
  571.  
  572. Notice that the background of the window no longer contains a grid of dots. 
  573. Type text into the entry field to see how it will appear. Use the Tab key to 
  574. move between the objects. Click on the push button. Nothing happens because no 
  575. code has been attached to the push button. Attaching code to the objects in the 
  576. window is the next step in developing our sample application. 
  577.  
  578. Exit the application and return to VX-REXX by clicking on the title bar icon 
  579. and choosing Close. 
  580.  
  581.  
  582. ΓòÉΓòÉΓòÉ 9.6. Attaching code to objects ΓòÉΓòÉΓòÉ
  583.  
  584. In this application pressing the push button will add the text in the entry 
  585. field to the list box. We will use the drag and drop programming feature of 
  586. VX-REXX to help us write the code which will perform this task. First we must 
  587. obtain the text in the entry field. To attach this code to the push button: 
  588.  
  589.  1. Open the push button's property notebook and turn to the Event page by 
  590.     clicking on the Event tab. Code can be attached to the push button for any 
  591.     events which appear on this page. 
  592.  
  593.  2. Select Click and then click on Open to invoke an editor we can use to write 
  594.     our code. The editor will contain a skeleton for an event routine, as shown 
  595.     in Figure 12. 
  596.  
  597.         Figure 12  Event routine skeleton
  598.  
  599.     The first line in the editor is a comment, the second is the name of the 
  600.     routine, and the last line contains a REXX return instruction which needs 
  601.     to be executed at the end of the routine. The REXX code we place in this 
  602.     routine will be executed when the push button is pressed. 
  603.  
  604.  3. At this point, we could write code manually but there is a much easier 
  605.     method. Press and hold down mouse button 2 over the entry field. Now move 
  606.     the mouse over the editor. The editor window and the application window may 
  607.     need to be moved apart before this step can be done. A line joining the 
  608.     mouse to the entry field will appear as in Figure 13: 
  609.  
  610.         Figure 13  Getting the text in the entry field.
  611.  
  612.  4. Release mouse button 2. A dialog box will appear which lists descriptions 
  613.     of all the entry field methods which can be invoked and all the entry field 
  614.     properties which can be set or retrieved. 
  615.  
  616.  5. Click on the Value item under the Get property heading. We need to get the 
  617.     Value property because it contains the text in the entry field. Now click 
  618.     on OK. The following instruction is placed at the insertion point in the 
  619.     editor: 
  620.  
  621.         value = VRGet( "EF_1", "Value" )
  622.  
  623.     This instruction will assign the variable value with the text in the entry 
  624.     field. 
  625.  
  626. The automatic code generation feature of VX-REXX we have used is called drag 
  627. and drop programming. Using this feature, you can create REXX applications 
  628. without having to memorize the syntax of VX-REXX functions and methods. 
  629.  
  630. The next step is to add the text to the list box: 
  631.  
  632.  1. Press and hold down mouse button 2 over the list box and then move the 
  633.     pointer over the editor window. A line joining the cursor to the list box 
  634.     will appear. 
  635.  
  636.  2. Release mouse button 2. A dialog box will appear listing all the list box 
  637.     methods that can be invoked and all the list box properties which can be 
  638.     set or retrieved. Click on the Add a string item under the Methods heading 
  639.     and then press the OK button. 
  640.  
  641.  3. Another dialog box, as shown in  Figure 14, will appear. 
  642.  
  643.         Figure 14  The Add a String dialog box.
  644.  
  645.  4. Click on the string field and type the following: 
  646.  
  647.         value
  648.  
  649.  5. Click on the Quoted String check box. Now it should not be checked. 
  650.  
  651.  6. Press the OK button. The REXX code to add the text to the list box will be 
  652.     placed underneath the previous instruction, as shown in Figure 15. 
  653.  
  654. Figure 15  The event routine for the push button.
  655.  
  656. After getting the text, we should clear the entry field to allow new text to be 
  657. entered: 
  658.  
  659.  1. Press and hold down mouse button 2 over the entry field and then move the 
  660.     mouse over the editor window. 
  661.  
  662.  2. Release mouse button 2. A dialog box will appear. 
  663.  
  664.  3. Click on the Value item under the Set property heading and then press the 
  665.     OK button. 
  666.  
  667.  4. Click on OK from the second dialog box. The editor window should now appear 
  668.     as in  Figure 16. 
  669.  
  670.         Figure 16  The unfinished push button event routine.
  671.  
  672. The push button will have the focus when this routine is executed. We should 
  673. set the focus to the entry field so that new text can be entered immediately: 
  674.  
  675.  1. Press and hold down mouse button 2 over the entry field and then move the 
  676.     mouse over the editor window. 
  677.  
  678.  2. Release mouse button 2. 
  679.  
  680.  3. Click on the Set focus to object item underneath the Methods heading and 
  681.     then press the OK button. A line of code will be inserted below the 
  682.     previous lines in the editor window. 
  683.  
  684.  4. Close the editor window by double clicking on its title bar icon. 
  685.  
  686. The push button event routine is now complete and is shown in Figure 17. We can 
  687. perform a test run to see if it works correctly. 
  688.  
  689. Figure 17  The complete push button event routine.
  690.  
  691.  
  692. ΓòÉΓòÉΓòÉ 9.7. A test run ΓòÉΓòÉΓòÉ
  693.  
  694. To run the application, click on the Run menu and choose Run project. The 
  695. application window will look the same as it did during the first run. We have 
  696. not changed its appearance. However, try clicking on the push button after 
  697. typing text into the entry field. Now the text is added to the list box. Also, 
  698. the entry field is cleared and is given the focus again. The push button click 
  699. routine we created appears to be working as it should. 
  700.  
  701. Try adding more text to the list box. Also, try pressing the push button when 
  702. there is no text in the entry field. It seems as though no action is performed. 
  703. However, if more text is added to the list box, you can see that a blank line 
  704. is inserted when the entry field is empty and the push button is pressed, as 
  705. shown in Figure 18. 
  706.  
  707. Figure 18  Adding text to the list box.
  708.  
  709. This behavior is undesirable and needs to be prevented with the addition of 
  710. more code. Also, to make the application easier to use, we should allow text to 
  711. be added to the list box with the use of the Enter key. 
  712.  
  713.  
  714. ΓòÉΓòÉΓòÉ 9.8. Improving the application ΓòÉΓòÉΓòÉ
  715.  
  716. A push button can be enabled or disabled. When enabled, a push button responds 
  717. to events such as a click event. The push button in our application has always 
  718. been enabled. When a push button is disabled it does not respond to any events 
  719. and also appears grayed. In particular, a disabled push button cannot receive 
  720. the focus and will not respond when pressed. We will use this property of push 
  721. buttons to prevent blank lines from being added to the list box: 
  722.  
  723.  1. Press mouse button 2 anywhere over the entry field to activate the VX-REXX 
  724.     pop-up menu. 
  725.  
  726.  2. Click on events and then click on change. The editor window will appear 
  727.     with the skeleton of a routine, as shown in  Figure 19. 
  728.  
  729.         Figure 19  The entry field change routine.
  730.  
  731.     This routine will be executed whenever the contents of the entry field 
  732.     change. We need to determine if the entry field has become empty and if 
  733.     this is the case, we will disable the push button to prevent it from adding 
  734.     any text to the list box. 
  735.  
  736.  3. Press and hold down mouse button 2 over the entry field, move the mouse 
  737.     over the editor window and then release the mouse button. As before, a 
  738.     dialog box will appear. 
  739.  
  740.  4. Click on the Value item underneath the Get property heading and then press 
  741.     OK. The code to get the contents of the entry field will be generated. 
  742.  
  743.  5. Add the following line of code at the insertion point: 
  744.  
  745.         if value = "" then do
  746.  
  747.     Press the Enter key and then the Tab key at the end of this line. 
  748.  
  749.  6. At this point, we have determined that the entry field is empty so we must 
  750.     disable the push button. Press and hold down mouse button 2 over the push 
  751.     button, move the mouse over the editor window and then release the mouse 
  752.     button. A dialog box listing all methods and properties of a push button 
  753.     will appear. 
  754.  
  755.  7. Click on the Enabled item under the Set property heading and then press OK. 
  756.     A second dialog box will appear, as shown in Figure 20. 
  757.  
  758.         Figure 20  The enabled property dialog box.
  759.  
  760.     Click on the Enabled check box so that it is not checked. Press OK. The 
  761.     instruction to disable the push button is placed at the insertion point in 
  762.     the editor window. 
  763.  
  764.  8. Now we need to add the code that will enable the push button when the entry 
  765.     field is not empty. Add the following lines at the insertion point: 
  766.  
  767.         end
  768.         else do
  769.  
  770.     Press the Enter key and then the Tab key at the end of the second line. The 
  771.     editor window should appear as in Figure 21. 
  772.  
  773.         Figure 21  The incomplete entry field change routine.
  774.  
  775.     Press and hold down mouse button 2 over the push button, move the mouse 
  776.     over the editor window and then release the mouse button. From the dialog 
  777.     box click on the Enabled item under the Set property heading and then press 
  778.     OK. Press OK again on the second dialog box which appears. The code to 
  779.     enable the push button is inserted into the editor window. 
  780.  
  781.  9. One last line needs to be added to the routine: 
  782.  
  783.         end
  784.  
  785.     The complete routine is shown in Figure 22. 
  786.  
  787.         Figure 22  The complete entry field change routine.
  788.  
  789. Now we must make the push button disabled when the application is first run: 
  790.  
  791.  1. Open the push button's property notebook and turn to the Style page. Click 
  792.     on the Enabled check box so that it is not checked. 
  793.  
  794.  2. Also on this page is the Default check box. Click on this check box so that 
  795.     it becomes checked. Now, when the Enter key is pressed the push button 
  796.     click routine will be executed, as though the push button had been pressed. 
  797.     This behavior will allow text to be added to the list box by pressing the 
  798.     Enter key. 
  799.  
  800. We can easily make another improvement to the application by using the Hints 
  801. feature of VX-REXX: 
  802.  
  803.  1. Turn to the Hint page of the push button's property notebook. Type the 
  804.     following in the Hint entry field: 
  805.  
  806.         Add the text to the list box.
  807.  
  808.  2. Open the entry field's property notebook, turn to the Hint page and type 
  809.     the following: 
  810.  
  811.         Enter text.
  812.  
  813.  3. Open the window's property notebook, turn to the Hint page and click on the 
  814.     ShowHints check box. Select the Bottom item from the Status Area drop down 
  815.     combobox. A status bar will appear at the bottom of the window, as shown in 
  816.     Figure 23. 
  817.  
  818.         Figure 23  The status bar for showing hints.
  819.  
  820.     The status bar may overlap with the bottom of the list box. If this is the 
  821.     case then the list box can be raised or its height can be decreased. 
  822.  
  823. The previous steps add hints to the application. When the mouse is moved over 
  824. the push button, its hint text will be displayed in the status bar. Similarly, 
  825. when the mouse is positioned over the entry field, its hint text will be 
  826. displayed. We can now try out the improvements we have made. 
  827.  
  828.  
  829. ΓòÉΓòÉΓòÉ 9.9. Running the application ΓòÉΓòÉΓòÉ
  830.  
  831. Run the application as before by clicking on the Run menu and choosing Run 
  832. project. Move the mouse over the entry field and then the push button to see 
  833. their hints. The application window is shown in  Figure 24. 
  834.  
  835. Figure 24  Running the finished application.
  836.  
  837. Try typing in text and adding it to the list box with the use of the Enter key 
  838. as well as the push button. Notice that the push button becomes disabled 
  839. whenever the entry field is empty. 
  840.  
  841. Although this is a simple application, it would take considerably more effort 
  842. and expertise to create it with other languages and development tools. However, 
  843. with VX-REXX features such as drag and drop programming, we have created it 
  844. easily with little knowledge of OS/2 or the REXX language. 
  845.  
  846.  
  847. ΓòÉΓòÉΓòÉ 9.10. Stopping VX-REXX ΓòÉΓòÉΓòÉ
  848.  
  849. To exit VX-REXX and return to the OS/2 desktop, click on the VX-REXX title bar 
  850. icon and choose Close or double click on the title bar icon. 
  851.  
  852. In this tutorial, the following techniques have been learned: 
  853.  
  854.  1. Adding objects to a window. 
  855.  
  856.  2. Modifying an object's properties. 
  857.  
  858.  3. Using the VX-REXX drag and drop programming feature to add code. 
  859.  
  860.  4. Testing a project. 
  861.  
  862. These are the basics. The following chapters expand on these basics to show how 
  863. to create and maintain complex as well as simple applications.