source: trunk/doc/expgui_cfg.html @ 114

Last change on this file since 114 was 114, checked in by toby, 11 years ago

# on 1999/10/11 20:27:13, toby did:
Customization examples

  • Property rcs:author set to toby
  • Property rcs:date set to 1999/10/11 20:27:13
  • Property rcs:lines set to +107 -3
  • Property rcs:rev set to 1.7
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 19.5 KB
Line 
1<HTML>
2<TITLE>
3Customizing EXPGUI and Associated Programs
4</TITLE>
5<HEAD>
6</HEAD>
7<BODY>
8
9<CENTER>
10<H2>
11Customizing EXPGUI and Associated Programs</H2></CENTER>
12
13The EXPGUI GSAS graphical user interface can be modified in many
14ways quite easily.
15This document describes how the GUI works and how to modify the menus without
16significant reprogramming. A little bit of programmaning in Tcl/Tk can go a
17long way in adding new features. See the
18<a HREF="#Customizing">Customizing</A> examples, below.
19
20<H3>EXPGUI</H3>
21The main GUI is created by file expgui, which in turn uses the following files
22sequentially:
23<UL>
24<LI><TT>readexp.tcl</TT>
25<LI><TT>gsascmds.tcl</TT>
26<LI><TT>gsasmenu.tcl</TT>
27</UL>
28Two additional files are read if they are found:
29<UL>
30<LI><TT>localconfig</TT>
31<LI><TT>.gsas_config</TT>
32</UL>
33<P>The first three files,
34(<TT>readexp.tcl</TT>, <TT>gsascmds.tcl</TT>, <TT>gsasmenu.tcl</TT>)
35must be located in the same directory where the <TT>expgui</TT> file is found.
36The <TT>localconfig</TT> file also is read from this directory, if it exists.
37The final file, <TT>.gsas_config</TT>, is read from the user's login directory (UNIX) or <TT>C:\</TT> (Windows).
38The <TT>localconfig</TT> and <TT>.gsas_config</TT> are intended to
39contain system-wide and user-level default values for parameters
40that are described in this document. Most routines have
41a "Save Options" command that writes some of the current parameters to
42file  <TT>.gsas_config</TT>. Note that information in <TT>.gsas_config</TT>
43overrides that in <TT>localconfig</TT>.
44No error occurs if either of these files are not found.
45
46<P>
47The <TT>readexp.tcl</TT> and <TT>gsascmds.tcl</TT> files contain
48tcl procedures that are
49used for more than one application, so it is convenient to place them
50in separate files. They are only of interest to someone trying to debug
51or add new functionality to expgui.
52<P>
53The <TT>gsasmenu.tcl</TT> file defines the contents of the
54menu bar, the contents of the
55button bar and definitions for each command. The contents of this file
56are designed to be modified and extended by users, either by editing the file,
57or by overridding definitions in the <TT>localconfig</TT> or
58<TT>.gsas_config</TT> files.
59
60The important variables defined in the <TT>gsasmenu.tcl</TT> file are:
61<DL><DL>
62<DT>expgui(menunames)<DD>
63This list defines the menu bar headings other than File, Options & Help
64<DT>expgui_menulist<DD>
65Each array element, e.g. expgui_menulist(file) and expgui_menulist(powder),
66defines commands to be added to a menu heading. Each command will appear
67as an array element in expgui_cmdlist.
68<DT>expgui_cmdlist<DD>
69Each array element, e.g. expgui_cmdlist(Save) or expgui_cmdlist(expnam)
70contains two items. The first defines a tcl procedure to be executed
71when the command is invoked, or "-" if no command will be invoked and
72the second contains help information describing what the command does.
73Note that when menu item is selected the variable cmd is set to the
74name of the command, so
75<PRE>
76    expgui_cmdlist(powpref) {{runGSASwEXP $cmd} {Powder data preparation}}
77</PRE>
78means that "runGSASwEXP powpref" will be invoked when powpref is invoked.
79. For example, when powpref is selected, the tcl command
80"runGSASwEXP $cmd" is invoked, where variable cmd is set to "powpref".
81<DT>expgui(buttonlist)<DD>
82This list defines the commands that will appear on the button bar where
83each item that appears on the button bar must have a matching pair of entries
84in expgui_cmdlist.
85Thus if the command
86<PRE>
87   set expgui(buttonlist) {expnam expedt genles ortep fourier forsrh forplot lstview}
88</PRE>
89is placed in the <TT>localconfig</TT> or <TT>.gsas_config</TT> files this will
90redefine the contents of the button bar.
91</DL></DL>
92
93In addition to the variables defined in the previous file, expgui, uses
94a small number of array for other configuration options. They are:
95<DL><DL>
96
97<DT>expgui(scriptdir)<DD>
98This determines where files such as <TT>readexp.tcl</TT>, etc.
99are located. This defaults to the location where <TT>expgui</TT> is located so
100it rarely needs to be changed.
101
102<DT>expgui(gsasdir)<DD>
103This contains the location of the GSAS directory, if it is not the
104parent director where expgui is found.
105This determines where a number of GSAS data files will be located. If expedt
106crashes when you try to add new atoms, this is probably wrong.
107
108<DT>expgui(gsasexe)<DD>
109This determines where the GSAS executable files are located.
110You might want to change this is you keep multiple versions of GSAS
111around or if you keep the GSAS files in a different location than
112the default or want to keep the tcl files somewhere other than
113in a subdirectory of the GSAS files.
114
115<DT>expgui(coordfont)<DD>
116Sets the font used for the coordinates scroll box
117
118<DT>expgui(histfont)<DD>
119Sets the font used for the histogram scroll box
120
121<DT>liveplot(hst)<DD>
122Sets the default histogram used for liveplot
123
124<DT>liveplot(legend)<DD>
125Sets the default value for display of the legend in liveplot
126
127</DL></DL>
128
129The following variables are written to <tt>.gsas_config</tt> when
130"Save Options" is used. These variables are all set from the GUI and therefore
131do not need to be edited manually.
132
133<DL><DL>
134<DT>expgui(archive)<DD>
135This defines the default state for the archive flag,
136where 0 is off and 1 is on. When archive is on, a copy of the .EXP file
137is saved before a new version of the file is saved and before EXPEDT is run.
138
139<DT>expgui(asorttype)<DD>
140This determines the atom sort mode.
141
142<DT>expgui(hsorttype)<DD>
143This determines the histogram sort mode.
144
145<DT>expgui(filesort)<DD>
146This determines the default file sorting mode for the expnam command.
147
148<DT>env(GSASBACKSPACE)<DD>
149Used only for UNIX: This determines if the default definition
150for the backspace key is overridden; some UNIX systems need this so that
151expedt and other terminal-oriented programs work correctly and
152other systems do not. You can toggle this option using the "sets an environment variable needed by the "Override Backspace" option on the file menu.
153
154</DL></DL>
155
156<HR><H3>LSTVIEW</H3>
157The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
158The following options are available for customization in these files:
159<DL><DL>
160<DT>txtvw(menulength)<DD>
161This limits the number of entries that can
162exist in a menu. For example, the default is 25, so when more than 25 cycles
163are found in a .LST file, only the last 25 are listed in the
164"Go To"/cycle submenu.
165<DT>txtvw(maxchars)<DD>
166This limits the maximum number of
167characters that will be read from an existing .LST file to speed
168the start of the program. The default is ~1Mb
169for UNIX systems and ~200K for Windows.
170</DL></DL>
171
172The following variables are written to <tt>.gsas_config</tt> when
173"Save Options" is used. These variables can be set from the GUI and therefore
174do not need to be edited manually.
175
176<DL><DL>
177<DT>txtvw(followcycle)<DD>
178This sets the initial value for the
179"Auto Advance" button in the "Go To" menu. When this is true,
180the program will show the last cycle in the file. As new cycles are
181added, the "view" is advanced.
182
183<DT>txtvw(font)<DD>
184This sets the font used for LSTVIEW. See documentation on the font command in
185Tk for details on font naming.
186</DL></DL>
187
188One additional variable is present that I don't suggest using at present:
189<UL>
190<LI>plotvars: I am in the process of developing code that tracks
191and plots shifts and R values as a function cycle number. Setting plotvars to 1
192allows this code to be tested.
193</LI></UL>
194
195<hr><H3>LIVEPLOT</H3><A NAME="liveplot"></A>
196The <TT>localconfig</TT> and <TT>.gsas_config</TT> files are read, if present.
197Note that some of these options are relevant only if the tcldump program is
198present.
199<P>
200The following options are available for customization in these files:
201<DL><DL>
202<DT>peakinfo(flag<i>n</i>)<DD>
203These variables define if peak positions will be shown
204for reflections in phase "<i>n</i>". Reflections will be shown if
205the value is non-zero.
206
207<DT>peakinfo(color<i>n</i>)<DD>
208These variables define the default colors for
209reflections in phase "<i>n</i>"
210
211<DT>peakinfo(dashes<i>n</i>)<DD>
212These variables define if peaks will be dashed for
213reflections in phase "<i>n</i>" (UNIX only). Lines will be dashed if
214the value is non-zero.
215
216<DT>peakinfo(min<i>n</i>) and peakinfo(max<i>n</i>)<DD>
217These variables dictact the placement vertical position for reflection
218markers, when manually placed (see expgui(autotick), below). To draw
219to the edge of the screen, use -Inf and Inf.
220</DL></DL>
221
222The following variables are written to <tt>.gsas_config</tt> when
223"Save Options" is used. These variables are all set from the GUI and therefore
224do not need to be edited manually.
225
226<DL><DL>
227<DT>graph(printout)<DD>
228This is set to 1 if PostScript files
229will be printed and 0 if they will be written to disk (for Windows all
230files should be written to disk).
231
232<DT>graph(outname)<DD>
233This is the default for the file name used
234when PostScript files will be written to disk.
235
236<DT>graph(outcmd)<DD>
237This is the default for the command used
238to print PostScript files (Unix only).
239
240<DT>graph(legend)<DD>
241Sets the default value for display of the legend in liveplot and widplt.
242
243<DT>peakinfo(obssym)<DD>
244Symbol for observed data points. Valid choices are square, circle, diamond,
245plus, cross, splus and scross.
246
247<DT>peakinfo(obssize)<DD>
248Size for the symbol for observed data points. A value of 1 corresponds to about 1/8 inch
249(about 3 mm).
250
251<DT>expgui(pixelregion)<DD>
252When hkl values are loaded (using tcldump) and reflections are labeled, reflections
253can be labeled using a Shift-Left-Mouse click. All labeled reflections within expgui(pixelregion)
254pixels of the mouse position are assumed to be overlapped and are labeled.
255
256<DT>expgui(fadetime)<DD>
257The time in seconds before reflection labels are removed. A value of zero means that reflections
258must be deleted manually (Shift-Right-Mouse).
259
260<DT>expgui(lblfontsize)<DD>
261A size for reflections labels in pixels.
262
263<DT>expgui(hklbox)<DD>
264If this variable is non-zero, reflection indices are shown in a box.
265
266<DT>expgui(autotick)<DD>
267If this variable is non-zero, reflection markers positions are
268set automatically.
269</DL></DL>
270
271<P>
272<B>Using TCLDUMP with LIVEPLOT.</B>
273LIVEPLOT works with the standard GSAS program HSTDMP, but it works faster and is more
274powerful when used with the TCLDUMP program. Instructions for downloading this file can
275be found in the installation notes for
276<A HREF="expgui_Win_readme.html">
277Windows</A> and
278<A HREF="expgui_Unix_readme.html">
279UNIX</A>.
280<P>
281<B>Combining CMPR and LIVEPLOT.</B>
282If you have <A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/cmpr.html">CMPR</A>
283installed on your computer, you can use superimpose on the GSAS results
284the peaks for an arbitrary unit cell. If desired, space group extinctions
285can even be shown.
286This is pretty neat! To enable this feature, you must have a version
287of CMPR downloaded after 4 May 1998
288<A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/cmpr.html">
289(see the CMPR installation instructions.)</A>
290For UNIX, create a link from in the expgui
291directory to file cellgen.tcl in the CMPR directory. For example:
292<PRE>
293         ln -s /usr/local/cmpr/cellgen.tcl /usr/local/gsas/expgui/cellgen.tcl
294</PRE>
295For Windows, copy all the CMPR .tcl and .exe files into the expgui directory.
296<P>
297<B>Combining LOGIC and LIVEPLOT</B>
298If you have <A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/logic.html">LOGIC</A>
299installed on your computer, you can superimpose peaks
300for a entry from the ICDD/JCPDS database on a pattern in LIVEPLOT.
301This is also pretty neat!
302To enable this feature, you must have
303a version of LOGIC downloaded after 4 May 1998
304<A HREF="http://www.ncnr.nist.gov/programs/crystallography/software/logic.html">
305(see the LOGIC installation instructions.)</A>
306For UNIX, create a link from in the GSAS GUI
307directory to file icddcmd.tcl in the LOGIC directory. For example:
308<PRE>
309         ln -s /usr/local/powdersuite/icddcmd.tcl /usr/local/gsas/tcl/icddcmd.tcl
310</PRE>
311For Windows, copy all the LOGIC files into the expgui directory.
312<HR>
313<H3>WIDPLT</H3>
314The widplt script is used to display the FWHM for one or more histograms
315from a .EXP file.
316At this point it only works for CW data.
317It is often convenient to add for reference the expected
318instrumental curves as options to the menu. This can be done by creating a
319file called widplot_<i>name</i>. For example, renaming the
320<tt>example_widplt_BT1</tt> file supplied with the distribution to
321<tt>widplt_BT1</tt> will cause the FWHM curves for the NIST BT-1 instrument
322to be added to the menu of defined FWHM values.
323<P>
324Creating such a file is easy. To add a entry define the following
325five array elements using a single, unique element name and then append that
326element name to variable datalist.
327Define
328<PRE>
329    set UVWP(Ge15) {398.5 -343.2  163.0 0}
330    set XY(Ge15) {0 0}
331    set wave(Ge15) 2.0775
332    set lblarr(Ge15) "BT-1 Ge(311) 15'"
333    set ttrange(Ge15) "5 160"
334    lappend datalist Ge15
335</PRE>
336Array element UVWP(item) contains the (Gaussian) GU, GV, GW and GP values,
337while XY(item) contains the (Lorentzian) LX and LY terms. Array element
338wave(item) contains a wavelength, array element lblarr(item) contains
339the text to be shown on the "Plot Contents" menu and ttrange(item)
340defines the range the function is valid.
341<P>
342The following variables are written to <tt>.gsas_config</tt> when
343"Save Options" is used. These variables are all set from the GUI and therefore
344do not need to be edited manually.
345
346<DL><DL>
347<DT>graph(printout)<DD>
348This is set to 1 if PostScript files
349will be printed and 0 if they will be written to disk (for Windows all
350files should be written to disk).
351
352<DT>graph(outname)<DD>
353This is the default for the file name used
354when PostScript files will be written to disk.
355
356<DT>graph(outcmd)<DD>
357This is the default for the command used
358to print PostScript files (Unix only).
359
360<DT>graph(legend)<DD>
361Sets the default value for display of the legend in liveplot and widplt.
362
363<DT>graph(plotunits)<DD>
364Sets the units used for displaying the data. Values are "d", "q", "",
365for d-space, Q and 2-theta, respectively.
366<DT>graph(equivwave)<DD>
367Sets the wavelength used for displaying data, if blank, no conversion is
368done and data are shown in their original wavelength.
369</DL></DL>
370
371<hr>
372<a name="Customizing"><H2>
373Customizing Example 1: Adding a new button to the button bar
374</H2></A>
375When a LeBail extraction is used to refine lattice constants, profile
376terms, ... It is always a good idea to run GENLES a few times after running
377POWPREF. This is because GENLES sets the extracted intensities back to their
378crystallographic values, during the first GENLES cycle after POWPREF has been
379run. Refining anything until the extracted intensities return to reasonable
380values is a really bad idea. Forturnately, running GENLES with the number of
381cycles set to zero gives the Le Bail extraction a head start.
382<P>
383The code below can be used to define a new command, <tt>leBail</tt>. The first
384command adds a command to the button bar and the second one defines what will
385be done when it is invoked (the number of cycles is set to zero and
386GENLES 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
387does not.
388
389<PRE>
390    lappend expgui(buttonlist) leBail
391    set expgui_cmdlist(leBail) {
392        {set entryvar(cycles) 0; runGSASwEXP "genles genles genles"}
393        {Converges GENLES with LeBail extractions;
394          Sets the number of cycles to zero and runs GENLES 3 times.}
395    }
396
397</PRE>
398To make this customization, put the above in the <TT>localconfig</TT> 
399file or the
400<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
401file.
402<hr>
403<H2>
404Customizing Example 2: Adding a new button to the button bar
405</H2>
406Barbara Reisner has been asking me to put the output from DISAGL in a separate
407window. Sounds like a pretty reasonable request. Here is the code to do that.
408
409<PRE>
410  set expgui(disaglSeparateBox) 1
411  set expgui_cmdlist(disagl) {rundisagl {Hacked Distance/angle calculations}}
412  proc rundisagl {} {
413    global expgui txtvw tcl_version tcl_platform
414    if {$expgui(disaglSeparateBox)} {
415        set root [file root $expgui(expfile)]
416        catch {file rename $root.LST $root.OLS}
417        runGSASwEXP disagl
418        catch {file rename $root.LST $root.DIS}
419        catch {file rename $root.OLS $root.LST}
420
421        # open a new window
422        catch {toplevel .disagl}
423        catch {eval grid forget [grid slaves .disagl]}
424        text .disagl.txt -width 100 -wrap none \
425                -yscrollcommand ".disagl.yscroll set" \
426                -xscrollcommand ".disagl.xscroll set"
427        if {$tcl_version >= 8.0} {.disagl.txt config -font $txtvw(font)}
428        scrollbar .disagl.yscroll -command ".disagl.txt yview"
429        scrollbar .disagl.xscroll -command ".disagl.txt xview" -orient horizontal
430        grid .disagl.xscroll -column 0 -row 2 -sticky ew
431        grid .disagl.txt -column 0 -row 1 -sticky nsew
432        grid .disagl.yscroll -column 1 -row 1 -sticky ns
433        grid columnconfigure .disagl 0 -weight 1
434        grid rowconfigure .disagl 1 -weight 1
435        wm title .disagl "DISAGL results $expgui(expfile)"
436        wm iconname .disagl "DISAGL $root"
437        set in [open $root.DIS r]
438        .disagl.txt insert end [read $in]
439        close $in
440        bind all <Control-KeyPress-c> {destroy .disagl}
441        bind .disagl <KeyPress-Prior> ".disagl.txt yview scroll -1 page"
442        bind .disagl <KeyPress-Next> ".disagl.txt yview scroll 1 page"
443        bind .disagl <KeyPress-Right> ".disagl.txt xview scroll 1 unit"
444        bind .disagl <KeyPress-Left> ".disagl.txt xview scroll -1 unit"
445        bind .disagl <KeyPress-Up> ".disagl.txt yview scroll -1 unit"
446        bind .disagl <KeyPress-Down> ".disagl.txt yview scroll 1 unit"
447        bind .disagl <KeyPress-Home> ".disagl.txt yview 0"
448        bind .disagl <KeyPress-End> ".disagl.txt yview end"
449        # don't disable in Win as this prevents the highlighting of selected text
450        if {$tcl_platform(platform) != "windows"} {
451            .disagl.txt config -state disabled
452        }
453    } else {
454        runGSASwEXP disagl
455    }
456  }
457
458</PRE>
459To make this customization, put the above in the <TT>localconfig</TT> 
460file or the
461<TT>~/.gsas_config</TT> or (or <TT>C:\GSAS\EXPGUI\.gsas_config</TT>)
462file.
463<P>
464Note that an even better customization might be to add these commands into
465the expgui file somewhere near the beginning and then near the end,
466add
467<PRE>
468   $expgui(fm).option.menu add checkbutton  -label "DISAGL window" \
469        -variable expgui(disaglSeparateBox) -underline 0
470</PRE>
471so that there is an option to turn the "separate DISAGL window mode"
472on and off.
473<hr>
474GSAS is written by Allen C. Larson and <A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://lansce.lanl.gov/lujan/staff12/vondreele.htm">
475Robert B. Von Dreele</A>, MS-H805,
476Los Alamos National Laboratory, Los Alamos, NM 87545. Problems, questions
477or kudos concerning GSAS should be sent to Robert B. Von Dreele at <A HREF="MAILTO:vondreele@lanl.gov">vondreele@lanl.gov</A>
478
479<P>This GUI is written by Brian H. Toby of the NIST Center for Neutron Research,
480<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV</A>.
481
482<P>GSAS is Copyright, 1984-1997, The Regents of the University of California.
483The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36)
484by the Los Alamos National Laboratory, which is operated by the University
485of California for the U.S. Department of Energy. The U.S. Government is
486licensed to use, reproduce, and distribute this software. Permission is
487granted to the public to copy and use this software without charge, provided
488that this notice and any statement of authorship are reproduced on all
489copies. Neither the Government nor the University makes any warranty, express
490or implied, or assumes any liability or responsibility for the use of this
491software.
492
493<P>The GUI is not subject to copyright. Have fun.
494
495<P>Brian Toby (<A HREF="MAILTO:Brian.Toby@NIST.GOV">Brian.Toby@NIST.GOV)</A>
496<BR>
497$Revision: 114 $ $Date: 2009-12-04 23:00:38 +0000 (Fri, 04 Dec 2009) $
498</BODY>
499</HTML>
Note: See TracBrowser for help on using the repository browser.