
VXREZ 1.2 -- Resource Binder for VX-REXX 2.0
--------------------------------------------

VXREZ is a set of macros that add resource binding capabilities to the
VX-REXX 2.0 design environment.  With these macros you can easily bind
resources (icons and bitmaps) to your executables.  Bound resources
are part of the .EXE file.

NOTE: VXREZ will not work if your project is saved in your VX-REXX
      root directory.  This is bad practice anyhow.


Adding Resources To Your Project
--------------------------------

Adding resources is very simple.  Make sure that VXREZ has been installed
properly by following the instructions in the README.TXT file.  You can
tell it's working by using the right mouse to bring up the popup menu
on a window.  The menu should display a new item "Edit resources...".

The first step is to save your project.  VXREZ will not work with
unnamed projects, and will tell you so if you try invoke the
"Edit resources..." menuitem without first saving the project to disk.

Next, invoke the "Edit resources..." menuitem.  This will bring up the
VXREZ main window, which is a mini text editor.  The text editor is used
to edit the .RC file which defines the resources for the project.  If
you are already experienced with .RC files, you may go ahead and enter
your resource information directly.

If you are not familiar with the syntax of a resource file, you may
instead move to the menubar and choose the "Insert resource..." item
under the "Edit" menu.  A dialog will appear prompting your for
resource information:

ID -- The number to assign the resource.  Choose a number between
1 and 65535.  You should give each resource a different
number.

File -- This is the pathname of the icon or bitmap file you wish
to bind to the executable.

Type -- This specifies whether the resource is an icon or a bitmap.

Preload, Moveable, Discardable -- These are resource options
that you probably will never use.  Leave them unchecked.

As an example, type 100 for the ID and test.ico for the filename.  Then
press the OK button.  A resource definition line will be inserted into
the resource file at the current cursor location.  The syntax is quite
simple and you may wish to add other resources manually.

You can add as many resources as you want.  The next step is to compile
the resources.


Compiling the Resources
-----------------------

OS/2 includes a resource compiler as one of the standard utilities, so
you do not need to purchase any special software.  Choose the
"Save and compile..." menuitem under the "File" menu.  This saves the
resource file to disk (in the same directory as your project) and
runs the OS/2 resource compiler on it.  The resource compiler converts
the .RC file into a .RES file, which contains all the resources that
will be bound to your executable.

Try compiling the example you typed in above.  A dialog will appear
informing you of a resource compilation error.  If you scroll to the
bottom, you'll see that error is 'File TEST.ICO not found'.  We need
to create the icon file TEST.ICO before we can successfully compile
the resource file.


Creating an Icon File
---------------------

Luckily, OS/2 also provides a utility called ICONEDIT.EXE that allows
you to create icons.  You can invoke it directly from the "Tools"
menu.  Its use is documented elsewhere.  But if you just want to
try it out, you can doodle on the drawing area with the mouse, then
save the icon to the file "TEST.ICO".  Just accept the defaults
for the icon formats.

Quit the icon editor and go back to the VXREZ main window, and
choose "Save and compile..." again.  The resource file should
compile without error this time, in which case no dialog will
appear.

Exit the VXREZ main window to return to your application.

IMPORTANT NOTE:  Always create your icons with at least TWO formats.
An icon with a single "Independent VGA" format is not good enough.
OS/2 requires at least a second format to display the icon properly
on the desktop -- no one knows why this is so, but it is.  The best
bet is to add the "8514 - 16 colors" format to the icon.  To do so,
just use the 'List...' option under the 'Device' menu in the icon
editor and then press the 'Add' button on the dialog.  Use the
'List...' menuitem to switch between the formats.  You can design
your icon in VGA format, copy it to the clipboard, then switch to
one of the other formats and paste it.  Or you can build different
icons for each format if you want.


Testing the Resource
--------------------

To test whether or not your resource is actually there, bring up
the properties notebook for the Window object and type the following
value into the PicturePath field:

        #100

This tells VX-REXX to use the resource with ID 100 that is bound to
the executable.

Now choose "Run project" to run your project.  A small dialog window
will appear saying that the resources are being bound to the executable,
then the VX-REXX design environment will be minimized as usual and
your project will run.  You should see your icon centered on the
window.

NOTE:  Because of conflicts with the debugger, resources will not be
bound to your project in Debug mode.  They will only be bound in Run
mode and when you make an executable.


Making an Executable
--------------------

You make an executable in the usual fashion, except that before the
file dialog appears asking you to name the executable, you'll be told
that resources are being bound.


What if I don't have resources?
-------------------------------

If there is no .RC file in the project directory, no resources will
be bound to your executable.

That's it!  Have fun...





How it Works (for the curious)
------------------------------

VX-REXX currently uses the stub executables PMRUN.EXE and PMEXE.EXE to
build the test version and the executable version of a project.  The trick
is to run the resource compiler on those executables before VX-REXX
binds its own data to them.

Because VX-REXX is partly written using itself, a small modification
to the profile.vrm file can be used to install a new popup menu macro
and replace a couple of menuitem events.  When the user chooses
"Run project" or "Make executable", a VXREZ macro is run instead of
the usual internal routine in VX-REXX.  The macro does its thing
and then posts an event to allow VX-REXX to call the internal routine.

You could expand further on this method to add your own items to the
VX-REXX menubar, or change the behaviour of some existing items.  Note
that the next release of VX-REXX is not guaranteed to support anything
that is not publically documented by WATCOM.

Eric Giguere
giguere@watcom.on.ca
