                Run Menu
                --------
                        
The "Run" menu allows you to define your own menu items to
run external programs.  This can be used for frame grabbers,
printers, paint programs, image processing, text generation,
or any other MS-DOS application.

You define these menu items, and associated actions, by
placing commands in the PKTV.CFG (or EZSSTV.CFG) file.
The general format is:

        RUN_MENU "menu item" keyboard action action ...

Details:

    RUN_MENU

        The line begins with this in either upper or lower case.
        The entire command must appear on a single line, which
        could get quite long.

    "menu item"

        This is what you want to appear in the menu.
        For example: "HiRes 32..."
        You can omit the quotation marks (") if the item does 
        not contain any blanks.

    keyboard

        A single character for the keyboard equivalent.  
        When no menu is visible, the menus are searched from 
        left to right so the Run menu is first.
        If you defined a Run menu item with the letter "P", 
        pressing the P key would select this item instead of 
        Print in the File menu.
        In this case, you would have to display the File menu 
        first (with Alt-F) then press P to select the Print 
        function from the keyboard.

    action

        Finally, you specify one or more "actions" to perform.
        These include:

            SELECT="prompt"     - Display the file selector.
            PROMPT="message"    - Prompt user for text input.
            SAVE="file-name"    - Write the current image to 
                                  a file.
            RUN="command"       - Run a program or batch file.
            OPEN="file-name"    - Read an image file.
            DELETE="file-name"  - Delete a file.
            TEXT_FROM="file-name" - Draw text from command file.

        Again, the quotation characters (") may be omitted if 
        the item does not contain any spaces.  It is very 
        important to remember that there MUST NOT be any 
        spaces before after the equal sign (=).  This is valid:

                OPEN=XYZ.BMP

        But this is not valid:

                OPEN = XYZ.BMP



Text Command File
-----------------

The TEXT_FROM action takes commands from a file and draws
text in the current image.

The file may contain the following commands:

        FONT font-name          Can use either a font name
                                listed in Text menu or a
                                complete font file name.
        SIZE n                  n is in range of 1 to 4.
        BORDER n                1 for border, 0 for none.
        COLOR r g b             Text color.  r, g, b are
                                in range of 0 to 255.
        COLOR2 r g b            Secondary color when gradient
                                (color fade) is used.
        GRADIENT n              0 for solid color, 1 to fade
                                from one color to another.
                                (Like using right mouse button
                                with the built-in paint program.)
        X n                     Horizontal position, from left.
        Y n                     Vertical position, from top.
        NEWLINE                 Move text cursor to next line.
        "Text"                  Draw text.  The quotation marks
                                may be omitted if the message
                                does not contain a command
                                keyword listed earlier.


Examples
--------

More details are contained in the examples below.  When 
adding your own it is easiest to start with an example 
closest to your needs and make minor adjustments.


Example: MS-DOS Prompt
----------------------

        RUN_MENU "DOS prompt..." ! RUN=

This is a special case of the RUN action item which gives you 
the MS-DOS command interpreter.

When you pick the "DOS prompt..." menu item, or press the "!" 
key, you will get the MS-DOS command prompt.  When you type 
"EXIT", control will return to Pasokon TV.


Example: Frame grabbers
-----------------------

For Ventek VIP 640C:

        RUN_MENU "VIP 640C..." V RUN="PKVIP DIG~TMP.TGA" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

The PKVIP program grabs an image from the VIP 640C video 
digitizer and stores it into the specified file.   There is 
nothing special about the file name.  I just happened to put 
the ~ character in the middle to minimize the chance of 
overwriting some existing file.  

The OPEN action causes the specified file to be read. 

The DELETE action causes the specified file to be deleted.

PKVIP.EXE is described in the file PKVIP.TXT.

PKVIP was written by Ventek in response to all the people who 
wanted to use their product with Pasokon TV.  Please contact 
them if you need further assistance with this program.


For Digital Vision Computer Eyes RT:

        RUN_MENU "Eyes RT..." E RUN="HAMCAP TG=DIG~TMP" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

Note that there is no file type specified in the TG= command
line argument.

Here is a slight variation:

        RUN_MENU "CE RT S-Video..." E RUN="HAMCAP SV=1 TG=DIG~TMP" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

The only difference is the "SV=1" command line option which 
means use the S-video input rather than the NTSC composite input.

HAMCAP.EXE is based on the CECAP program and is described in
the files CECAP.TXT and HAMCAP.TXT.

HAMCAP was written by Digital Vision in response to all the 
people who wanted to use their product with Pasokon TV.  Please 
contact them if you need further assistance with this program.  
I borrowed one of these, from a local vendor, during development
but don't have it any more.

Note: The File menu has a predefined item for running a video
digitizer program.  You can't change the menu item and keyboard
equivalent but the action items are the same as the Run menu.


Example: A non-supported printer
--------------------------------

        RUN_MENU "Acme Print" P SAVE=SSTV~TMP.BMP
                RUN="ACMEPRIN SSTV~TMP.BMP" DELETE=SSTV~TMP.BMP

Pasokon TV has built-in support for most popular types of
printers used with personal computers.  Other printer types
can be used with suitable external programs.

In this case, pressing the "P" key would save the current 
image in a temporary file called SSTV~TMP.BMP, run the 
hypothetical ACMEPRIN program to print the file, and finally
delete the file.


Example: Paint program - HiRes 32
---------------------------------

        RUN_MENU "HiRes 32..." H SAVE=\HIRES32\SSTV~TMP.TGA256
                        RUN=HIRES32.BAT
                        OPEN=\HIRES32\SSTV~TMP.TGA256
                        DELETE=\HIRES32\SSTV~TMP.TGA

Note: This must appear on a single long line.  It was broken into
4 lines, above, to fit better in this document.

The SAVE action, causes the current image to be stored into a
file called SSTV~TMP.TGA.  The special file extension of ".TGA256"
means store it as a 256 x 240 image with only 32K colors for
compatibility with older versions of HiRes 32.

Next, the RUN item means run a batch file called HIRES32.BAT.
This file contains these commands:

        cd \hires32
        hires32.exe
        cd \pktv31

The HiRes 32 program does not use a command line argument for
a file name.  Instead it looks for the specific name SSTV~TMP.TGA.
It reads this file automatically.  When you exit from the program
it saves the results in this file.

When Pasokon TV regains control, the OPEN action item tells it
to read the modified SSTV~TMP.TGA file.  The extra "256" on the
end of the file name extension is for compatibility with version
2 and has no effect.

Finally, the DELETE item gets rid of the temporary file.


Example: Paint program - Neopaint
---------------------------------

This is very similar to the HiRes 32 example above.

        RUN_MENU "Neopaint..." N
                        SAVE=\NEOPAINT\SSTV~TMP.BMP
                        RUN=NEOPAINT.BAT
                        OPEN=\NEOPAINT\SSTV~TMP.BMP
                        DELETE=\NEOPAINT\SSTV~TMP.BMP

Note: This must appear on a single long line.  It was broken into
5 lines, above, to fit better in this document.

The SAVE action, causes the current image to be stored into a
file called SSTV~TMP.BMP which preserves all 16 million colors.

Next, the RUN item means run a batch file called NEOPAINT.BAT.
This file contains these commands:

        cd \neopaint
        neopaint.exe sstv~tmp.bmp
        cd \pktv31

The program is not very happy if run from another directory so
we must first "CD" to its directory.
Neopaint gets the file name from the command line argument and
reads in this image automatically.
When you exit from the program it saves the results in this file.

When Pasokon TV regains control, the OPEN action item tells it
to read the modified SSTV~TMP.BMP file.  

Finally, the DELETE item gets rid of the temporary file.



Example: Image creation program
-------------------------------

        RUN_MENU Flag Z RUN="FLAG FRANCE FRANCE.TGA" 
                        OPEN=FRANCE.TGA DELETE=FRANCE.TGA

This simple program generates flags for a several countries.

The type of flag can be changed by specifying a different
country on the command line.  Source code, FLAG.C, is provided
so those interested can see how it works and use it as a
starting point for their own applications.


Example: Read a GIF file
------------------------

        RUN_MENU "Read GIF" U SELECT="Pick GIF file"
                        RUN="gif2tga %1 sstv~tmp.tga"
                        open=sstv~tmp.tga delete=sstv~tmp.tga

This version of Pasokon TV does not read GIF files.  The 
reason is that Unisys holds a patent for the compression 
technique used in GIF files.  Anyone using GIF files in a 
commercial or shareware product must obtain a license and pay 
hefty royalties on every copy sold.  That's why GIF support is
disappearing from more and more programs.

This restriction does not apply to completely FREE (not
shareware) software.

You really wouldn't want to save your beautiful SSTV pictures
in GIF because it can handle a maximum of only 256 colors.
However, there might be cases where you'd want to read an 
existing GIF file.  Here is a work-around.

Define a menu item as shown above.  The SELECT action item
means display the file selector with the prompt shown.
In the RUN action item, the "%1" means the result of the 
first SELECT item.  An external program is used to convert
the specified GIF file to a TGA file.  This temp file is
read and deleted.

The GIF2TGA program is a free program.  It is being passed 
along as a free service because there is some space left 
over on the diskette.  It is not part of the purchase price.

Obviously, the same technique could be used with any other
image conversion program that is controlled by command line
arguments.


Example: Contest Assistant
--------------------------

Here is a handy little program to help you in SSTV contests.

First, add this to the PKTV.CFG file:

        RUN_MENU "Contest..." C
                PROMPT="Enter call of other station"
                RUN="CONTEST %1"
                TEXT_FROM=CONTEST.CMD
                DELETE=CONTEST.CMD

This is how it works.

Operator:

1. Pick the "Contest..." menu item, or press the "C" key.
2. A dialog box appears with the message "Enter call of
   other station" and a space to type in text.
3. Type in the other call and press enter or click on OK.
4. Optionally enter a comment then press enter or click OK.

CONTEST.EXE program runs:

1. Generate the next available sequence number.
2. Record information in a log file.
3. Create a text command file to add text to image.

Pasokon TV:

1. Interprets the commands in CONTEST.CMD and puts
   text on image.


Example: Remote control of transceiver
--------------------------------------

Many modern ham transceivers have the ability to accept commands
from a serial port.  You might want to define menu items to
move to your favorite frequencies.  Suppose you had a program
called SETFREQ which would set the frequency of your transceiver.
You might define menu items resembling:

        RUN_MENU "14.230" 1 RUN="SETFREQ 14230 USB"
        RUN_MENU "14.233" 2 RUN="SETFREQ 14233 USB"
        RUN_MENU "3.857" 3 RUN="SETFREQ 3857 LSB"
        RUN_MENU "3.862" 4 RUN="SETFREQ 3862 LSB"

Just press 1, 2, 3, or 4 to jump between your favorite spots.

This example uses an imaginary program called SETFREQ.  If 
someone sends me examples of real programs I'll use them instead.


Example: An MS Windows program
------------------------------

It is possible to start a Microsoft Windows (3.1) application 
from the MS-DOS command line like this:

        win c:\windows\pbrush c:\pktv31\sstv~tmp.bmp

This means:
    1. Start Microsoft Windows.
    2. Automatically run the Paintbrush program.
    3. Pass a file name to the application, causing it to
        automatically read that file when it starts up.

You might be tempted to try something like this:

        RUN_MENU "Paintbrush..." P SAVE=SSTV~TMP.BMP 
                RUN="win c:\windows\pbrush c:\pktv31\sstv~tmp.bmp" 
                OPEN=SSTV~TMP.BMP DELETE=SSTV~TMP.BMP

I tried it and it gave me some error message about VDA.386 
whatever that is.

I suspect it is impossible, or at least difficult, to make this
work because Pasokon TV has already grabbed most of the memory
for itself.  There is not enough left over to start Windows.

