OS/2 Shareware BBS: 18 REXX/18-REXX.zip/vxdemo.zip/TUTBOOK.IN$/TUTBOOK.INF

OS/2 Help File | 1993-11-22 | 109KB | 731 lines

ΓòÉΓòÉΓòÉ 1. Welcome ΓòÉΓòÉΓòÉ

Welcome to the demonstration version of VXΓêÖREXX.

Click the Forward button to continue.


ΓòÉΓòÉΓòÉ 2. Introduction to VXΓêÖREXX ΓòÉΓòÉΓòÉ

WATCOM's visual development environment for OS/2 REXX is an easy to use,
powerful and fully integrated environment for creating applications that
exploits the graphical user interface capabilities of OS/2 2.x and Presentation
Manager. The product combines a project management facility, visual designer,
and an interactive source-level debugger to deliver a very approachable and
highly productive visual development environment.

Design applications visually

Create rich graphical applications quickly and easily using the visual design
environment. With the visual designer, you can graphically create Presentation
Manager objects, quickly customize their properties, and easily attach REXX
routines to the objects.

Powerful open environment

Enjoy the simplicity of event-driven programming together with global editing
capabilities essential for professional project management. The WATCOM visual
development environment is open and extensible through IBM's object oriented
System Object Model (SOM) technology. You can access all standard REXX APIs
including DB2/2 because the VXΓêÖREXX is based on the OS/2 2.x system REXX.

Intergrated development environment

Build, test, and debug your applications without leaving the development
environment. Then package your applications as an EXE file or PM macro for
royalty-free redistribution. The power of the integrated development
environment can also be used with your existing REXX applications.

Highlights

   o Easy to use visual development environment
   o Create and modify objects dynamically at both edit and run time
   o Powerful project management facility
   o Advanced interactive source-level debugger
   o Package your applications as EXE files or PM macros
   o Access standard REXX APIs including DB2/2
   o Create REXX code visually using drag and drop programming
   o System Object Model (SOM) based object manager
   o Support for multi-threaded applications
   o Include OS/2 style help and hints in your applications
   o Supports SAA CUA '91 objects
   o Autosizing and alignment of objects
   o Integrated console window support for existing REXX programs
   o Royalty-free run time library
   o Multiple modeless window support
   o Create PM macros for applications supporting REXX as a macro language

Click the Forward button to continue.


ΓòÉΓòÉΓòÉ 3. How to use this tutorial ΓòÉΓòÉΓòÉ

This tutorial shows you how to create applications with VXΓêÖREXX. The first two
parts show you how to use the tools and the system to create applications. The
third part of the manual is an alphabetical reference for all components of the
VXΓêÖREXX software.

At any point in the tutorial, you can click the Back button to review a
previous page. You can also press Forward to skip ahead. To see an outline of
the whole tutorial, press the Contents button.


ΓòÉΓòÉΓòÉ 4. Samples included with the demonstration version ΓòÉΓòÉΓòÉ

A number of sample programs come with the demonstration version of VXΓêÖREXX.
They are located in the Samples folder, in your WATCOM VX-REXX folder. All
samples come ready to run with full source code. Here is a list of the sample
programs:

Button         A simple first application with push buttons.

Calc           A four function calculator.

HintHelp       A demonstration of the run time help facility in VXΓêÖREXX.

MindGame       A pattern guessing game.

MMW            An example of modal and modeless windows.

Movies         A multimedia sample that plays OS/2 movies (AVI files).

SampleDB       A database sample (requires IBM DB2/2).

Scan           An EPM macro that scans through the current file looking for
               REXX labels.

Threads        A sample of a multithreaded program.

WinCtrl        This program lists the top level frame windows on the desktop
               and lets you minimize, maximize, restore, and shake them.


ΓòÉΓòÉΓòÉ 5. About the demonstration version of the software ΓòÉΓòÉΓòÉ

The demonstration version of VXΓêÖREXX differs from the full version in a number
of ways:

o The full version 2 software includes containers, notebooks, sliders, value
  sets, and DDE client objects.

o The full version includes the online version of the VXΓêÖREXX Programmer's
  Guide and Reference manual.

o You cannot save projects, make standalone executables, or make macro files
  using the demonstration version.


ΓòÉΓòÉΓòÉ 6. System requirements ΓòÉΓòÉΓòÉ

The minimum recommended configuration for WATCOM VXΓêÖREXX is a 20 megahertz 386
personal computer with 8 megabytes of memory. About 5 megabytes of hard disk
space are required to install the software.

IBM OS/2 version 2.0 with the OS/2 Service Pak or higher must be installed
prior to installing VXΓêÖREXX. If you are running OS/2 2.0 without the OS/2
Service Pak, you must obtain it from IBM and install it to make sure that all
features of VXΓêÖREXX work correctly. The Service Pak required is IBM number
XR06055. You can obtain it from the IBM OS/2 BBS, from CompuServe, or directly
from IBM. Contact your IBM representative for more information.

The OS/2 REXX interpreter and the REXX information must also be installed prior
to installing VXΓêÖREXX.


ΓòÉΓòÉΓòÉ 7. How to contact WATCOM ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1. In North America (and all other non-European locations) ΓòÉΓòÉΓòÉ

WATCOM International Corporation.

415 Phillip Street, Waterloo, Ontario, CANADA, N2L 3X2

Technical Support
hot-line:   [phone]
fax:        [phone]
BBS:        [phone]
Internet:   [e-mail]
Compuserve: type GO WATCOM

General Inquiries
tel: [phone]
fax: [phone]

Sales, upgrades, other product
orders, and reseller inquiries/orders:
1-800-265-4555 (toll free in North America)


ΓòÉΓòÉΓòÉ 7.2. In Europe ΓòÉΓòÉΓòÉ

WATCOM Europe Limited.

PO Box 64, LIVINGSTON, West Lothian, EH54 7AE, UNITED KINGDOM

Technical Support
    United Kingdom
        tel: [phone]
        fax: [phone]

    Other Locations
        tel: [phone]
        fax: [phone]

    BBS: [phone]
    Internet: [e-mail]
    Compuserve: type GO WATCOM

General Inquiries
    United Kingdom
        tel: [phone]
        fax: [phone]

    Other Locations
        tel: [phone]
        fax: [phone]

Sales, Upgrades, other product orders, and reseller inquiries/orders:
    United Kingdom Toll Free
        tel: [phone]
        fax: [phone]

    Germany Toll Free
        tel: [phone]
        fax: [phone]

    France Toll Free
        tel: [phone]
        fax: [phone]

    All Other Locations
        tel: [phone]
        fax: [phone]


ΓòÉΓòÉΓòÉ 8. A simple program ΓòÉΓòÉΓòÉ

This chapter provides a brief introduction to the VXΓêÖREXX development
environment through a tutorial. We will learn how to start and stop VXΓêÖREXX and
create, and run a simple application. In addition, the drag and drop
programming feature of VXΓêÖREXX will be used to reduce the time and effort
needed for writing code. The same steps used in this tutorial can be used to
develop all VXΓêÖREXX applications. Subsequent chapters provide more details
about each step.

In this tutorial, you will create an application which consists of an entry
field, push button, and list box. When run, text typed in the entry field will
be added to the list box using the push button.


ΓòÉΓòÉΓòÉ 8.1. Starting VXΓêÖREXX ΓòÉΓòÉΓòÉ

You can start VXΓêÖREXX by double clicking on the VXΓêÖREXX icon in the WATCOM
VXΓêÖREXX folder on your desktop. After it starts, you will see a window similar
to Figure 1.

Figure 1  The initial VXΓêÖREXX screen.

The VXΓêÖREXX interface consists of a menu bar, a tool palette, and a project
window containing a grid of dots. The menu bar contains the commands that are
used to create and run applications. The tool palette contains the objects
which can be placed in the project window to create the user interface for an
application.

Note:  The demonstration version of VXΓêÖREXX automatically opens the tutorial
book when it starts up.


ΓòÉΓòÉΓòÉ 8.2. Creating an application ΓòÉΓòÉΓòÉ

There are three basic steps to building a VXΓêÖREXX application:

 1. Creating the user interface by adding objects to the project window.

 2. Customizing each object's properties.

 3. Attaching code to each object.

We will go through these steps in the following sections to create a simple
application.


ΓòÉΓòÉΓòÉ 8.3. Creating the user interface ΓòÉΓòÉΓòÉ

Creating the user interface is the first step in building an application. The
interface to this application has three objects: an entry field, a push button,
and a list box. We will start by adding the entry field to the window:

 1. Click on the Tools menu and then choose EntryField.

 2. Position the mouse pointer near the top left corner of the project window.

    The cursor will change to a cross while it is positioned on the project
    window.

 3. Hold down mouse button 1 and drag the mouse down and to the right until the
    entry field is approximately the size of the one shown in Figure 2.

        Figure 2  The entry field added to the window.

 4. Release the mouse button.

Add the push button to the window using a similar procedure:

 1. Click on the Tools menu and then choose PushButton.

 2. Position the cursor below the bottom left corner of the entry field.

 3. Hold down mouse button 1 and drag the mouse down and to the right until the
    push button  is approximately the size of the one shown in Figure 3.

        Figure 3  The push button added to the window.

 4. Release the mouse button.

Repeat the above steps using the ListBox item from the Tools menu to make your
window similar in appearance to Figure 4.

Figure 4  The entry field, push button and list box on the window.

Finally, to improve the appearance of the window, center the three objects on
the window as follows:

 1. Position the cursor on the entry field.

 2. Press and hold down mouse button 1. Sizing handles will appear along the
    border of the entry field. Move the cursor over the push button and then
    over the list box. Now all three objects will have sizing handles along
    their borders. The screen should look similar to  Figure 5.

        Figure 5  The entry field, push button and list box are selected.

 3. Release mouse button 1.

 4. Position the cursor on the entry field once again and press mouse button 2
    to invoke the VXΓêÖREXX pop-up menu.

 5. Select the Align menu item using mouse button 1. A second menu will appear.
    From this menu, click on the menu item used for centering objects as shown
    in Figure 6.

        Figure 6  The menu item used to centre objects.
    The push button and the list box will now be centered underneath the entry
    field.

 6. Position the cursor over the right border of the window. The cursor shape
    should change to a sizing arrow.

 7. Hold down mouse button 1 and move the cursor left or right to adjust the
    width of the window until the objects are centered.

 8. Click on the window background to deselect the objects.

The screen should appear as in  Figure 7.

Figure 7  The objects centred on the window.

All the objects we need have been created. Now their properties must be
customized.


ΓòÉΓòÉΓòÉ 8.4. Customizing object properties ΓòÉΓòÉΓòÉ

Each VXΓêÖREXX object has properties such as color and size which can be
customized. An object is given default property values when it is first
created. Often, these properties need to be changed.

The entry field has a font property which determines the font used to display
text. The height of the entry field should be set according to the size of the
font being used. This step can be done automatically using the entry field's
Autosize property. If this property is set to 1, the height of the entry field
will be adjusted automatically based on the font being used. Initially, the
Autosize property is set to 0. Change it to 1 as follows:

 1. Click mouse button 2 anywhere over the entry field. A pop-up menu will be
    displayed.

 2. Choose the Properties menu item. A property notebook will be displayed.

 3. Click on the Size index tab. The Size page will be displayed as in Figure
    8.

        Figure 8  The size page of the property notebook.

 4. Click on the check box marked Autosize.

 5. Close the entry field's property notebook by double clicking on the title
    bar icon in the upper left corner.

The text which appears on a push button is called the caption and is determined
by the push button's Caption property. To set the caption of the push button to
Add Item:

 1. Click mouse button 2 anywhere over the push button and choose Properties to
    open the push button's property notebook.

 2. Click on the Text index tab. The Text page will be displayed as in Figure
    9.

        Figure 9  The text page of the property notebook.

 3. Click on the Caption entry field and type:

        Add Item

 4. Close the property notebook. The text Add Item will appear on the push
    button.

Lines in a list box are displayed one below another, beginning at the top. The
last line in the list box may not appear completely, depending on the height of
the list box. The height must be adjusted if this characteristic is
undesirable. To have the height adjusted automatically, set the AdjustHeight
property of the list box as follows:

 1. Open the property notebook for the list box using the same method as
    before.

 2. Turn to the Size page by clicking on the Size index tab.

 3. Click on the AdjustHeight check box.

By default, items in a list box will be sorted in ascending order. For our
application, we want items to be listed in the order they are added to the list
box. The list box's Sort property must be changed:

 1. With the list box property notebook open, turn to the List page by clicking
    on the List index tab.

 2. Click on the scroll arrows in the Sort drop down combobox.

 3. Choose none from the drop down list.

 4. Close the property notebook by double clicking on its title bar icon.

Finally, set the text that will appear on the window title bar:

 1. Open the property notebook for the window. Note that the cursor must be
    positioned on the window but not over any object in the window when
    pressing mouse button 2.

 2. Index tabs for all pages in the notebook cannot be seen at once. The tab
    scroll arrows at the top and bottom right corners of the notebook, as shown
    in Figure 10, must be used to view all the index tabs. Press mouse button 1
    on the bottom right tab scroll arrow until the Text index tab appears.

        Figure 10  The window's property notebook.

 3. Open the Text page of the notebook by clicking on the Text index tab.

 4. Click on the Caption entry field and type:

        Sample

 5. Close the property notebook.

The first two steps in developing the sample application are complete: creating
the objects and customizing their properties.


ΓòÉΓòÉΓòÉ 8.5. A preliminary run ΓòÉΓòÉΓòÉ

Although the sample program is not finished you can run it to see what it will
look like when complete. To run it, click on the Run menu and choose Run
project. This will hide VXΓêÖREXX and run the application, which should appear
similar to Figure 11:

Figure 11  A test run of the sample program.

Notice that the background of the window no longer contains a grid of dots.
Type text into the entry field to see how it will appear. Use the Tab key to
move between the objects. Click on the push button. Nothing happens because no
code has been attached to the push button. Attaching code to the objects in the
window is the next step in developing our sample application.

Exit the application and return to VXΓêÖREXX by clicking on the title bar icon
and choosing Close.


ΓòÉΓòÉΓòÉ 8.6. Attaching code to objects ΓòÉΓòÉΓòÉ

In this application pressing the push button will add the text in the entry
field to the list box. We will use the drag and drop programming feature of
VXΓêÖREXX to help us write the code which will perform this task. First we must
obtain the text in the entry field. To attach this code to the push button:

 1. Open the push button's property notebook and turn to the Event page by
    clicking on the Event tab. Code can be attached to the push button for any
    events which appear on this page.

 2. Select Click and then click on Open to invoke an editor we can use to write
    our code. The editor will contain a skeleton for an event routine, as shown
    in Figure 12.

        Figure 12  Event routine skeleton

    The first line in the editor is a comment, the second is the name of the
    routine, and the last line contains a REXX return instruction which needs
    to be executed at the end of the routine. The REXX code we place in this
    routine will be executed when the push button is pressed.

 3. At this point, we could write code manually but there is a much easier
    method. Press and hold down mouse button 2 over the entry field. Now move
    the mouse over the editor. The editor window and the application window may
    need to be moved apart before this step can be done. A line joining the
    mouse to the entry field will appear as in Figure 13:

        Figure 13  Getting the text in the entry field.

 4. Release mouse button 2. A dialog box will appear which lists descriptions
    of all the entry field methods which can be invoked and all the entry field
    properties which can be set or retrieved.

 5. Click on the Value item under the Get property heading. We need to get the
    Value property because it contains the text in the entry field. Now click
    on OK. The following instruction is placed at the insertion point in the
    editor:

        value = VRGet( "EF_1", "Value" )

    This instruction will assign the variable value with the text in the entry
    field.

The automatic code generation feature of VXΓêÖREXX we have used is called drag
and drop programming. Using this feature, you can create REXX applications
without having to memorize the syntax of VXΓêÖREXX functions and methods.

The next step is to add the text to the list box:

 1. Press and hold down mouse button 2 over the list box and then move the
    pointer over the editor window. A line joining the cursor to the list box
    will appear.

 2. Release mouse button 2. A dialog box will appear listing all the list box
    methods that can be invoked and all the list box properties which can be
    set or retrieved. Click on the Add a string item under the Methods heading
    and then press the OK button.

 3. Another dialog box, as shown in  Figure 14, will appear.

        Figure 14  The Add a String dialog box.

 4. Click on the string field and type the following:

        value

 5. Click on the Quoted String check box. Now it should not be checked.

 6. Press the OK button. The REXX code to add the text to the list box will be
    placed underneath the previous instruction, as shown in Figure 15.

Figure 15  The event routine for the push button.

After getting the text, we should clear the entry field to allow new text to be
entered:

 1. Press and hold down mouse button 2 over the entry field and then move the
    mouse over the editor window.

 2. Release mouse button 2. A dialog box will appear.

 3. Click on the Value item under the Set property heading and then press the
    OK button.

 4. Click on OK from the second dialog box. The editor window should now appear
    as in  Figure 16.

        Figure 16  The unfinished push button event routine.

The push button will have the focus when this routine is executed. We should
set the focus to the entry field so that new text can be entered immediately:

 1. Press and hold down mouse button 2 over the entry field and then move the
    mouse over the editor window.

 2. Release mouse button 2.

 3. Click on the Set focus to object item underneath the Methods heading and
    then press the OK button. A line of code will be inserted below the
    previous lines in the editor window.

 4. Close the editor window by double clicking on its title bar icon.

The push button event routine is now complete and is shown in Figure 17. We can
perform a test run to see if it works correctly.

Figure 17  The complete push button event routine.


ΓòÉΓòÉΓòÉ 8.7. A test run ΓòÉΓòÉΓòÉ

To run the application, click on the Run menu and choose Run project. The
application window will look the same as it did during the first run. We have
not changed its appearance. However, try clicking on the push button after
typing text into the entry field. Now the text is added to the list box. Also,
the entry field is cleared and is given the focus again. The push button click
routine we created appears to be working as it should.

Try adding more text to the list box. Also, try pressing the push button when
there is no text in the entry field. It seems as though no action is performed.
However, if more text is added to the list box, you can see that a blank line
is inserted when the entry field is empty and the push button is pressed, as
shown in Figure 18.

Figure 18  Adding text to the list box.

This behavior is undesirable and needs to be prevented with the addition of
more code. Also, to make the application easier to use, we should allow text to
be added to the list box with the use of the Enter key.


ΓòÉΓòÉΓòÉ 8.8. Improving the application ΓòÉΓòÉΓòÉ

A push button can be enabled or disabled. When enabled, a push button responds
to events such as a click event. The push button in our application has always
been enabled. When a push button is disabled it does not respond to any events
and also appears grayed. In particular, a disabled push button cannot receive
the focus and will not respond when pressed. We will use this property of push
buttons to prevent blank lines from being added to the list box:

 1. Press mouse button 2 anywhere over the entry field to activate the VXΓêÖREXX
    pop-up menu.

 2. Click on events and then click on change. The editor window will appear
    with the skeleton of a routine, as shown in  Figure 19.

        Figure 19  The entry field change routine.

    This routine will be executed whenever the contents of the entry field
    change. We need to determine if the entry field has become empty and if
    this is the case, we will disable the push button to prevent it from adding
    any text to the list box.

 3. Press and hold down mouse button 2 over the entry field, move the mouse
    over the editor window and then release the mouse button. As before, a
    dialog box will appear.

 4. Click on the Value item underneath the Get property heading and then press
    OK. The code to get the contents of the entry field will be generated.

 5. Add the following line of code at the insertion point:

        if value = "" then do

    Press the Enter key and then the Tab key at the end of this line.

 6. At this point, we have determined that the entry field is empty so we must
    disable the push button. Press and hold down mouse button 2 over the push
    button, move the mouse over the editor window and then release the mouse
    button. A dialog box listing all methods and properties of a push button
    will appear.

 7. Click on the Enabled item under the Set property heading and then press OK.
    A second dialog box will appear, as shown in Figure 20.

        Figure 20  The enabled property dialog box.

    Click on the Enabled check box so that it is not checked. Press OK. The
    instruction to disable the push button is placed at the insertion point in
    the editor window.

 8. Now we need to add the code that will enable the push button when the entry
    field is not empty. Add the following lines at the insertion point:

        end
        else do

    Press the Enter key and then the Tab key at the end of the second line. The
    editor window should appear as in Figure 21.

        Figure 21  The incomplete entry field change routine.

    Press and hold down mouse button 2 over the push button, move the mouse
    over the editor window and then release the mouse button. From the dialog
    box click on the Enabled item under the Set property heading and then press
    OK. Press OK again on the second dialog box which appears. The code to
    enable the push button is inserted into the editor window.

 9. One last line needs to be added to the routine:

        end

    The complete routine is shown in Figure 22.

        Figure 22  The complete entry field change routine.

Now we must make the push button disabled when the application is first run:

 1. Open the push button's property notebook and turn to the Style page. Click
    on the Enabled check box so that it is not checked.

 2. Also on this page is the Default check box. Click on this check box so that
    it becomes checked. Now, when the Enter key is pressed the push button
    click routine will be executed, as though the push button had been pressed.
    This behavior will allow text to be added to the list box by pressing the
    Enter key.

We can easily make another improvement to the application by using the Hints
feature of VXΓêÖREXX:

 1. Turn to the Hint page of the push button's property notebook. Type the
    following in the Hint entry field:

        Add the text to the list box.

 2. Open the entry field's property notebook, turn to the Hint page and type
    the following:

        Enter text.

 3. Open the window's property notebook, turn to the Hint page and click on the
    ShowHints check box. Select the Bottom item from the Status Area drop down
    combobox. A status bar will appear at the bottom of the window, as shown in
    Figure 23.

        Figure 23  The status bar for showing hints.

    The status bar may overlap with the bottom of the list box. If this is the
    case then the list box can be raised or its height can be decreased.

The previous steps add hints to the application. When the mouse is moved over
the push button, its hint text will be displayed in the status bar. Similarly,
when the mouse is positioned over the entry field, its hint text will be
displayed. We can now try out the improvements we have made.


ΓòÉΓòÉΓòÉ 8.9. Running the application ΓòÉΓòÉΓòÉ

Run the application as before by clicking on the Run menu and choosing Run
project. Move the mouse over the entry field and then the push button to see
their hints. The application window is shown in  Figure 24.

Figure 24  Running the finished application.

Try typing in text and adding it to the list box with the use of the Enter key
as well as the push button. Notice that the push button becomes disabled
whenever the entry field is empty.

Although this is a simple application, it would take considerably more effort
and expertise to create it with other languages and development tools. However,
with VXΓêÖREXX features such as drag and drop programming, we have created it
easily with little knowledge of OS/2 or the REXX language.


ΓòÉΓòÉΓòÉ 8.10. Stopping VXΓêÖREXX ΓòÉΓòÉΓòÉ

To exit VXΓêÖREXX and return to the OS/2 desktop, click on the VXΓêÖREXX title bar
icon and choose Close or double click on the title bar icon.

In this tutorial, the following techniques have been learned:

 1. Adding objects to a window.

 2. Modifying an object's properties.

 3. Using the VXΓêÖREXX drag and drop programming feature to add code.

 4. Testing a project.

These are the basics. The following chapters expand on these basics to show how
to create and maintain complex as well as simple applications.