GLOSSARY OF TW TERMS
Menus and Includes in TWX
In this article, I'm going to present
two more new features of TWX, menus and includes. The menus are
pretty straight forward, but the includes are a new concept that is
probably alien to anyone that's not a traditional programmer. In a
nutshell, includes are time savers. Say you have a certain routine
that is common to most of your scripts. Instead of re-creating that
routine or sub-routine in each of your scripts, you only have to write it
once, then use the include statement in your scripts, and when your script
compiles, it will also stick in that subroutine. I'll go into
includes in more detail below.
The following is a small sample menu in
TWX. I'm going to go through it more or less line by line. You
can also download it here, so you can
look at in notepad or whatever while you are reading along. I put in
some extra blank lines to help group lines of similar code.
echo "**This is a test menu.**"
2 addMenu "" "Menu"
"Test Menu" "." "" "Menu" FALSE
3 addMenu "Menu"
"option1" "Change Option 1" "A" :Menu_Opt1
4 addMenu "Menu"
"option2" "Change Option 2" "B" :Menu_Opt2
5 addMenu "Menu"
"execute" "Execute with current options" "C"
:Menu_Exec "" TRUE
6 setmenuvalue "option1"
7 setmenuvalue "option2"
8 setmenuoptions "Menu" FALSE
9 setmenuhelp "option1"
"This is a toggle. It is either 'Hello' or 'Goodbye'."
10 setmenuhelp "option2"
"This is a toggle. It is either 'World' or 'cruel World'"
11 openMenu "Menu"
13 getmenuvalue "option1"
14 if $opt1val = "Hello"
setmenuvalue "option1" "Goodbye"
setmenuvalue "option1" "Hello"
22 getmenuvalue "option2"
23 if $opt2val = "World"
setmenuvalue "option2" "cruel World"
setmenuvalue "option2" "World"
31 getmenuvalue "option1"
32 getmenuvalue "option2"
33 echo "**" & $opt1val
& " " & $opt2val & "!**"
(The line numbers
are in grey. They are there for reference only)
What this piece of code does is set up
some menu toggles so when you press 'execute', the script will either echo
back "Hello World!" or "Goodbye cruel World!" or some
combination of the two. Pretty simple.
When you run it, it will look like this on your display:
This is a test menu.
Help on command
A - Change Option 1
B - Change Option 2
C - Execute with current options
If you press 'a' and 'b', the menu
display changes to:
+ - Help on command
A - Change Option 1
B - Change Option 2
C - Execute with current options
If you then press 'c', you get the following output:
Goodbye cruel World!
Now for the line-by-line breakdown:
This is just there for looks :)
This is where I create the top level menu, called Menu. You can tell
it's the top level menu because it has no parent menu associated with
it. (That would be the first set of double quotes with nothing in
it.) The next set of quotes is the actual name of the menu as far as
TWX is concerned. When you open a menu, this is the name you
use. Be sure to always put it in quotes. The next set of
quotes is the display name, or the name of the menu that appears on the
screen. The next set of quotes is the hotkey associated with the
menu. You always need a hotkey, even if it's a top level menu.
In this case, I am using a '.' for the hotkey. The next one is the
label that is called when you press the hotkey. In this case, there
is no label for it to go to, so I again use the double quotes to show
nothing is there. The final set of quotes is the prompt. In
this case, I want my prompt to be "Menu". This is handy if
you have nested menus, so you know at what level of the menu you are
at. Finally, I have the FALSE statement there to indicate that I
don't want the menu to close when the hotkey is selected. So, now I
have initialized my top level menu, so now I need to put some selections
Lines 3 and 4:
These two lines are where I setup my menu options. Notice how I have
linked them to the top level menu, (called Menu), by putting
"Menu" in the first set of quotes. The second set is it's
name, the 3rd is what it looks like on the screen, 4th is the hotkey, 5th
are the labels that they call when the hotkey is pressed (in this case 'a'
or 'b'). Since these are simple toggles, I don't bother changing the
prompt, and since I don't want to exit the menu, I again put FALSE at the
very end. The menus are called option1 and option2.
Line 5: This
looks a lot like 3 and 4, except that I have TRUE at the end. This
means that when that hotkey ('c') is pressed, the menu exits because I'm
done with it at that point. Try changing the TRUE and FALSE
statements around if you are still unclear how it works, and then run it
again. It'll become pretty clear then.
Now that I've created my menu, I need to
setup the menu variables. This is how you setup default values for a
Line 6 & 7:
This is where I setup the default values for option1 and option2.
The values could be variables, or numbers if I wanted, but in this case,
it's 'Hello' and 'World'. When the script is run, you will see these
in the menu if you set them. You don't have to have values set for
menus if you don't want too either.
There are 3 optional menu entries that always appear at the top of your
menus, unless you tell TWX not to display them. They are '?' for
Command list, '+' for help on a command, and 'Q' to exit the menu.
Since I have no need of either the command list, or quit, I use this line
to turn those two options off, leaving only the help.
Line 9 & 10: This
is where I put in my help on command stuff. Pretty straight
forward. menu name, followed by the help. Remember that it all
has to be on the same line, but I've had help on command entries that were
over 500 characters, so there is no practical limit on the size.
Everything so far has been leading up to this command. This is what
actually opens up the menu.
Line 12: This
is the label for menu option1. If you press 'a', you end up here.
Line 13: In this line, I'm using the getMenuValue command to get the
current value of option1 and storing it in the variable $opt1val.
The first time you press 'a', $opt1val will be equal to 'Hello'.
This IF statement checks to see what the value of $opt1val is, and if it's
equal to 'Hello', it changes it to 'Goodbye' in line
15, and then returns to the main
menu in line 16.
If it's not equal to 'Hello', then it changes $opt1val to 'Goodbye', and
returns to the main menu. (Lines
17-20) This is how you make a
Lines 21-29: This
is just like the lines above it, only it toggles option2.
Line 30: This
is the label for menu execute.
Line 31 & 32:
Here, I'm grabbing the current values of the menus option1 and option2,
and making them equal to variables, so I can use them in the echo
statement below. This is the final check of the variables.
Before you hit 'c' and got to this point, you could press 'a' and 'b' all
day long and toggle them all you wanted. Once you hit 'c', those
values are set in stone, and are ready to be used by line
This is where I actually do something with the $opt1val and
$opt2val. I use them in an echo statement. Notice
how I use the & character to string them all together.
That is the menu commands in a
nutshell. I'll show you a slightly more complex use of menus in my
This script is not your typical probe script. Granted, it has
all the usual bells and whistles, but what makes this one unique AFIK, is
that it never sends a probe to a sector it's already seen. This
makes it way more efficient. In a stock 5k sector game, you can
probe the entire universe from start to finish for less than 8 mill,
compared to 15 mill you would spend if you fired a probe down every
sector. I use both menus and includes in this script, so take a look
at the documentation inside the script and you should be able to follow
As I mentioned in the beginning,
INCLUDES are handy when you want to save yourself a lot of typing by
creating modules that your scripts can import.
More later, as I have run out of time.