-------------------------------------------------------------------------

   VeeColorizer
   Colorizes icons in VEE programs for better readability
  
   Author: Rolf Eichenseher <roffe@gmx.net>
   Version: 0.92

-------------------------------------------------------------------------

0. Overview
-----------
This program can be used to add color info to the "Detail View" of 
Agilent VEE programs for increased readability. 


1. Introduction
---------------
Graphic programming environments like Agilent VEE (formerly HP VEE) 
provide fast development results. But complex programs tend to look
confusing (from the developers view) because of many objects and 
connections between them.

One way to solve this is to paint objects in different colors, primarily 
depending on the function of an object. (For example, set loops and loop 
control statements to the same color, and paint function calls in another
color). This increases readability a lot, but since VEE does not support 
doing this automatically, you have to spend a lot of time painting each 
object individually.

The main thought behind VeeColorizer is to paint objects automatically 
depending on the object type. This is possible because VEE files are saved 
as normal text files.
 

2. Requirements
---------------
You need: Perl for Win32 (www.perl.org)


3. Invoking VeeColorizer
------------------------
3.1. On the command line

At the Command Prompt (e.g. C:\) say:
perl veecolorizer.pl [-options] inputfiles...

where [-options] can one or more of the following:
   -c <file> : read color table from <file> (default: colors.ini)
   -f        : force (overwrite existing colors)
   -q        : be quiet (don't print any information)
   -u        : uncolorize (remove color info from all objects)

3.2. From Windows Explorer

Put a link to the batch file "start-veecolorizer.bat" in the SendTo Folder 
(normally C:\Windows\SendTo).
Now you can right-click any VEE file, then select "Send to > / Vee Colorizer". 
If you do this with non-vee files, nothing happens because VeeColorizer 
searches the VEE file for the appropriate file before it does anything.

Every time you invoke the colorizer, a backup from the original .VEE file 
is created with the extension ".colorizer.bak". This is done for security 
reasons, if VEE is unable to load the colorized file. Of course, this 
shouldn't happen, but if... :-)


4. Tips and tricks
------------------
If you have a fast machine, you can execute the colorizer from the vee
program itself - that everytime your program is run, it colorizes itself. 
Changes made by the colorizer will become visible when you reload the .vee
file into Agilent VEE development version. This is especially useful during 
program development, but it takes a few seconds at program run, so make sure
to remove the colorizer call from your final version.


5. How it works
---------------
Basically, a VEE file holds a basic description of any object 
("device <number> <type>"). This is where main features (as type...FIXME) are 
defined. Additionally, properties for each object (color, position, title, 
description, settings etc.) are stored in a separate section called "devCarrierFor".
 Each entry consists of a key and one or more associated values, depending on 
the key type. This is the place where color info is stored, for the detail view
these are keys "titleBg" and "titleFg".

When invoked, VeeColorizer first looks for an object definition, starting with a 
new block beginning with the keyword "(device". Then a color table lookup is made
to find the correct color, and appropriate colors are stored along with the object
identifier. This continues until one of the following conditions become true:
   1. A "devCarrierFor" line for is found. Then color info is added by inserting 
      "titleBg" and/or "titleFg" lines. 
   2. A new context (scoping level) is found. Then all collected information about 
      "device" lines remain on the stack, and recursively "device" sections are 
      searched again.
   3. A context definition ends (this is when a sufficient number of closing brackets
      was found).


6. Known bugs and limitations
-----------------------------
This *should* also work for the HP-UX version of VEE, but THIS IS COMPLETELY UNTESTED!
If you have any experience with this, please send me a mail.


7. Want to help?
----------------
Comments, bugfixes and suggestions are welcome - and if you have created a nice "theme" 
(aka .ini-file), mail it to me <roffe@gmx.net>. It will be bundled with the next
"official" version of VeeColorizer.

 
8. Credits
----------
Christian Groeger and Steffen Walter for their ideas and testing, 
Porsche for their wonderful cars :-)
