Customizing EXPGUI and Associated Programs
The EXPGUI GSAS graphical user interface can be modified in many
ways quite easily.
This document describes how the GUI works and how to modify the menus without
significant reprogramming. A little bit of programming in Tcl/Tk can go a
long way in adding new features. See the
Customizing examples, below.
EXPGUI
The main GUI is created by file expgui, which in turn uses the following files
sequentially:
- readexp.tcl
- gsascmds.tcl
- gsasmenu.tcl
Two additional files are read if they are found:
The first three files,
(readexp.tcl, gsascmds.tcl, gsasmenu.tcl)
must be located in the same directory where the expgui file is found.
The localconfig file also is read from this directory, if it exists.
The final file, .gsas_config, is read from the user's login directory (UNIX) or C:\ (Windows).
The localconfig and .gsas_config are intended to
contain system-wide and user-level default values for parameters
that are described in this document. Most routines have
a "Save Options" command that writes some of the current parameters to
file .gsas_config. Note that information in .gsas_config
overrides that in localconfig.
No error occurs if either of these files are not found.
The readexp.tcl and gsascmds.tcl files contain
tcl procedures that are
used for more than one application, so it is convenient to place them
in separate files. They are only of interest to someone trying to debug
or add new functionality to expgui.
The gsasmenu.tcl file defines the contents of the
menu bar, the contents of the
button bar and definitions for each command. The contents of this file
are designed to be modified and extended by users, either by editing the file,
or by overriding definitions in the localconfig or
.gsas_config files.
The important variables defined in the gsasmenu.tcl file are:
- expgui(menunames)
-
This list defines the menu bar headings other than File, Options & Help
- expgui_menulist
-
Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
defines commands to be added to a menu heading. Each command will appear
as an array element in expgui_cmdlist.
- expgui_cmdlist
-
Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
contains two items. The first defines a tcl procedure to be executed
when the command is invoked, or "-" if no command will be invoked and
the second contains help information describing what the command does.
Note that when menu item is selected the variable cmd is set to the
name of the command, so
expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
. For example, when powpref is selected, the tcl command
"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
- expgui(buttonlist)
-
This list defines the commands that will appear on the button bar where
each item that appears on the button bar must have a matching pair of entries
in expgui_cmdlist.
Thus if the command
set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
is placed in the localconfig or .gsas_config files this will
redefine the contents of the button bar.
In addition to the variables defined in the previous file, expgui, uses
a small number of array elements for other configuration options. They are:
- expgui(scriptdir)
-
This determines where files such as readexp.tcl, etc.
are located. This defaults to the location where expgui is located so
it rarely needs to be changed.
- expgui(gsasdir)
-
This contains the location of the GSAS directory, if it is not the
parent director where expgui is found.
This determines where a number of GSAS data files will be located. If expedt
crashes when you try to add new atoms, this is probably wrong.
- expgui(gsasexe)
-
This determines where the GSAS executable files are located.
You might want to change this is you keep multiple versions of GSAS
around or if you keep the GSAS files in a different location than
the default or want to keep the tcl files somewhere other than
in a subdirectory of the GSAS files.
- expgui(bkgcolor1)
-
Sets the background color for the bottom box on the phase pane.
The default value, #fdf, is a light violet that
will probably drive some folks nuts, but is a good contrast to the yellow
of the refinement flags.
- liveplot(hst)
-
Sets the default histogram used for liveplot
- liveplot(legend)
-
Sets the default value for display of the legend in liveplot
- expgui(initstring)
-
Defines commands to be executed by EXPGUI after all other commands
have been run. This is used to define initialization commands in
the localconfig or .gsas_config files that cannot be
run at the time when the files are sourced. (added in EXPGUI v1.21)
The following variables are written to .gsas_config when
"Save Options" is used. These variables are all set from the GUI and therefore
do not need to be edited manually.
- expgui(archive)
-
This defines the default state for the archive flag,
where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
is saved before a new version of the file is saved and before EXPEDT is run.
- expgui(font)
-
This determines the base font used in the programs. You conceivably
could want to use an integer value not present in the
"Options/Screen Font" menu command.
- expgui(asorttype)
-
This determines the atom sort mode.
- expgui(hsorttype)
-
This determines the histogram sort mode.
- expgui(filesort)
-
This determines the default file sorting mode for the expnam command.
- expgui(autoexpload)
-
If set to 1, the experiment file is automatically reread after
GSAS programs modify it.
(UNIX only)
- expgui(showexptool)
-
If set to 1, output from EXPTOOL is shown after the program is run.
This is probably needed only for debugging purposes.
- env(GSASBACKSPACE)
-
Used only for UNIX: This determines if the default definition
for the backspace key is overridden; some UNIX systems need this so that
expedt and other terminal-oriented programs work correctly and
other systems do not. You can toggle this option using the
"Override Backspace" option on the file menu to see what works for you.
Currently two formats are supported, the Crystallographic Information File (CIF)
and .CEL files from PowderCell.
It is possible to define new formats for EXPGUI to use for importing
phase/coordinate information. This is done by creating a file named
import_xxxx.tcl (where xxxx is arbitrary)
in the EXPGUI directory. See the file import_cell.tcl as an example.
The file must contain four items:
-
A description for the type of file to be read.
set description "PowderCell .CEL file"
The text should not be too long, but use a return (\n) if needed:
set description "My favorite coordinate\nfile from the GIGO pkg"
This description text shows up on the button for selecting a format.
-
A list of preferred file extensions.
set extensions .cel
or
set extensions {.jnk .junk}
In UNIX upper and lower case
versions will be generated automatically, so do not worry about
the case of the extension. Note that "*" (all files) is always added as well.
-
The name of the routine that will read the data file
set procname ReadPowderCellFile
-
A routine that takes the file name as an argument
proc ReadPowderCellFile {filename} {
and returns a list containing the following four items
- Space Group
The space group should be named and spaced appropriately for GSAS,
e.g. P 21/c or P 21 21 21, not P21/c or P212121.
Note that GSAS requires that if a center of symmetry is present,
this center defines the origin (Origin 2 settings, where more than one setting
is given in the International Tables).
- Cell parameters
All six parameters should be specified in a list
- Atom Coordinates
The atom coordinates should be specified as a list with a list element
for each atom.
The list contains the following items:
- Atom label
- x
- y
- z
- Atom type
- Occupancy
- Uiso
If an item is not specified, it is left blank in the atom table, except for
Occupancy and Uiso, which default to 1.0 and 0.025, respectively.
However, one must specify a null value, if an item will be skipped over.
For example, use:
"Li1 0 0 0 li 0.5"
or
"{} 0 0 0 li 0.5"
but not
"0 0 0 li 0.5"
- Warning Message (optional)
The warning message is displayed at the bottom of the
Replace Atoms and Add Atoms box after the file is read. This can be used
to warn the user about problems reading the file, for example if
the space group symbol needs attention.
LSTVIEW
The localconfig and .gsas_config files are read, if present.
The following options are available for customization in these files:
- txtvw(menulength)
-
This limits the number of entries that can
exist in a menu. For example, the default is 25, so when more than 25 cycles
are found in a .LST file, only the last 25 are listed in the
"Go To"/cycle submenu.
- txtvw(maxchars)
-
This limits the maximum number of
characters that will be read from an existing .LST file to speed
the start of the program. The default is ~1Mb
for UNIX systems and ~200K for Windows.
The following variables are written to .gsas_config when
"Save Options" is used. These variables can be set from the GUI and therefore
do not need to be edited manually.
- txtvw(followcycle)
-
This sets the initial value for the
"Auto Advance" button in the "Go To" menu. When this is true,
the program will show the last cycle in the file. As new cycles are
added, the "view" is advanced.
- txtvw(font)
-
This sets the font used for LSTVIEW. See documentation on the font command in
Tk for details on font naming.
One additional variable is present that I don't suggest using at present:
- plotvars: I am in the process of developing code that tracks
and plots shifts and R values as a function cycle number. Setting plotvars to 1
allows this code to be tested.
LIVEPLOT
A description of the customization options for LIVEPLOT can be
found in the
LIVEPLOT description.
WIDPLT
The widplt script is used to display the FWHM for one or more histograms
from a .EXP file.
At this point it only works for CW data.
It is often convenient to add for reference the expected
instrumental curves as options to the menu. This can be done by creating a
file called widplot_name. For example, renaming the
example_widplt_BT1 file supplied with the distribution to
widplt_BT1 will cause the FWHM curves for the NIST BT-1 instrument
to be added to the menu of defined FWHM values.
Creating such a file is easy. To add a entry define the following
five array elements using a single, unique element name and then append that
element name to variable datalist.
Define
set UVWP(Ge15) {398.5 -343.2 163.0 0}
set XY(Ge15) {0 0}
set wave(Ge15) 2.0775
set lblarr(Ge15) "BT-1 Ge(311) 15'"
set ttrange(Ge15) "5 160"
lappend datalist Ge15
Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
while XY(item) contains the (Lorentzian) LX and LY terms. Array element
wave(item) contains a wavelength, array element lblarr(item) contains
the text to be shown on the "Plot Contents" menu and ttrange(item)
defines the range the function is valid.
The following variables are written to .gsas_config when
"Save Options" is used. These variables are all set from the GUI and therefore
do not need to be edited manually.
- graph(printout)
-
This is set to 1 if PostScript files
will be printed and 0 if they will be written to disk (for Windows all
files should be written to disk).
- graph(outname)
-
This is the default for the file name used
when PostScript files will be written to disk.
- graph(outcmd)
-
This is the default for the command used
to print PostScript files (Unix only).
- graph(legend)
-
Sets the default value for display of the legend in liveplot and widplt.
- graph(plotunits)
-
Sets the units used for displaying the data. Values are "d", "q", "",
for d-space, Q and 2-theta, respectively.
- graph(equivwave)
-
Sets the wavelength used for displaying data, if blank, no conversion is
done and data are shown in their original wavelength.
Customizing Example 1: Adding a new button to the button bar
When a LeBail extraction is used to refine lattice constants, profile
terms, ... It is always a good idea to run GENLES a few times after running
POWPREF. This is because GENLES sets the extracted intensities back to their
crystallographic values, during the first GENLES cycle after POWPREF has been
run. Refining anything until the extracted intensities return to reasonable
values is a really bad idea. Forturnately, running GENLES with the number of
cycles set to zero gives the Le Bail extraction a head start.
The code below can be used to define a new command, leBail. The first
command adds a command to the button bar and the second one defines what will
be done when it is invoked (the number of cycles is set to zero and
GENLES is run three times). It also defines the help entry. Note that commands must start with a lower case letter even though Armel LeBail's last name
does not.
lappend expgui(buttonlist) leBail
set expgui_cmdlist(leBail) {
{set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
{Converges GENLES with LeBail extractions;
Sets the number of cycles to zero and runs GENLES 3 times.}
}
To make this customization, put the above in the localconfig
file or the
~/.gsas_config or (or C:\GSAS\EXPGUI\.gsas_config)
file.
Customizing Example 2: Putting DISAGL Results in a Separate Box
Barbara Reisner has been asking me to put the output from DISAGL in a separate
window. Sounds like a pretty reasonable request. Here is an example with code
to do that as a customization option. Please note that this has now been
incorporated into EXPGUI, so do not use this example.
set expgui(disaglSeparateBox) 1
set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
proc rundisagl {} {
global expgui txtvw tcl_version tcl_platform
if {$expgui(disaglSeparateBox) && $tcl_platform(platform) != "windows"} {
set root [file root $expgui(expfile)]
catch {file rename $root.LST $root.OLS}
runGSASwEXP disagl
catch {file rename $root.LST $root.DIS}
catch {file rename $root.OLS $root.LST}
# open a new window
catch {toplevel .disagl}
catch {eval grid forget [grid slaves .disagl]}
text .disagl.txt -width 100 -wrap none \
-yscrollcommand ".disagl.yscroll set" \
-xscrollcommand ".disagl.xscroll set"
if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
scrollbar .disagl.yscroll -command ".disagl.txt yview"
scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
grid .disagl.xscroll -column 0 -row 2 -sticky ew
grid .disagl.txt -column 0 -row 1 -sticky nsew
grid .disagl.yscroll -column 1 -row 1 -sticky ns
grid columnconfigure .disagl 0 -weight 1
grid rowconfigure .disagl 1 -weight 1
wm title .disagl "DISAGL results $expgui(expfile)"
wm iconname .disagl "DISAGL $root"
set in [open $root.DIS r]
.disagl.txt insert end [read $in]
close $in
bind all {destroy .disagl}
bind .disagl ".disagl.txt yview scroll -1 page"
bind .disagl ".disagl.txt yview scroll 1 page"
bind .disagl ".disagl.txt xview scroll 1 unit"
bind .disagl ".disagl.txt xview scroll -1 unit"
bind .disagl ".disagl.txt yview scroll -1 unit"
bind .disagl ".disagl.txt yview scroll 1 unit"
bind .disagl ".disagl.txt yview 0"
bind .disagl ".disagl.txt yview end"
# don't disable in Win as this prevents the highlighting of selected text
if {$tcl_platform(platform) != "windows"} {
.disagl.txt config -state disabled
}
} else {
runGSASwEXP disagl
}
}
if {$tcl_platform(platform) != "windows"} {
append expgui(initstring) {
$expgui(fm).option.menu add checkbutton -label "DISAGL window" \
-variable expgui(disaglSeparateBox) -underline 0;
}
}
To make this customization, put the above in the localconfig
file or the
~/.gsas_config or (or C:\GSAS\EXPGUI\.gsas_config)
file.
Note that the expgui(initstring) option became available in EXPGUI
version 1.21. (Previous versions will ignore this). This code must be executed
after all the menus and other GUI code has been run. When executed, it
creates a checkbutton on the Options menu to
turn the "separate DISAGL window mode" mode on and off.
Customizing Example 3: Adding a new page to EXPGUI
The steps for creating support for additional functionality, implementation
of atom constraints, is outlined here. Routines described here can be found in
file atomcons.tcl unless otherwise noted.
- Create a routine to read and write the appropriate records
from the .EXP file. In this case, a new routine, constrinfo,
was added to file readexp.tcl.
This takes considerable care and manual testing.
- Create a routine that places the appropriate widgets into a frame
(in this case MakeAtomsConstraintsPane). This routine will be called only once.
Note that in this example expcons(atommaster) is defined to be the name of the
frame.
- Create a routine to display and edit the information shown in the
frame. In this case, DisplayAtomConstraints. This routine will be called each
time the page is displayed. Note that this routine and the previous can be
tested in a separate toplevel until they work well.
- In this particular example, the previous frame is located on a notebook
widget that in turn placed on a notebook page, so MakeConstraintsPane is used
to create this inner notebook when the "Constraints" notebook page is first
shown. This in turn calls MakeAtomsConstraintsPane and DisplayAtomConstraints.
To update this page each time it is displayed, DisplayConstraintsPane is
called.
- Edit file expgui to make the following changes:
- load the atomcons.tcl file:
# commands for constraints
source [file join $expgui(scriptdir) atomcons.tcl]
- Define a notebook page for the option. The -createcmd option
is used only once, but the -raisecmd option is used every time
the page is exposed.
set expgui(consFrame) [\
.n insert end consPane -text Constraints \
-raisecmd "set expgui(pagenow) consFrame; DisplayConstraintsPane"\
-createcmd MakeConstraintsPane]
lappend expgui(frameactionlist) "consFrame DisplayConstraintsPane"
Note that if we were displaying the atoms constraint page directly on
the main notebook widget, the previous command would have been
-raisecmd DisplayAtomConstraints -createcmd MakeAtomsConstraintsPane
Since the frame will need to be updated when information in the .EXP file
changes, the name of the frame and a command to execute are added into list
expgui(frameactionlist) using the lappend expgui(frameactionlist)
command.
Customizing Example 4: Changing the fonts used in the GUI
Question:
I am not happy with the fonts available via the Option/Screen Font
menu option. Is there a way to select different font size(s)/families?
option add *Coord.Listbox.Font "Courier -18 bold italic" 20
you will override the menu command and force the atom coordinates
to be displayed at 18 points in a bold & italicied Courier font.
(See the Tk documentation if this is not clear). The value 20 is a
priority, which overrides the priority value of 10 in the
standard initialization. Here are the options that can be specified:
- *Graph*Font
- Used for Graph labels
- *Graph.font
- Used for Graph title
- *Canvas.font
- Used for notebook tabs
- *Button.font
- Used on most buttons
- *Menu.font
- Used on menu commands
- *Menubutton.font
- Used on "menu buttons" (e.g. Print options)
- *Label.font
- Used on labels
- *Scale.font
- Used on sliders (e.g. Marquardt damping)
- *TitleFrame.font
- Used on title frames (e.g. box labels such as
the "Diffractometer Constants" label
- *SmallFont.Button.font
- Used for buttons with smaller letters
- *Coord.Listbox.font
- Used for coordinate listings, best as a
mono-spaced font, such as Courier
- *HistList.Listbox.font
- Used for histogram listings
- *MonoSpc.Label.font
- Used in other places where a mono-spaced
font is required
It should be noted that the appearance of fonts depends on many factors --
the fonts installed on your computer, the screen size and resolution and your
eyes, so it is wise to experiment with different values.
GSAS
is written by Allen C. Larson and
Robert B. Von Dreele, MS-H805,
Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
or kudos concerning GSAS should be sent to Robert B. Von Dreele at vondreele@lanl.gov
This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
Brian.Toby@NIST.GOV.
GSAS is Copyright, 1984-1997, The Regents of the University of California.
The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
by the Los Alamos National Laboratory, which is operated by the University
of California for the U.S. Department of Energy. The U.S. Government is
licensed to use, reproduce, and distribute this software. Permission is
granted to the public to copy and use this software without charge, provided
that this notice and any statement of authorship are reproduced on all
copies. Neither the Government nor the University makes any warranty, express
or implied, or assumes any liability or responsibility for the use of this
software.
The GUI is not subject to copyright. Have fun.
Brian Toby (Brian.Toby@NIST.GOV)
$Revision: 423 $ $Date: 2009-12-04 23:05:55 +0000 (Fri, 04 Dec 2009) $