1.4.1 Creating a menu item
Before
you start - You really need to
have a good idea of how to run your program at the command line
before you try to make a GDE menu item to run it. Read the manual pages
or other documentation. Try it out. It will save you a lot of time and
frustration.
|
A GDE menu item contains a command to be executed to run a program, and
parameters that are substituted into that command.
Example:
#--------------- PROT2NUC - Reverse Translation ( 4/10/06) -----------------
item:PROT2NUC - reverse translation
itemmethod: sed "s/[#%]/>/" <in1 | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&
itemhelp: doc/xylem/prot2nuc.txt
itemopen:gde_help_viewer.csh
arg:LINLEN
arglabel:CODONS PER LINE
argtype:slider
argmin:5
argmax:100
argvalue:25
arg:GROUP
arglabel:NUMBERING INTERVAL (amino acids/codons)
argtype:slider
argmin:5
argmax:100
argvalue:5
in:in1
informat:flat
insave:
The itemmethod is the command that is executed to run the program. In
this case, the sed command is used to translate the GDE flat file
format into FASTA format. The output from the sed command is piped
directly to the prot2nuc program, using parameters LINLEN and GROUP
substituted into the command line. Output is redirected to the file
in1.out, which is launched using the text editor specified in the
$GDE_TEXTEDIT environment variable.
For a more complete description of how to write GDE menu items, you
really have to read Appendix B - Adding Functions in the
GDE
Manual.
Note
on GDE HELP
The example above shows the syntax for specifying a help file to be
opened in when the HELP button is pressed in a GDE item menu. The
general formula is:
itemhelp:filename
itemopen:program
where filename is the file to
open (path is relative to the GDE_HELP_DIR directory) and program is the program to open the
file. filename can also be a URL. program
is usually gde_help_viewer.csh, which chooses the viewer based on the
file extension.
There is one exception. Where a URL points to a named anchor in an HTML
document
(ie. a URL containing a '#' character) use
itemopen:browser.csh
gde_help_viewer.csh will not properly handle these types of URLs, so
browser.csh can
be called to force the file to be read in the BIRCH default browser.
All help files must be accessed through the $GDE_HELP_DIR. If you need
to specify a path to files that are not part of the main BIRCH
distribution, you can use the 'root' link,
which resides in all GDE help directories. This points to the root of
the directory tree, '/'.
So, for example, to get your GDE item to display the help file found in:
/export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html
Add the following lines to the .item file:
itemhelp:root/export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html
itemopen:gde_help_viewer.csh
To point to files in your $BIRCH/local directory, the GDE help
directories also have a symbolic link called 'local' eg.
itemhelp:local/doc/filename
|
Some of the subtleties for writing good GDE menu items are further
discussed in
GDEmenus Hints and Tips.
There are lots and lots of example of menu items in
$BIRCH/dat/GDE/makemenus/menus. As well, when you first install BIRCH,
the directory
$BIRCH/local/dat/GDE/makemenus/menus
will have some menu item files that you could edit to fit your
system. For example, there are a set of FASTA and BLAST menu item files
that you can edit to use your local copies of sequence databases. These
will override the generic FASTA and BLAST menus that are part of
the BIRCH core.
If you update your BIRCH system to a new release you may wish to
check the
$BIRCH/local-generic/dat/GDE/makemenus/menus
directory for new GDE menu item files that might be modified to work on
your site.
Note: None of the GDE menu item files will appear in the GDE menus
until you add their names to the menulist file, as described below.
1.4.2 Adding your menu item to
the
menulist file
Your GDE menu item file must have a file name of the form
name.item
where name is the name of the
menu item. It should be saved in
$BIRCH/local/dat/GDE/makemenus/menus/directory
where directory is the name
of the menu where you would like your item to appear. For example, if I
wanted to add a menuitem named paracelBLASTN.item to the Database menu,
it would be saved as
$BIRCH/local/dat/GDE/makemenus/menus/Database/paracelBLASTN.item
However, this .item file will be ignored unless we also add the name of
the file to the makemenus/menus/menulist file. In this example, we need
to have an entry added to the file that looks like this:
Database
paracelBLASTN
Note: the indentation is done by a single TAB character, NOT using
spaces. The syntax for creating a menulist file is more fully explained
in the manual page for makemenus.py.
Do not go any further before you read this page!
1.4.3 Merging
your
menu item into the .GDEmenus file
Finally, to get your menu item to appear in the GDE window, you need to
run makemenus.py. This is always done from the $BIRCH/dat/GDE/
directory. Just cd to that directory and type 'python makemenus.py'.
Your local menus items will be merged with the GDE core menus, to
create single .GDEmenus files in the GDEHELP directories. As described
in the makemenus.py
manual page, separate .GDEmenus files are made for each platform. For
example, if the paracelBLASTN command was only available on Solaris
hosts, your menulist file would look like this:
Database
paracelBLASTN S
Again, you have to read the makemenus.py
manual page for full details.
1.4.4 Testing
and
refining your menu item
For the new menu to appear, you have to launch a new GDE window after running makemenus.py.
This is because the menus in GDE are read from .GDEmenus only when the
program first starts. One trick for doing many test and refine cycles
is to run makemenus.py, and then, in your GDE window, choose Edit
--> Select All, and then Edit --> Extract. This will take the
contents of the current GDE window and launch a new GDE window, which
will have the updated menus. That saves having to launch GDE at the
command line and re-read the data each time you run the program.
The debugging process can be a difficult one . One of the most useful
tricks for debugging is to insert commands into the itemmethod:
commands that open up intermediate files in a text editor. That way,
you can see whether any given step was successful. For example,
itemmethod: sed "s/[#%]/>/" <in1 >in1.test; $GDE_TEXTEDIT in1.test; cat in1.test | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&
will let you verify that the sed command worked corrrectly before
prot2nuc is run.
Leverage the
multiwindow environment
For this kind of work, you can make things a lot easier by having
different windows for different steps. For the test and refine process
you might have the following windows on your screen:
- a text editor with your GDE menu item file
- a terminal window in the $BIRCH/dat/GDE/
directory. Run
makemenus.py in this window. If the only command you type in this
window is 'python makemenus.py', the shell's history command can save
you some typing. If you type '!!' the previous command will be repeated.
- a terminal window open to the directory in
which you are testing
GDE. Launch GDE from this window.
Using this strategy, moving back and forth between directories
does not
have to be done using 'cd'. Rather, you move between directories by
moving from one window to the other.