source: trunk/doc/expgui_cfg.html @ 258

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

# on 2000/05/18 15:32:42, toby did:
add Tcl/tk logo, general editing
new example section

  • Property rcs:author set to toby
  • Property rcs:date set to 2000/05/18 15:32:42
  • Property rcs:lines set to +23 -14
  • Property rcs:rev set to 1.9
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 23.3 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">
25Customizing EXPGUI and Associated Programs</H1></CENTER>
27The EXPGUI GSAS graphical user interface can be modified in many
28ways quite easily.
29This document describes how the GUI works and how to modify the menus without
[144]30significant reprogramming. A little bit of programming in Tcl/Tk can go a
[114]31long way in adding new features. See the
32<a HREF="#Customizing">Customizing</A> examples, below.
[36]35The main GUI is created by file expgui, which in turn uses the following files
42Two additional files are read if they are found:
47<P>The first three files,
48(<TT>readexp.tcl</TT>, <TT>gsascmds.tcl</TT>, <TT>gsasmenu.tcl</TT>)
49must be located in the same directory where the <TT>expgui</TT> file is found.
50The <TT>localconfig</TT> file also is read from this directory, if it exists.
51The final file, <TT>.gsas_config</TT>, is read from the user's login directory (UNIX) or <TT>C:\</TT> (Windows).
[41]52The <TT>localconfig</TT> and <TT>.gsas_config</TT> are intended to
53contain system-wide and user-level default values for parameters
54that are described in this document. Most routines have
55a "Save Options" command that writes some of the current parameters to
56file  <TT>.gsas_config</TT>. Note that information in <TT>.gsas_config</TT>
57overrides that in <TT>localconfig</TT>.
58No error occurs if either of these files are not found.
61The <TT>readexp.tcl</TT> and <TT>gsascmds.tcl</TT> files contain
62tcl procedures that are
63used for more than one application, so it is convenient to place them
64in separate files. They are only of interest to someone trying to debug
65or add new functionality to expgui.
67The <TT>gsasmenu.tcl</TT> file defines the contents of the
68menu bar, the contents of the
69button bar and definitions for each command. The contents of this file
70are designed to be modified and extended by users, either by editing the file,
[144]71or by overriding definitions in the <TT>localconfig</TT> or
[36]72<TT>.gsas_config</TT> files.
[41]74The important variables defined in the <TT>gsasmenu.tcl</TT> file are:
77This list defines the menu bar headings other than File, Options & Help
79Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
80defines commands to be added to a menu heading. Each command will appear
81as an array element in expgui_cmdlist.
83Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
84contains two items. The first defines a tcl procedure to be executed
85when the command is invoked, or "-" if no command will be invoked and
86the second contains help information describing what the command does.
87Note that when menu item is selected the variable cmd is set to the
88name of the command, so
90    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
92means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
93. For example, when powpref is selected, the tcl command
94"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
96This list defines the commands that will appear on the button bar where
97each item that appears on the button bar must have a matching pair of entries
98in expgui_cmdlist.
99Thus if the command
101   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
103is placed in the <TT>localconfig</TT> or <TT>.gsas_config</TT> files this will
104redefine the contents of the button bar.
107In addition to the variables defined in the previous file, expgui, uses
[143]108a small number of array elements for other configuration options. They are:
112This determines where files such as <TT>readexp.tcl</TT>, etc.
113are located. This defaults to the location where <TT>expgui</TT> is located so
114it rarely needs to be changed.
117This contains the location of the GSAS directory, if it is not the
118parent director where expgui is found.
119This determines where a number of GSAS data files will be located. If expedt
120crashes when you try to add new atoms, this is probably wrong.
[36]123This determines where the GSAS executable files are located.
124You might want to change this is you keep multiple versions of GSAS
125around or if you keep the GSAS files in a different location than
126the default or want to keep the tcl files somewhere other than
127in a subdirectory of the GSAS files.
130Sets the font used for the coordinates scroll box
133Sets the font used for the histogram scroll box
136Sets the default histogram used for liveplot
139Sets the default value for display of the legend in liveplot
142Defines commands to be executed by EXPGUI after all other commands
143have been run. This is used to define initialization commands in
144the <TT>localconfig</TT> or <TT>.gsas_config</TT> files that cannot be
145run at the time when the files are sourced. <I>(added in EXPGUI v1.21)</I>
148The following variables are written to <tt>.gsas_config</tt> when
149"Save Options" is used. These variables are all set from the GUI and therefore
150do not need to be edited manually.
154This defines the default state for the archive flag,
155where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
156is saved before a new version of the file is saved and before EXPEDT is run.
159This determines the atom sort mode.
162This determines the histogram sort mode.
[81]165This determines the default file sorting mode for the expnam command.
168Used only for UNIX: This determines if the default definition
[36]169for the backspace key is overridden; some UNIX systems need this so that
170expedt and other terminal-oriented programs work correctly and
[143]171other systems do not. You can toggle this option using the
172"Override Backspace" option on the file menu to see what works for you.
177The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
178The following options are available for customization in these files:
181This limits the number of entries that can
[36]182exist in a menu. For example, the default is 25, so when more than 25 cycles
183are found in a .LST file, only the last 25 are listed in the
184"Go To"/cycle submenu.
186This limits the maximum number of
[36]187characters that will be read from an existing .LST file to speed
[41]188the start of the program. The default is ~1Mb
[36]189for UNIX systems and ~200K for Windows.
[81]192The following variables are written to <tt>.gsas_config</tt> when
193"Save Options" is used. These variables can be set from the GUI and therefore
194do not need to be edited manually.
198This sets the initial value for the
199"Auto Advance" button in the "Go To" menu. When this is true,
200the program will show the last cycle in the file. As new cycles are
201added, the "view" is advanced.
204This sets the font used for LSTVIEW. See documentation on the font command in
205Tk for details on font naming.
208One additional variable is present that I don't suggest using at present:
[41]210<LI>plotvars: I am in the process of developing code that tracks
[36]211and plots shifts and R values as a function cycle number. Setting plotvars to 1
212allows this code to be tested.
215<hr><H3>LIVEPLOT</H3><A NAME="liveplot"></A>
216The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
[81]217Note that some of these options are relevant only if the tcldump program is
220The following options are available for customization in these files:
223These variables define if peak positions will be shown
224for reflections in phase "<i>n</i>". Reflections will be shown if
225the value is non-zero.
228These variables define the default colors for
229reflections in phase "<i>n</i>"
232These variables define if peaks will be dashed for
233reflections in phase "<i>n</i>" (UNIX only). Lines will be dashed if
234the value is non-zero.
236<DT>peakinfo(min<i>n</i>) and peakinfo(max<i>n</i>)<DD>
[144]237These variables dictate the placement vertical position for reflection
[81]238markers, when manually placed (see expgui(autotick), below). To draw
239to the edge of the screen, use -Inf and Inf.
242The following variables are written to <tt>.gsas_config</tt> when
243"Save Options" is used. These variables are all set from the GUI and therefore
244do not need to be edited manually.
248This is set to 1 if PostScript files
249will be printed and 0 if they will be written to disk (for Windows all
250files should be written to disk).
253This is the default for the file name used
[36]254when PostScript files will be written to disk.
257This is the default for the command used
258to print PostScript files (Unix only).
261Sets the default value for display of the legend in liveplot and widplt.
264Symbol for observed data points. Valid choices are square, circle, diamond,
265plus, cross, splus and scross.
268Size for the symbol for observed data points. A value of 1 corresponds to about 1/8 inch
269(about 3 mm).
272When hkl values are loaded (using tcldump) and reflections are labeled, reflections
273can be labeled using a Shift-Left-Mouse click. All labeled reflections within expgui(pixelregion)
274pixels of the mouse position are assumed to be overlapped and are labeled.
277The time in seconds before reflection labels are removed. A value of zero means that reflections
278must be deleted manually (Shift-Right-Mouse).
281A size for reflections labels in pixels.
284If this variable is non-zero, reflection indices are shown in a box.
287If this variable is non-zero, reflection markers positions are
288set automatically.
[81]292<B>Using TCLDUMP with LIVEPLOT.</B>
293LIVEPLOT works with the standard GSAS program HSTDMP, but it works faster and is more
294powerful when used with the TCLDUMP program. Instructions for downloading this file can
295be found in the installation notes for
[105]296<A HREF="expgui_Win_readme.html">
[81]297Windows</A> and
[105]298<A HREF="expgui_Unix_readme.html">
[143]299UNIX</A>. Note that as of the April 2000 releases, GSAS is now distributed
300with TCLDUMP.
302<B>Combining CMPR and LIVEPLOT.</B>
[105]303If you have <A HREF="">CMPR</A>
[41]304installed on your computer, you can use superimpose on the GSAS results
305the peaks for an arbitrary unit cell. If desired, space group extinctions
306can even be shown.
307This is pretty neat! To enable this feature, you must have a version
[42]308of CMPR downloaded after 4 May 1998
[105]309<A HREF="">
[36]310(see the CMPR installation instructions.)</A>
[41]311For UNIX, create a link from in the expgui
[36]312directory to file cellgen.tcl in the CMPR directory. For example:
[41]314         ln -s /usr/local/cmpr/cellgen.tcl /usr/local/gsas/expgui/cellgen.tcl
[41]316For Windows, copy all the CMPR .tcl and .exe files into the expgui directory.
[81]318<B>Combining LOGIC and LIVEPLOT</B>
[105]319If you have <A HREF="">LOGIC</A>
[41]320installed on your computer, you can superimpose peaks
[36]321for a entry from the ICDD/JCPDS database on a pattern in LIVEPLOT.
322This is also pretty neat!
[41]323To enable this feature, you must have
[36]324a version of LOGIC downloaded after 4 May 1998
[105]325<A HREF="">
[36]326(see the LOGIC installation instructions.)</A>
[41]327For UNIX, create a link from in the GSAS GUI
[36]328directory to file icddcmd.tcl in the LOGIC directory. For example:
330         ln -s /usr/local/powdersuite/icddcmd.tcl /usr/local/gsas/tcl/icddcmd.tcl
[41]332For Windows, copy all the LOGIC files into the expgui directory.
[36]335The widplt script is used to display the FWHM for one or more histograms
[41]336from a .EXP file.
337At this point it only works for CW data.
338It is often convenient to add for reference the expected
[36]339instrumental curves as options to the menu. This can be done by creating a
340file called widplot_<i>name</i>. For example, renaming the
341<tt>example_widplt_BT1</tt> file supplied with the distribution to
342<tt>widplt_BT1</tt> will cause the FWHM curves for the NIST BT-1 instrument
343to be added to the menu of defined FWHM values.
345Creating such a file is easy. To add a entry define the following
346five array elements using a single, unique element name and then append that
347element name to variable datalist.
350    set UVWP(Ge15) {398.5 -343.2  163.0 0}
351    set XY(Ge15) {0 0}
352    set wave(Ge15) 2.0775
353    set lblarr(Ge15) "BT-1 Ge(311) 15'"
354    set ttrange(Ge15) "5 160"
355    lappend datalist Ge15
357Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
[41]358while XY(item) contains the (Lorentzian) LX and LY terms. Array element
[36]359wave(item) contains a wavelength, array element lblarr(item) contains
360the text to be shown on the "Plot Contents" menu and ttrange(item)
361defines the range the function is valid.
[41]363The following variables are written to <tt>.gsas_config</tt> when
364"Save Options" is used. These variables are all set from the GUI and therefore
365do not need to be edited manually.
369This is set to 1 if PostScript files
370will be printed and 0 if they will be written to disk (for Windows all
371files should be written to disk).
374This is the default for the file name used
375when PostScript files will be written to disk.
378This is the default for the command used
379to print PostScript files (Unix only).
382Sets the default value for display of the legend in liveplot and widplt.
385Sets the units used for displaying the data. Values are "d", "q", "",
386for d-space, Q and 2-theta, respectively.
388Sets the wavelength used for displaying data, if blank, no conversion is
389done and data are shown in their original wavelength.
[114]393<a name="Customizing"><H2>
394Customizing Example 1: Adding a new button to the button bar
396When a LeBail extraction is used to refine lattice constants, profile
397terms, ... It is always a good idea to run GENLES a few times after running
398POWPREF. This is because GENLES sets the extracted intensities back to their
399crystallographic values, during the first GENLES cycle after POWPREF has been
400run. Refining anything until the extracted intensities return to reasonable
401values is a really bad idea. Forturnately, running GENLES with the number of
402cycles set to zero gives the Le Bail extraction a head start.
404The code below can be used to define a new command, <tt>leBail</tt>. The first
405command adds a command to the button bar and the second one defines what will
406be done when it is invoked (the number of cycles is set to zero and
407GENLES 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
408does not.
411    lappend expgui(buttonlist) leBail
412    set expgui_cmdlist(leBail) {
413        {set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
414        {Converges GENLES with LeBail extractions;
415          Sets the number of cycles to zero and runs GENLES 3 times.}
416    }
419To make this customization, put the above in the <TT>localconfig</TT> 
420file or the
421<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]425Customizing Example 2: Putting DISAGL Results in a Separate Box
427Barbara Reisner has been asking me to put the output from DISAGL in a separate
[143]428window. Sounds like a pretty reasonable request. Here is an example with code
429to do that as a customization option. Please note that this has now been
430incorporated into EXPGUI, so do not use this example.
432  set expgui(disaglSeparateBox) 1
433  set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
434  proc rundisagl {} {
435    global expgui txtvw tcl_version tcl_platform
[143]436    if {$expgui(disaglSeparateBox) && $tcl_platform(platform) != "windows"} {
[114]437        set root [file root $expgui(expfile)]
438        catch {file rename $root.LST $root.OLS}
439        runGSASwEXP disagl
440        catch {file rename $root.LST $root.DIS}
441        catch {file rename $root.OLS $root.LST}
443        # open a new window
444        catch {toplevel .disagl}
445        catch {eval grid forget [grid slaves .disagl]}
446        text .disagl.txt -width 100 -wrap none \
447                -yscrollcommand ".disagl.yscroll set" \
448                -xscrollcommand ".disagl.xscroll set"
449        if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
450        scrollbar .disagl.yscroll -command ".disagl.txt yview"
451        scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
452        grid .disagl.xscroll -column 0 -row 2 -sticky ew
453        grid .disagl.txt -column 0 -row 1 -sticky nsew
454        grid .disagl.yscroll -column 1 -row 1 -sticky ns
455        grid columnconfigure .disagl 0 -weight 1
456        grid rowconfigure .disagl 1 -weight 1
457        wm title .disagl "DISAGL results $expgui(expfile)"
458        wm iconname .disagl "DISAGL $root"
459        set in [open $root.DIS r]
460        .disagl.txt insert end [read $in]
461        close $in
462        bind all <Control-KeyPress-c> {destroy .disagl}
463        bind .disagl <KeyPress-Prior> ".disagl.txt yview scroll -1 page"
464        bind .disagl <KeyPress-Next> ".disagl.txt yview scroll 1 page"
465        bind .disagl <KeyPress-Right> ".disagl.txt xview scroll 1 unit"
466        bind .disagl <KeyPress-Left> ".disagl.txt xview scroll -1 unit"
467        bind .disagl <KeyPress-Up> ".disagl.txt yview scroll -1 unit"
468        bind .disagl <KeyPress-Down> ".disagl.txt yview scroll 1 unit"
469        bind .disagl <KeyPress-Home> ".disagl.txt yview 0"
470        bind .disagl <KeyPress-End> ".disagl.txt yview end"
471        # don't disable in Win as this prevents the highlighting of selected text
472        if {$tcl_platform(platform) != "windows"} {
473            .disagl.txt config -state disabled
474        }
475    } else {
476        runGSASwEXP disagl
477    }
478  }
[143]480if {$tcl_platform(platform) != "windows"} {
481  append expgui(initstring) {
482      $expgui(fm) add checkbutton  -label "DISAGL window" \
483              -variable expgui(disaglSeparateBox) -underline 0;
484  }
488To make this customization, put the above in the <TT>localconfig</TT> 
489file or the
490<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
[143]493Note that the <tt>expgui(initstring)</tt> option became available in EXPGUI
494version 1.21. (Previous versions will ignore this). This code must be executed
495after all the menus and other GUI code has been run. When executed, it
496creates a checkbutton on the Options menu to
497turn the "separate DISAGL window mode" mode on and off.
500Customizing Example 3: Adding a new page to EXPGUI
502The steps for creating support for additional functionality, implementation
503of atom constraints, is outlined here. Routines described here can be found in
504file <tt>atomcons.tcl</tt> unless otherwise noted.
506<LI>Create a routine to read and write the appropriate records
507from the .EXP file. In this case, a new routine, constrinfo,
508was added to file <tt>readexp.tcl</tt>.
509This takes considerable care and manual testing.
510<LI>Create a routine that places the appropriate widgets into a frame
511(in this case MakeAtomsConstraintsPane). This routine will be called only once.
512Note that in this example expcons(atommaster) is defined to be the name of the
514<LI>Create a routine to display and edit the information shown in the
515frame. In this case, DisplayAtomConstraints. This routine will be called each
516time the page is displayed. Note that this routine and the previous can be
517tested in a separate toplevel until they work well.
518<LI>In this particular example, the previous frame is located on a notebook
519widget that in turn placed on a notebook page, so MakeConstraintsPane is used
520to create this inner notebook when the "Constraints" notebook page is first
521shown. This in turn calls MakeAtomsConstraintsPane and DisplayAtomConstraints.
[144]522To update this page each time it is displayed, DisplayConstraintsPane is
[143]524<LI>Edit file <tt>expgui</tt> to make the following changes:
526<P><LI>load the <tt>atomcons.tcl</tt> file:
[144]528# commands for constraints
[143]529source [file join $expgui(scriptdir) atomcons.tcl]
[143]531<P><LI>Define a notebook page for the option. The -createcmd option
532is used only once, but the -raisecmd option is used every time
533the page is exposed.
535set expgui(consFrame) [\
536            .n insert end consPane -text Constraints \
[144]537            -raisecmd "set expgui(pagenow) consFrame; DisplayConstraintsPane"\
[143]538            -createcmd MakeConstraintsPane]
[144]539lappend expgui(frameactionlist) "consFrame DisplayConstraintsPane"
541Note that if we were displaying the atoms constraint page directly on
542the main notebook widget, the previous command would have been
543<tt>-raisecmd DisplayAtomConstraints -createcmd MakeAtomsConstraintsPane</tt>
[144]545Since the frame will need to be updated when information in the .EXP file
546changes, the name of the frame and a command to execute are added into list
547expgui(frameactionlist) using the <TT>lappend expgui(frameactionlist)</TT>
[144]553<A Href="">
555is written by Allen C. Larson and <A HREF="">
[67]556Robert B. Von Dreele</A>, MS-H805,
[36]557Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
558or kudos concerning GSAS should be sent to Robert B. Von Dreele at <A HREF=""></A>
[67]560<P>This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
[36]561<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A>.
563<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
564The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
565by the Los Alamos National Laboratory, which is operated by the University
566of California for the U.S. Department of Energy. The U.S. Government is
567licensed to use, reproduce, and distribute this software. Permission is
568granted to the public to copy and use this software without charge, provided
569that this notice and any statement of authorship are reproduced on all
570copies. Neither the Government nor the University makes any warranty, express
571or implied, or assumes any liability or responsibility for the use of this
574<P>The GUI is not subject to copyright. Have fun.
576<P>Brian Toby (<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV)</A>
578$Revision: 144 $ $Date: 2009-12-04 23:01:08 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.