source: trunk/doc/expgui_cfg.html @ 410

Last change on this file since 410 was 410, checked in by toby, 12 years ago

# on 2001/08/24 18:56:53, toby did:

  • Property rcs:author set to toby
  • Property rcs:date set to 2001/08/24 18:56:53
  • Property rcs:lines set to +5 -124
  • Property rcs:rev set to 1.18
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 24.8 KB
[143]2   <META NAME="Author" CONTENT="Brian H. Toby">
3   <TITLE>Customizing EXPGUI and Associated Programs</TITLE>
[143]8<A HREF=>
9<IMG SRC="" 
10alt="Link to NIST Center for Neutron Research home page"
12<A HREF=>
13<IMG SRC="" 
14alt="Link to National Institute of Standards & Technology home page"
[144]17<A Href="">
18<IMG SRC="tcltklogo100.gif" 
19alt="Link to Tcl/Tk information">
[338]21<br clear=all><hr>
24<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
29Customizing EXPGUI and Associated Programs</H1></CENTER>
31The EXPGUI GSAS graphical user interface can be modified in many
32ways quite easily.
33This document describes how the GUI works and how to modify the menus without
[144]34significant reprogramming. A little bit of programming in Tcl/Tk can go a
[114]35long way in adding new features. See the
36<a HREF="#Customizing">Customizing</A> examples, below.
[36]39The main GUI is created by file expgui, which in turn uses the following files
46Two additional files are read if they are found:
51<P>The first three files,
52(<TT>readexp.tcl</TT>, <TT>gsascmds.tcl</TT>, <TT>gsasmenu.tcl</TT>)
53must be located in the same directory where the <TT>expgui</TT> file is found.
54The <TT>localconfig</TT> file also is read from this directory, if it exists.
55The final file, <TT>.gsas_config</TT>, is read from the user's login directory (UNIX) or <TT>C:\</TT> (Windows).
[41]56The <TT>localconfig</TT> and <TT>.gsas_config</TT> are intended to
57contain system-wide and user-level default values for parameters
58that are described in this document. Most routines have
59a "Save Options" command that writes some of the current parameters to
60file  <TT>.gsas_config</TT>. Note that information in <TT>.gsas_config</TT>
61overrides that in <TT>localconfig</TT>.
62No error occurs if either of these files are not found.
65The <TT>readexp.tcl</TT> and <TT>gsascmds.tcl</TT> files contain
66tcl procedures that are
67used for more than one application, so it is convenient to place them
68in separate files. They are only of interest to someone trying to debug
69or add new functionality to expgui.
71The <TT>gsasmenu.tcl</TT> file defines the contents of the
72menu bar, the contents of the
73button bar and definitions for each command. The contents of this file
74are designed to be modified and extended by users, either by editing the file,
[144]75or by overriding definitions in the <TT>localconfig</TT> or
[36]76<TT>.gsas_config</TT> files.
[41]78The important variables defined in the <TT>gsasmenu.tcl</TT> file are:
[36]81This list defines the menu bar headings other than File, Options & Help
[36]83Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
84defines commands to be added to a menu heading. Each command will appear
85as an array element in expgui_cmdlist.
[36]87Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
88contains two items. The first defines a tcl procedure to be executed
89when the command is invoked, or "-" if no command will be invoked and
90the second contains help information describing what the command does.
91Note that when menu item is selected the variable cmd is set to the
92name of the command, so
94    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
96means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
97. For example, when powpref is selected, the tcl command
98"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
[36]100This list defines the commands that will appear on the button bar where
101each item that appears on the button bar must have a matching pair of entries
102in expgui_cmdlist.
103Thus if the command
105   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
107is placed in the <TT>localconfig</TT> or <TT>.gsas_config</TT> files this will
108redefine the contents of the button bar.
111In addition to the variables defined in the previous file, expgui, uses
[143]112a small number of array elements for other configuration options. They are:
[41]116This determines where files such as <TT>readexp.tcl</TT>, etc.
117are located. This defaults to the location where <TT>expgui</TT> is located so
118it rarely needs to be changed.
[41]121This contains the location of the GSAS directory, if it is not the
122parent director where expgui is found.
123This determines where a number of GSAS data files will be located. If expedt
124crashes when you try to add new atoms, this is probably wrong.
[36]127This determines where the GSAS executable files are located.
128You might want to change this is you keep multiple versions of GSAS
129around or if you keep the GSAS files in a different location than
130the default or want to keep the tcl files somewhere other than
131in a subdirectory of the GSAS files.
[41]134Sets the font used for the coordinates scroll box
[41]137Sets the font used for the histogram scroll box
140Sets the background color for the bottom box on the phase pane.
141The default value, #fdf, is a light violet that
142will probably drive some folks nuts, but is a good contrast to the yellow
143of the refinement flags.
[41]146Sets the default histogram used for liveplot
[41]149Sets the default value for display of the legend in liveplot
[143]152Defines commands to be executed by EXPGUI after all other commands
153have been run. This is used to define initialization commands in
154the <TT>localconfig</TT> or <TT>.gsas_config</TT> files that cannot be
155run at the time when the files are sourced. <I>(added in EXPGUI v1.21)</I>
158The following variables are written to <tt>.gsas_config</tt> when
159"Save Options" is used. These variables are all set from the GUI and therefore
160do not need to be edited manually.
[41]164This defines the default state for the archive flag,
165where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
166is saved before a new version of the file is saved and before EXPEDT is run.
[41]169This determines the atom sort mode.
[41]172This determines the histogram sort mode.
[81]175This determines the default file sorting mode for the expnam command.
178If set to 1, the experiment file is automatically reread after
179GSAS programs modify it.
180(UNIX only)
183If set to 1, output from EXPTOOL is shown after the program is run.
184This is probably needed only for debugging purposes.
[41]187Used only for UNIX: This determines if the default definition
[36]188for the backspace key is overridden; some UNIX systems need this so that
189expedt and other terminal-oriented programs work correctly and
[143]190other systems do not. You can toggle this option using the
191"Override Backspace" option on the file menu to see what works for you.
196<HR><H3><A NAME="import">Coordinate import routines for EXPGUI</A>
[299]197<IMG SRC="new.gif" HEIGHT=13 WIDTH=36 alt="New!">
[282]199Currently two formats are supported, the Crystallographic Information File (CIF)
200and .CEL files from PowderCell.
[270]201It is possible to define new formats for EXPGUI to use for importing
202phase/coordinate information. This is done by creating a file named
[282]203<TT>import_</TT><I>xxxx</I><TT>.tcl</TT> (where <I>xxxx</I> is arbitrary)
204in the EXPGUI directory. See the file <TT>import_cell.tcl</TT> as an example.
206The file must contain four items:
209A description for the type of file to be read.
211set description "PowderCell .CEL file"
[282]213The text should not be too long, but use a return (\n) if needed:
215set description "My favorite coordinate\nfile from the GIGO pkg"
[282]217This description text shows up on the button for selecting a format.
[282]220A list of preferred file extensions.
222set extensions .cel
226set extensions {.jnk .junk}
[282]228In UNIX upper and lower case
229versions will be generated automatically, so do not worry about
230the case of the extension. Note that "*" (all files) is always added as well.
233The name of the routine that will read the data file
235set procname ReadPowderCellFile
238A routine that takes the file name as an argument
240proc ReadPowderCellFile {filename} {
[282]242and returns a list containing the following four items
[282]244<P><LI>Space Group
246The space group should be named and spaced appropriately for GSAS,
247e.g. P 21/c or P 21 21 21, not P21/c or P212121.
[282]249Note that GSAS requires that if a center of symmetry is present,
250this center defines the origin (Origin 2 settings, where more than one setting
251is given in the International Tables).
252<P><LI>Cell parameters
254All six parameters should be specified in a list
[282]256<P><LI>Atom Coordinates
258The atom coordinates should be specified as a list with a list element
259for each atom.
260The list contains the following items:
262<LI>Atom label
266<LI>Atom type
270If an item is not specified, it is left blank in the atom table, except for
271Occupancy and U<sub>iso</sub>, which default to 1.0 and 0.025, respectively.
272However, one must specify a null value, if an item will be skipped over.
273For example, use:
275    "Li1 0 0 0 li 0.5"
279    "{} 0 0 0 li 0.5"
281but not
283    "0 0 0 li 0.5"
[282]287<P><LI>Warning Message (optional)
289The warning message is displayed at the bottom of the
290Replace Atoms and Add Atoms box after the file is read. This can be used
291to warn the user about problems reading the file, for example if
292the space group symbol needs attention.
298The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
299The following options are available for customization in these files:
[41]302This limits the number of entries that can
[36]303exist in a menu. For example, the default is 25, so when more than 25 cycles
304are found in a .LST file, only the last 25 are listed in the
305"Go To"/cycle submenu.
[41]307This limits the maximum number of
[36]308characters that will be read from an existing .LST file to speed
[41]309the start of the program. The default is ~1Mb
[36]310for UNIX systems and ~200K for Windows.
[81]313The following variables are written to <tt>.gsas_config</tt> when
314"Save Options" is used. These variables can be set from the GUI and therefore
315do not need to be edited manually.
[41]319This sets the initial value for the
320"Auto Advance" button in the "Go To" menu. When this is true,
321the program will show the last cycle in the file. As new cycles are
322added, the "view" is advanced.
[81]325This sets the font used for LSTVIEW. See documentation on the font command in
326Tk for details on font naming.
329One additional variable is present that I don't suggest using at present:
[41]331<LI>plotvars: I am in the process of developing code that tracks
[36]332and plots shifts and R values as a function cycle number. Setting plotvars to 1
333allows this code to be tested.
336<hr><H3>LIVEPLOT</H3><A NAME="liveplot"></A>
[410]337A description of the customization options for LIVEPLOT can be
338found in the
339<A HREF="liveplot.html#customize">
340LIVEPLOT description</A>.
[36]345The widplt script is used to display the FWHM for one or more histograms
[41]346from a .EXP file.
347At this point it only works for CW data.
348It is often convenient to add for reference the expected
[36]349instrumental curves as options to the menu. This can be done by creating a
350file called widplot_<i>name</i>. For example, renaming the
351<tt>example_widplt_BT1</tt> file supplied with the distribution to
352<tt>widplt_BT1</tt> will cause the FWHM curves for the NIST BT-1 instrument
353to be added to the menu of defined FWHM values.
355Creating such a file is easy. To add a entry define the following
356five array elements using a single, unique element name and then append that
357element name to variable datalist.
360    set UVWP(Ge15) {398.5 -343.2  163.0 0}
361    set XY(Ge15) {0 0}
362    set wave(Ge15) 2.0775
363    set lblarr(Ge15) "BT-1 Ge(311) 15'"
364    set ttrange(Ge15) "5 160"
365    lappend datalist Ge15
367Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
[41]368while XY(item) contains the (Lorentzian) LX and LY terms. Array element
[36]369wave(item) contains a wavelength, array element lblarr(item) contains
370the text to be shown on the "Plot Contents" menu and ttrange(item)
371defines the range the function is valid.
[41]373The following variables are written to <tt>.gsas_config</tt> when
374"Save Options" is used. These variables are all set from the GUI and therefore
375do not need to be edited manually.
[41]379This is set to 1 if PostScript files
380will be printed and 0 if they will be written to disk (for Windows all
381files should be written to disk).
[41]384This is the default for the file name used
385when PostScript files will be written to disk.
[41]388This is the default for the command used
389to print PostScript files (Unix only).
[41]392Sets the default value for display of the legend in liveplot and widplt.
[41]395Sets the units used for displaying the data. Values are "d", "q", "",
396for d-space, Q and 2-theta, respectively.
[41]398Sets the wavelength used for displaying data, if blank, no conversion is
399done and data are shown in their original wavelength.
[114]403<a name="Customizing"><H2>
404Customizing Example 1: Adding a new button to the button bar
406When a LeBail extraction is used to refine lattice constants, profile
407terms, ... It is always a good idea to run GENLES a few times after running
408POWPREF. This is because GENLES sets the extracted intensities back to their
409crystallographic values, during the first GENLES cycle after POWPREF has been
410run. Refining anything until the extracted intensities return to reasonable
411values is a really bad idea. Forturnately, running GENLES with the number of
412cycles set to zero gives the Le Bail extraction a head start.
414The code below can be used to define a new command, <tt>leBail</tt>. The first
415command adds a command to the button bar and the second one defines what will
416be done when it is invoked (the number of cycles is set to zero and
417GENLES 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
418does not.
421    lappend expgui(buttonlist) leBail
422    set expgui_cmdlist(leBail) {
423        {set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
424        {Converges GENLES with LeBail extractions;
425          Sets the number of cycles to zero and runs GENLES 3 times.}
426    }
429To make this customization, put the above in the <TT>localconfig</TT> 
430file or the
431<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]435Customizing Example 2: Putting DISAGL Results in a Separate Box
437Barbara Reisner has been asking me to put the output from DISAGL in a separate
[143]438window. Sounds like a pretty reasonable request. Here is an example with code
439to do that as a customization option. Please note that this has now been
440incorporated into EXPGUI, so do not use this example.
442  set expgui(disaglSeparateBox) 1
443  set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
444  proc rundisagl {} {
445    global expgui txtvw tcl_version tcl_platform
[143]446    if {$expgui(disaglSeparateBox) && $tcl_platform(platform) != "windows"} {
[114]447        set root [file root $expgui(expfile)]
448        catch {file rename $root.LST $root.OLS}
449        runGSASwEXP disagl
450        catch {file rename $root.LST $root.DIS}
451        catch {file rename $root.OLS $root.LST}
453        # open a new window
454        catch {toplevel .disagl}
455        catch {eval grid forget [grid slaves .disagl]}
456        text .disagl.txt -width 100 -wrap none \
457                -yscrollcommand ".disagl.yscroll set" \
458                -xscrollcommand ".disagl.xscroll set"
459        if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
460        scrollbar .disagl.yscroll -command ".disagl.txt yview"
461        scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
462        grid .disagl.xscroll -column 0 -row 2 -sticky ew
463        grid .disagl.txt -column 0 -row 1 -sticky nsew
464        grid .disagl.yscroll -column 1 -row 1 -sticky ns
465        grid columnconfigure .disagl 0 -weight 1
466        grid rowconfigure .disagl 1 -weight 1
467        wm title .disagl "DISAGL results $expgui(expfile)"
468        wm iconname .disagl "DISAGL $root"
469        set in [open $root.DIS r]
470        .disagl.txt insert end [read $in]
471        close $in
472        bind all <Control-KeyPress-c> {destroy .disagl}
473        bind .disagl <KeyPress-Prior> ".disagl.txt yview scroll -1 page"
474        bind .disagl <KeyPress-Next> ".disagl.txt yview scroll 1 page"
475        bind .disagl <KeyPress-Right> ".disagl.txt xview scroll 1 unit"
476        bind .disagl <KeyPress-Left> ".disagl.txt xview scroll -1 unit"
477        bind .disagl <KeyPress-Up> ".disagl.txt yview scroll -1 unit"
478        bind .disagl <KeyPress-Down> ".disagl.txt yview scroll 1 unit"
479        bind .disagl <KeyPress-Home> ".disagl.txt yview 0"
480        bind .disagl <KeyPress-End> ".disagl.txt yview end"
481        # don't disable in Win as this prevents the highlighting of selected text
482        if {$tcl_platform(platform) != "windows"} {
483            .disagl.txt config -state disabled
484        }
485    } else {
486        runGSASwEXP disagl
487    }
488  }
[143]490if {$tcl_platform(platform) != "windows"} {
491  append expgui(initstring) {
492      $expgui(fm) add checkbutton  -label "DISAGL window" \
493              -variable expgui(disaglSeparateBox) -underline 0;
494  }
498To make this customization, put the above in the <TT>localconfig</TT> 
499file or the
500<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]503Note that the <tt>expgui(initstring)</tt> option became available in EXPGUI
504version 1.21. (Previous versions will ignore this). This code must be executed
505after all the menus and other GUI code has been run. When executed, it
506creates a checkbutton on the Options menu to
507turn the "separate DISAGL window mode" mode on and off.
510Customizing Example 3: Adding a new page to EXPGUI
512The steps for creating support for additional functionality, implementation
513of atom constraints, is outlined here. Routines described here can be found in
514file <tt>atomcons.tcl</tt> unless otherwise noted.
516<LI>Create a routine to read and write the appropriate records
517from the .EXP file. In this case, a new routine, constrinfo,
518was added to file <tt>readexp.tcl</tt>.
519This takes considerable care and manual testing.
520<LI>Create a routine that places the appropriate widgets into a frame
521(in this case MakeAtomsConstraintsPane). This routine will be called only once.
522Note that in this example expcons(atommaster) is defined to be the name of the
524<LI>Create a routine to display and edit the information shown in the
525frame. In this case, DisplayAtomConstraints. This routine will be called each
526time the page is displayed. Note that this routine and the previous can be
527tested in a separate toplevel until they work well.
528<LI>In this particular example, the previous frame is located on a notebook
529widget that in turn placed on a notebook page, so MakeConstraintsPane is used
530to create this inner notebook when the "Constraints" notebook page is first
531shown. This in turn calls MakeAtomsConstraintsPane and DisplayAtomConstraints.
[144]532To update this page each time it is displayed, DisplayConstraintsPane is
[143]534<LI>Edit file <tt>expgui</tt> to make the following changes:
536<P><LI>load the <tt>atomcons.tcl</tt> file:
[144]538# commands for constraints
[143]539source [file join $expgui(scriptdir) atomcons.tcl]
[143]541<P><LI>Define a notebook page for the option. The -createcmd option
542is used only once, but the -raisecmd option is used every time
543the page is exposed.
545set expgui(consFrame) [\
546            .n insert end consPane -text Constraints \
[144]547            -raisecmd "set expgui(pagenow) consFrame; DisplayConstraintsPane"\
[143]548            -createcmd MakeConstraintsPane]
[144]549lappend expgui(frameactionlist) "consFrame DisplayConstraintsPane"
551Note that if we were displaying the atoms constraint page directly on
552the main notebook widget, the previous command would have been
553<tt>-raisecmd DisplayAtomConstraints -createcmd MakeAtomsConstraintsPane</tt>
[144]555Since the frame will need to be updated when information in the .EXP file
556changes, the name of the frame and a command to execute are added into list
557expgui(frameactionlist) using the <TT>lappend expgui(frameactionlist)</TT>
564Customizing Example 4: Changing the fonts used in the GUI
566<B>Question: </B>
567<I>I use a 19" screen with a resolution 1280x1024. With this resolution, the
568fonts are really small in the GUI. Is a way exist to increase the font size?
571<B>Answer: </B>
572The fonts used in EXPGUI can be customized by adding some code to the
573<TT>localconfig</TT> file or the
574<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>) file.
575By default, fonts are 14 point for the menus, buttons, labels,... and
57612 point for the histogram and atom lists.
578This code changes those fonts to 18 and 16 point, respectively.
580option add *Font            -*-helvetica-medium-r-normal-*-18-*-*-*-*-*-*-*
581option add *font            -*-helvetica-medium-r-normal-*-18-*-*-*-*-*-*-*
582option add *Menu.font       -*-helvetica-bold-r-normal-*-18-*-*-*-*-*-*-*
583option add *Menubutton.font -*-helvetica-bold-r-normal-*-18-*-*-*-*-*-*-*
584option add *Label.font      -*-helvetica-bold-r-normal-*-18-*-*-*-*-*-*-*
585option add *Scale.font      -*-helvetica-bold-o-normal-*-18-*-*-*-*-*-*-*
586option add *TitleFrame.font -*-helvetica-bold-o-normal-*-18-*-*-*-*-*-*-*
587set expgui(coordfont) "-*-courier-bold-r-normal--16-*"
588set expgui(histfont) "-*-courier-bold-r-normal--16-*"
591A slightly different and perhaps cleaner approach is to specify the font
592sizes in pixels.
593The code below uses font sizes of 18 and 16 pixels, respectively.
595option add *Font            "Helvetica -18"
596option add *font            "Helvetica -18"
597option add *Menu.font       "Helvetica -18 bold"
598option add *Menubutton.font "Helvetica -18 bold"
599option add *Label.font      "Helvetica -18 bold"
600option add *Scale.font      "Helvetica -18 bold italic"
601option add *TitleFrame.font "Helvetica -18 bold italic"
602set expgui(coordfont) "Courier -16 bold"
603set expgui(histfont)  "Courier -16 bold"
605It should be noted that the appearance of fonts depends on many factors --
606the fonts installed on your computer, the screen size and resolution and your
607eyes, so it is wise to experiment with different values in the above
612<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
[144]615<A Href="">
617is written by Allen C. Larson and <A HREF="">
[67]618Robert B. Von Dreele</A>, MS-H805,
[36]619Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
620or kudos concerning GSAS should be sent to Robert B. Von Dreele at <A HREF=""></A>
[67]622<P>This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
[36]623<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A>.
625<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
626The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
627by the Los Alamos National Laboratory, which is operated by the University
628of California for the U.S. Department of Energy. The U.S. Government is
629licensed to use, reproduce, and distribute this software. Permission is
630granted to the public to copy and use this software without charge, provided
631that this notice and any statement of authorship are reproduced on all
632copies. Neither the Government nor the University makes any warranty, express
633or implied, or assumes any liability or responsibility for the use of this
636<P>The GUI is not subject to copyright. Have fun.
638<P>Brian Toby (<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV)</A>
640$Revision: 410 $ $Date: 2009-12-04 23:05:42 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.