This will replace the current section in the manual titled:

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
             Customizing the Popup Menu and the Hot Keys


There are many ways to configure VMD to suit your tastes.  All you
have to do is get the code, modify it, and recompile.  Okay, I am
kidding here.  There are a lot of ways to tweak VMD without getting
down into the code, but they do require you to know some of the VMD
scripting language.  The amount depends on how much you want to change.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

				Hot Keys

VMD comes with some default kot keys.  When the mouse is in the
graphics display menu you can press 'r' to enter rotate mode, 's' for
scale and 't' for translate.  The full list of default hot keys is:

	r, R		enter rotate mode
	t, T		enter translate mode
	s, S		enter scaling mode
	0		query item
	1		pick atom
	2		pick bond (2 atoms)
	3		pick angle (3 atoms)
	4		pick dihedral (4 atoms)
	5		move atom
	6		move residue
	7		move fragment
	8		move molecule
	%		apply linear force to atom  (when connected to NAMD)
	^		apply linear force to bond		"
	&		apply linear force to angle		"
	*		apply linear force to dihedral		"
	x		spin about x axis
	X		rock about x axis
	y		spin about y axis
	Y		rock about y axis
	z		spin about z axis
	Z		rock about z axis
	+, f, F		advance one frame
	-, b, B		go back one frame
	., >		play animation forward
	,, <		play animation backward
	/, ?		stop animation

When you press a key, VMD finds if there is a command associated with
that key then executes it.  For instance, the '+' key is mapped to
"animate next" which advances all active molecules by one frame.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

			Adding New Hot Keys

But there are a lot of keys left over, so we provided a way for you to
add new hot keys, or even override our own definitions.  The command is

	user add key <key> <new command>

Using the '+' example, the command would be

	user add key + animate next

Here are some of the commands people I know use, which you might want
to try.  Odds are many will be made default hot keys in the final 1.2
release of VMD.

These are like the vi cursor control keys and let you rotate the
molecule around the x, y, or z axis by 2 degrees at a time:

		# rotate down with the 'j' key
		user add key j rot x by 2
		# rotate up with the 'k' key
		user add key k rot x by -2
		# rotate left with the 'l' key
		user add key l rot y by 2
		# rotate right with the 'h' key
		user add key h rot y by -2
		# rotate couterclockwise with the 'g' key
		user add key g rot z by 2
		# rotate clockwise with the 'G' key
		user add key G rot z by -2

Here is a quick way to scale in and out.  These keys are similar to
those used in a lot of games (like bz :)  :

		# make larger with the 'a' key
		user add key a scale by 1.1
		# make smaller with the 'z' key
		user add key z scale by 0.9


Reset the view (returns the "top" molecule to the center of the screen
and scaled to fit):

		user add key g display reset

Turns the Main menu off then on again.  Not only is this the fastest
way to open the form, but by turning it off first, the form will end
up being the foremost window on the screen:

		user add key M {menu main off ; menu main on}

The command here is in braces because of the way the intepreter works.
If they were not there, VMD would see two commands, split at the
semicolon, as in:

		user add key M menu main off
		menu main on

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
			Changes for the 1.2 release

The current version (starting with 1.2b1) has support for extra
modifier keys; Alt and Control.  However, it doesn't have support for
keys which don't have printable representations, like F9 or the Home
key.  Following are some of the hot keys which will be possible:

Quit, but verify first:

		user add key Alt-q quit confirm

Quit, without verification:

		user add key Alt-Q quit

Open the Files, Graphics and Main form, using the method just
described:

		user add key Alt-f {menu files off; menu files on}
		user add key Alt-g {menu graphics off; menu graphics on}
		user add key Alt-m {menu main off ; menu main on}

For emacs users, here are controls similar to the earlier vi-like
commands:

		user add key Control-n rot x by 2
		user add key Control-p rot x by -2
		user add key Control-f rot y by 2
		user add key Control-b rot y by -2

Remember, these Alt- and Control commands are only available in the
vmd-1.2b1 or later versions of VMD.  To get a "mailing list only"
sneak preview version of the latest binary, go to ftp.ks.uiuc.edu in
/pub/group/dalke, get vmd_IRIX5.Z, uncompress and chmod +X it, and
replace your current binary with it.  Since this is internal test
code, you might want to keep a copy of the original version, just in
case there is a bug.  For instance, in the binary available there
until today, the 'Control-' options did not work.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

			Changing the popup menu

The popup menu, available when you press the right mouse button when
the mouse is in the graphics display, has many menus, and each menu
has several items.  As with the hot keys, you can customize it by
adding more menus and items.

Menus in VMD are arranged hierarchically, starting from the main menu,
and each menu has a name.  A menu contains items, which may be a
command, a check-box command, or a separator.  New menus and the first
and last type of items may be added by a user.

To add a menu to the main pop-up menu, use:

	user add menu <name>

For example, I'll make a menu to load some of my most often used
structures:

	user add menu Favorites

Since there isn't anything in the menu, it doesn't appear in the popup
menu yet.  To add items to the menu, use:

	user add subitem <menu> <name> <command>

I often load the structures "alanin.pdb" and "brH.pdb" and remotely
download the 9pti structure from the PDB FTP site, so I'll add:

	user add subitem Favorites BPTI {mol pdbload 9pti}
	user add subitem Favorites alanin {mol load pdb alanin.pdb}
	user add subitem Favorites bR {mol load pdb brH.pdb}

Enter these three lines then bring up the popup menu.  You should see
the new menu item just above the "Help" lines.  Unless you are me, the
last two items probably won't work, but the first one should.  Try it
out.

You can also add a separator in the menu, using:

	user add subseparator <menu>

So if I want a separation between the first three molecules and the
fourth, the poliovirus 2PLV structure, you could do:

	user add subseparator Favorites
	user add subitem Favorites Polio {mol pdbload 2plv}



Sadly, the user modifiable popup menus are not hierarchical.  There is
no way to add a submenu to one of your own menus.  They can only be
added to the main popup menu.  However, there is another place to add
new menu items, the 'User Commands' submenu of the main menu. "Where
is it?" you ask?  It doesn't contain anything, so it isn't displayed.
You can add items to it just as you can to the main menu, but the
commands are slightly different.  Why are the menus this way?
Frankly, I don't know.  Anyone feel like improving them?

To add an item to the 'User Commands' menu:

	user add item <name> <command>

To add a separator to the 'User Commands' menu:

	user add separator

The usage is the same as their related commands, so I won't give a
detailed example, but to see how it works, try this:

	# Turn off the axis
	user add item {Axes Off} axes location off
	user add item {Axes On} axes location LowerLeft 
	# a break
	user add separator
	# delete all the loaded molecule
	user add item {Zap Everything} {
		foreach molecule [molinfo list] {
			mol delete $molecule
		}
	}

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

				Examples


Here are some more extensive ways to use the popup menus that I've
heard people using.

  = = = = = = = = = = = = = = =

Here is a way to set the amount of transparency for the different
colors by using the pop-up menu.  This is useful when fine tuning an
image:

	# Set the alpha value of the "transparent" materials
	proc set_transparency_value {alpha} {
		display update off
		# change the opaquicity of the transparent colors
		for {set color 17} {$color < 34} {incr color} {
			color change alpha $color $alpha
		}
		# and the transparent color scale (66 to 97)
		for {set color 66} {$color < 98} {incr color} {
			color change alpha $color $alpha
		}
		display update on
	}
	user add menu Transparency
	user add subitem Transparency 1.0 {set_transparency_value 1.0}
	user add subitem Transparency 0.9 {set_transparency_value 0.9}
	user add subitem Transparency 0.8 {set_transparency_value 0.8}
	user add subitem Transparency 0.7 {set_transparency_value 0.7}
	user add subitem Transparency 0.6 {set_transparency_value 0.6}
	user add subitem Transparency 0.5 {set_transparency_value 0.5}
	user add subitem Transparency 0.4 {set_transparency_value 0.4}
	user add subitem Transparency 0.3 {set_transparency_value 0.3}
	user add subitem Transparency 0.2 {set_transparency_value 0.2}
	user add subitem Transparency 0.1 {set_transparency_value 0.1}
	user add subitem Transparency 0.0 {set_transparency_value 0.0}

		
FYI, since this is a scripting language, the last 11 lines could be
replaced with:

	for {set i 1.0} {$i >= 0.0} {set i [expr $i - 0.1]} {
		eval "user add subitem Transparency $i {\
			set_transparency_value $i}"
	}

  = = = = = = = = = = = = = = =

For the other detailed example of uses for the popup menu, here's a
way to make a menu contain information specific to a given molecule.
In this case, it will be one of the myoglobin structures from Joel
Berendzen included in the vmd distribution.  Since I don't know where
you keep those files on your local disk, to use this example you'll
have to change the filename to fit your setup.  You really should use
cut and paste for this.  If you can't, don't worry about entering the
"Set View" item.

	# Create the submenu
	user add menu Myoglobin

	# Load the molecule, and print an error if 
	user add subitem Myoglobin {Load MBCO} {
		set top [molinfo top]
		#### CHANGE THIS TO POINT TO YOUR LOCAL COPY ####
		mol load pdb /nfs/cairo/workshop/mbco.pdb
		set newtop [molinfo top]
		if {$top == $newtop || $newtop == -1 } {
			error "Could not load mbco.pdb"
		}
		# keep track of the most recently loaded MBCO
		set mbco_molid [molinfo top]
	}

	# set the view so you look at the heme
	# Don't worry too much about figuring out what this does,
	# I just want to show some of the things VMD can do
	user add subitem Myoglobin {Set View} {
		rotate stop
		display resetview
		molinfo $mbco_molid set \
  {center_matrix rotate_matrix scale_matrix global_matrix} {
    {{1 0 0 1.875311} {0 1 0 -6.642823} {0 0 1 3.179466} {0 0 0 1}}
    {{0.950469 -0.149586 -0.272456 0 } {0.282904 0.779412 0.559000 0 }
    {0.128737 -0.608391 0.783126 0 } {0 0 0 1 } } {{0.073577 0 0 0} 
    {0 0.073577 0 0} {0 0 0.073577 0} {0 0 0 1}} {{1 0 0 0} {0 1 0 0}
    {0 0 1 0} {0 0 0 1}} }
	}

	user add subseparator Myoglobin

	# Turn on the backbone as a tube
	user add subitem Myoglobin {Backbone Tube} {
		mol color index
		mol selection protein
		mol representation tube 0
		mol addrep $mbco_molid
	}

	# turn on the Heme and the CO
	user add subitem Myoglobin {Heme and CO} {
		mol color name
		mol selection resname HEM
		mol representation licorice
		mol addrep $mbco_molid
		# get the FE as well
		mol selection resname HEM and name FE
		mol representation vdw 0.5
		mol addrep $mbco_molid
		# and the CO
		mol selection resname CO
		mol representation vdw 1.0
		mol addrep $mbco_molid
	}

	# turn on the two histidines near the heme
	user add subitem Myoglobin {HIS} {
		mol color resname
		mol selection resid 64 93
		mol representation lines
		mol addrep $mbco_molid
	}

	# show the myoglobin backbone in cylinders
	user add subitem Myoglobin {Cartoon} {
		mol color structure
		mol selection protein
		mol representation cartoon
		mol addrep $mbco_molid
	}
	user add subseparator Myoglobin

	# delete all the representations
	user add subitem Myoglobin {Delete Reps} {
		for {set i [molinfo $mbco_molid get numreps]} \
					{$i > 0} {incr i -1} {
			mol delrep 0 $mbco_molid
		}
	}

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

				The .vmdrc startup file

Finally, once you've defined all of these menus and hot keys, where
should you put them?  The best place would be your .vmdrc . When VMD
starts up but just before control is passed back to the user, VMD
looks for that file in one of three locations, the local directory,
your home directory, and the main VMD installation directory.  The
first file found is sourced, so a .vmdrc in the local directory
overrides the one in your home directory, etc.

As a hint to those that maintain VMD on their local site, if you want
to set up a local configuration file for others to use, make a file
(called, perhaps, .vmdrc.local) in the VMD installation directory.
Put the new commands in that file, and have those interested in
using the new commands add the line:

		source $env(VMDDIR)/.vmdrc.local

at the beginning of their own .vmdrc.  Don't forget to add this line to
the installation version of .vmdrc as well.