The Cabal's Secret Hideout

Our TradeWars 2002 Homepage

Web Master:













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.**"
addMenu "" "Menu" "Test Menu" "." "" "Menu" FALSE
addMenu "Menu" "option1" "Change Option 1" "A" :Menu_Opt1 "" FALSE
addMenu "Menu" "option2" "Change Option 2" "B" :Menu_Opt2 "" FALSE
addMenu "Menu" "execute" "Execute with current options" "C" :Menu_Exec "" TRUE

setmenuvalue "option1" "Hello"
setmenuvalue "option2" "World"

setmenuoptions "Menu" FALSE FALSE TRUE

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"

12  :Menu_Opt1
13  getmenuvalue "option1" $opt1val
14  if $opt1val = "Hello"
15       setmenuvalue "option1" "Goodbye"
16       openmenu "Menu"
17  else
18       setmenuvalue "option1" "Hello"
19       openmenu "Menu"
20  end

21  :Menu_Opt2
22  getmenuvalue "option2" $opt2val
23  if $opt2val = "World"
24       setmenuvalue "option2" "cruel World"
25       openmenu "Menu"
26  else
27       setmenuvalue "option2" "World"
28       openmenu "Menu"
29  end

30  :Menu_Exec
31  getmenuvalue "option1" $opt1val
32  getmenuvalue "option2" $opt2val
33  echo "**" & $opt1val & " " & $opt2val & "!**"
34  halt

(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.

Test Menu:
+ - Help on command
- Change Option 1 Hello
- Change Option 2 World
- Execute with current options


If you press 'a' and 'b', the menu display changes to:
Test Menu:
+ - Help on command
- Change Option 1 Goodbye
- Change Option 2 cruel World
- Execute with current options

If you then press 'c', you get the following output:

Goodbye cruel World!

Now for the line-by-line breakdown:
Line 1: This is just there for looks :)
Line 2: 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 in it.
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 particular menu.
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.

Line 8: 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.

Line 11:  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'.
Line 14: 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 toggle.
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 33.
Line 33: 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 probe script.
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 along.


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. -Traitor 5/27/03

Copyright 2002 - 2005, Chris Kent aka Traitor.  All rights reserved.  See About.html for more info.