\(\renewcommand\AA{\text{Å}}\)

7. GSAS-II GUI Support Modules

The modules documented here provide GUI or graphics capabilities that are used in multiple sections of the GSAS-II GUI or graphics.

7.1. GSASIIctrlGUI: Custom GUI controls

A library of specialized widgets (GUI controls) for use in the GSAS-II data window or dialogs:

Class or function name	Description
EnumSelector	A combo box with a built-in call back routine that automatically sets a dict or list entry.
G2ChoiceButton	A customized wx.Choice that automatically initializes to the initial value and saves the choice directly into a dict or list value. Optionally calls function when a choice is selected
G2CheckBox	A customized wx.CheckBox that automatically initializes to the initial value and saves the choice directly into a dict or list value. Optionally calls function when a choice is selected
G2CheckBoxFrontLbl()	A version of G2CheckBox that places the label for the check box in front. Otherwise works the same.
G2RadioButtons()	Creates a series of grouped radio buttons.
G2SliderWidget	A customized combination of a wx.Slider and a validated wx.TextCtrl (see ValidatedTxtCtrl).
G2Slider	A wrapped version of wx.Slider that implements scaling
G2SpinWidget	A customized combination of a wx.SpinButton and a validated wx.TextCtrl (see ValidatedTxtCtrl).
G2MultiChoiceWindow	Similar to G2MultiChoiceDialog but provides a sizer that can be placed in a frame or panel.
HelpButton	Creates a button labeled with a “?” that when pressed displays help text in a modal message window or web browser.
OrderBox	Creates a wx.Panel with scrollbars where items can be ordered into columns.
SortableLstCtrl	Creates a wx.Panel for a table of data that can be sorted by clicking on a column label.
ValidatedTxtCtrl	A text control with a built-in call back routine to set dict or list elements. Optionally validates input as float, int or for strings non-blank. Value is set when focus changes
HorizontalLine()	Places a line in a Frame or Dialog to separate sections.
ScrolledStaticText	A wx.StaticText widget that fits a large string into a small space by scrolling it
ReadOnlyTextCtrl()	A wx.TextCtrl widget to be used wx.StaticText (no edits allowed) text appears in a box.
setColorButton()	A button for color selection as a replacement for wx.ColourSelect

GSAS-II-provided Dialog (full window) routines:

Class or function name	Description
G2MessageBox()	Displays text typically used for errors or warnings.
ShowScrolledInfo()	Dialog to display longer text where scrolling is possibly needed
gpxFileSelector	File browser dialog for opening existing .gpx files
GetImportFile()	Gets one or more files from the appropriate import directory, which can be overridden. Arguments follow those of wx.FileDialog()
G2FileBrowser()	An alternate file selection dialog to use in place of wx.FileDialog(). Offers a filter and breaks long lists into ranges.
askSaveFile()	Get a file name from user
askSaveDirectory()	Get a directory name from user
MultiColumnSelection	A dialog that builds a multicolumn table, word wrapping is used for the 2nd, 3rd,… columns.
MultiColMultiSelDlg()	Calls a dialog that allows multiple selection from a multicolumn table
MultiDataDialog	Dialog to obtain multiple data values from user, with optional range validation; items can be float, str or bool
MultiIntegerDialog	Dialog to obtain multiple integer values from user, with a description for each value and optional defaults.
MultiStringDialog	Dialog to obtain multiple string values from user, with a description for each value and optional
DisAglDialog	Distance/Angle Controls input dialog.
FlagSetDialog	Dialog that provides a table of items along with a checkbox for each. defaults.
G2ColumnIDDialog	A dialog for matching column data to desired items; some columns may be ignored.
G2HistoDataDialog	A dialog for global edits to histogram data globally
G2MultiChoiceDialog	Dialog similar to wx.MultiChoiceDialog, but provides a filter to select choices and buttons to make selection of multiple items more simple.
G2SingleChoiceDialog	Dialog similar to wx.SingleChoiceDialog, but provides a filter to help search through choices.
SGMagSpinBox	Special version of wx.MessageBox that displays magnetic spin text
SGMessageBox	Special version of wx.MessageBox that displays space group & super space group text in two blocks
SingleFloatDialog	Dialog to obtain a single float value from user, with optional range validation.
SingleIntDialog	Dialog to obtain a single integer value from user, with optional range validation.
SingleStringDialog	Dialog to obtain a single string value from user, with optional an optional default value.
GetItemOrder()	Dialog for ordering items into columns
ScrolledMultiEditor	Dialog for editing many dict- or list-contained items. with validation. Results are placed in dict or list.
CallScrolledMultiEditor()	Routine for editing many dict- or list-contained items. using the ScrolledMultiEditor dialog
G2ScrolledGrid()	Displays a multicolumn table of information with possible scroll bars
ShowScrolledColText()	Displays tabular text with scrolling where needed
ItemSelector()	Select a single item or multiple items from list of choices. Creates and then destroys a wx.Dialog and returns the selections(s).
SelectEdit1Var()	Select a variable from a list, then edit it and select histograms to copy it to.
BlockSelector()	Select a single block for instrument parameters
MultipleBlockSelector()	Select one or more blocks of data, used for CIF powder histogram imports only
MultipleChoicesSelector()	Dialog for displaying fairly complex choices, used for CIF powder histogram imports only
PhaseSelector()	Select a phase from a list (used for phase importers)

Miscellaneous GUI support routines:

Function name	Description
Define_wxId()	Create a unique wx.Id symbol in _initMenus in GSASII.GSASIIdataGUI. Such symbols are needed when the menu item is defined in a different location from the wx.Bind that links the menu item to a function. This function allows all the menu Ids to be defined as the menus are created in one place and then can be used in Bind elsewhere in the code.
openInNewTerm()	opens a Python routine (usually G2.py) in a new terminal window (works on all platforms)

Other miscellaneous non-GUI routines that may be of use for GUI-related actions:

Function name	Description
StripIndents()	Regularizes the intentation from a string with multiple newline characters by removing spaces at the beginning of each line.
StripUnicode()	Removes unicode characters from strings
GetImportPath()	Determines the default location to use for importing files. Tries sequentially G2frame.TutorialImportDir, config var Import_directory and G2frame.LastImportDir.
GetExportPath()	Determines the default location to use for writing files. Tries sequentially G2frame.LastExportDir and G2frame.LastGPXdir

7.1.1. GSASIIctrlGUI Classes & Routines

Documentation for all the routines in module GSASIIctrlGUI follows.

class GSASII.GSASIIctrlGUI.ASCIIValidator(result=None, key=None)

A validator to be used with a TextCtrl to prevent entering characters other than ASCII characters.

The value is checked for validity after every keystroke

If an invalid number is entered, the box is highlighted. If the number is valid, it is saved in result[key]

Parameters:

• result (dict/list) – List or dict where value should be placed when valid

• key (any) – key to use for result (int for list)

Clone()

Create a copy of the validator, a strange, but required component

OnChar(event)

Called each type a key is pressed ignores keys that are not allowed for int and float types

TestValid(tc)

Check if the value is valid by casting the input string into ASCII.

Save it in the dict/list where the initial value was stored

Parameters:

tc (wx.TextCtrl) – A reference to the TextCtrl that the validator is associated with.

TransferFromWindow()

Needed by validator, strange, but required component

TransferToWindow()

Needed by validator, strange, but required component

GSASII.GSASIIctrlGUI.BlockSelector(ChoiceList, ParentFrame=None, title='Select a block', size=None, header='Block Selector', useCancel=True)

Provide a wx dialog to select a single block where one must be selected. Used for selecting for banks for instrument parameters if the file contains more than one set.

GSASII.GSASIIctrlGUI.CallScrolledMultiEditor(parent, dictlst, elemlst, prelbl=[], postlbl=[], title='Edit items', header='', size=(300, 250), CopyButton=False, ASCIIonly=False, **kw)

Wrapper routine to call a ScrolledMultiEditor dialog. See ScrolledMultiEditor for parameter definitions.

Returns:

True if the OK button is pressed; False if the window is closed with the system menu or the Cancel button.

GSASII.GSASIIctrlGUI.Define_wxId(*args)

routine to create unique global wx Id symbols in this module.

class GSASII.GSASIIctrlGUI.DisAglDialog(parent, data, default, Reset=True, Angle=True)

Distance/Angle Controls input dialog. After ShowModal() returns, the results are found in dict self.data, which is accessed using GetData().

Parameters:

• parent (wx.Frame) – reference to parent frame (or None)

• data (dict) – a dict containing the current search ranges or an empty dict, which causes default values to be used. Will be used to set element DisAglCtls in Phase Tree Item

• default (dict) – A dict containing the default search ranges for each element.

• Reset (bool) – if True (default), show Reset button

• Angle (bool) – if True (default), show angle radii

Draw(data)

Creates the contents of the dialog. Normally called by __init__().

GetData()

Returns the values from the dialog

OnOk(event)

Called when the OK button is pressed

OnReset(event)

Called when the Reset button is pressed

class GSASII.GSASIIctrlGUI.EnumSelector(parent, dct, item, choices, values=None, OnChange=None, **kw)

A customized wxpython.ComboBox that selects items from a list of choices, but sets a dict (list) entry to the corresponding entry from the input list of values.

Parameters:

• parent (wx.Panel) – the parent to the ComboBox (usually a frame or panel)

• dct – a dict or list to contain the value set for the ComboBox.

• item – the dict key (or list index) where dct[item] will be set to the value selected in the ComboBox. Also, dct[item] contains the starting value shown in the widget. If the value does not match an entry in values, the first value in choices is used as the default, but dct[item] is not changed.

• choices (list) –

  a list of choices to be displayed to the user such as

  ["default","option 1","option 2",]
  

  Note that these options will correspond to the entries in values (if specified) item by item.

• values (list) –

  a list of values that correspond to the options in choices, such as

  [0,1,2]
  

  The default for values is to use the same list as specified for choices.

• OnChange (function) – an optional routine that will be called when the ComboBox can be specified.

• (other) – additional keyword arguments accepted by ComboBox can be specified.

GSASII.GSASIIctrlGUI.ExtractFileFromZip(filename, selection=None, confirmread=True, confirmoverwrite=True, parent=None, multipleselect=False, msg='')

If the filename is a zip file, extract a file from that archive.

Parameters:

• selection (list) – used to predefine the name of the file to be extracted. Filename case and zip directory name are ignored in selection; the first matching file is used.

• confirmread (bool) – if True asks the user to confirm before expanding the only file in a zip

• confirmoverwrite (bool) – if True asks the user to confirm before overwriting if the extracted file already exists

• multipleselect (bool) – if True allows more than one zip file to be extracted, a list of file(s) is returned. If only one file is present, do not ask which one, otherwise offer a list of choices (unless selection is used).

• msg (str) – a message explaining what is being read. Default is blank.

Returns:

the name of the file that has been created or a list of files (see multipleselect)

If the file is not a zipfile, return the name of the input file. If the zipfile is empty or no file has been selected, return None

class GSASII.GSASIIctrlGUI.FlagSetDialog(parent, title, colnames, rownames, flags)

Creates popup with table of variables to be checked for e.g. refinement flags

GSASII.GSASIIctrlGUI.G2AfterFit(parent, msg, title='Error', vartbl=[], txtwidth=300)

Shows the results from a refinement

Parameters:

• parent (wx.Frame) – pointer to parent of window, usually G2frame

• msg (str) – text from refinement results

• title (str) – text to label window

• vartbl (list) – a list of lists. The contents of each inner list item will be [var-name, val-before, val-after, sigma, meaning]

• txtwidth (int) – width (in pixesl) to display msg. Defaults to 300

class GSASII.GSASIIctrlGUI.G2Button(parent, id=-1, label='', locationcode='', handler=None, *args, **kwargs)

A version of wx.Button. Bindings are saved in the object, and are looked up rather than directly set with a bind.

Parameters:

• parent (wx.Panel) – parent widget

• id (int) – Id for button

• label (str) – label for button

• handler (function) – a routine to call when the button is pressed

onPress(event)

create log event and call handler

class GSASII.GSASIIctrlGUI.G2CheckBox(parent, label, loc, key, OnChange=None)

A customized version of a CheckBox that automatically initializes the control to a supplied list or dict entry and updates that entry as the widget is used.

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the widget. Can be None.

• label (str) – text to put on check button

• loc (dict/list) – the dict or list with the initial value to be placed in the CheckBox.

• key (int/str) – the dict key or the list index for the value to be edited by the CheckBox. The loc[key] element must exist. The CheckBox will be initialized from this value. If the value is anything other that True (or 1), it will be taken as False.

• OnChange (function) – specifies a function or method that will be called when the CheckBox is changed (Default is None). The called function is supplied with one argument, the calling event.

GSASII.GSASIIctrlGUI.G2CheckBoxFrontLbl(parent, label, loc, key, OnChange=None)

A customized version of a CheckBox that automatically initializes the control to a supplied list or dict entry and updates that entry as the widget is used. Same as G2CheckBox except the label is placed before the CheckBox and returns a sizer rather than the G2CheckBox.

If the CheckBox is needed, reference Sizer.myCheckBox.

class GSASII.GSASIIctrlGUI.G2ChoiceButton(parent, choiceList, indLoc=None, indKey=None, strLoc=None, strKey=None, onChoice=None, **kwargs)

A customized version of a wx.Choice that automatically initializes the control to match a supplied value and saves the choice directly into an array or list. Optionally a function can be called each time a choice is selected. The widget can be used with an array item that is set to to the choice by number (indLoc[indKey]) or by string value (strLoc[strKey]) or both. The initial value is taken from indLoc[indKey] if not None or strLoc[strKey] if not None.

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the widget. Can be None.

• choiceList (list) – a list or tuple of choices to offer the user.

• indLoc (dict/list) – a dict or list with the initial value to be placed in the Choice button. If this is None, this is ignored.

• indKey (int/str) – the dict key or the list index for the value to be edited by the Choice button. If indLoc is not None then this must be specified and the indLoc[indKey] will be set. If the value for indLoc[indKey] is not None, it should be an integer in range(len(choiceList)). The Choice button will be initialized to the choice corresponding to the value in this element if not None.

• strLoc (dict/list) – a dict or list with the string value corresponding to indLoc/indKey. Default (None) means that this is not used.

• strKey (int/str) – the dict key or the list index for the string value The strLoc[strKey] element must exist or strLoc must be None (default).

• onChoice (function) – name of a function to call when the choice is made.

Example 1:

data['Orientation'] = 1
choice = G2G.G2ChoiceButton(dlg,
                    ['Horizontal','Vertical'],
                    data,'Orientation',
                    onChoice=replot)

This will show “Vertical” as the initial value, and based on what is selected, data['Orientation'] will be set to 0 or 1 (as an int value).

Example 2:

data[0]['Font'] = '8'
choice = G2G.G2ChoiceButton(dlg,
                    ['6','8','10','12','14','16'],
                    None,None,
                    data[0],'Font',
                    onChoice=replot)

This will show “8” as the initial value, and based on what is selected, data[0]['Font'] will be set to a string with one of the size options (“6”… “16”).

setByString(string)

Find an entry matching string and select it

class GSASII.GSASIIctrlGUI.G2ColumnIDDialog(parent, title, header, Comments, ChoiceList, ColumnData, monoFont=False, **kw)

A dialog for matching column data to desired items; some columns may be ignored.

Parameters:

• ParentFrame (wx.Frame) – reference to parent frame

• title (str) – heading above list of choices

• header (str) – Title to place on window frame

• ChoiceList (list) – a list of possible choices for the columns

• ColumnData (list) – lists of column data to be matched with ChoiceList

• monoFont (bool) – If False (default), use a variable-spaced font; if True use a equally-spaced font.

• kw – optional keyword parameters for the wx.Dialog may be included such as size [which defaults to (320,310)] and style (which defaults to wx.DEFAULT_DIALOG_STYLE | wx.RESIZE_BORDER | wx.CENTRE | wx.OK | wx.CANCEL); note that wx.OK and wx.CANCEL controls the presence of the eponymous buttons in the dialog.

Returns:

the name of the created dialog

GetSelection()

Returns the selected sample parm for each column

GSASII.GSASIIctrlGUI.G2FileBrowser(parent, message, defaultDir, *args, style=1, wildcard='any file (*.*)|*.*', **kwargs)

Create a file browser for selecting one or more files from a directory. The user may select the directory where the files and must select an extension from a specified list. Optionally, a filter may be supplied to ignore files not matching a glob pattern. When a large number of files is found, the file list is broken into ranges.

Arguments used are the same as in wx.FileDialog(). Selection of multiple files is allowed if argument style includes wx.FD_MULTIPLE. Note that other positional or keyword parameters, other than those below are allowed, but are ignored.

Parameters:

• parent – parent window to dialog to be created

• message – message to place at top of dialog

• defaultDir – starting directory

• style – selection style. Bit settings other than wx.FD_MULTIPLE are ignored. When wx.FD_MULTIPLE is specified, multiple files can be selected.

• wildcard – defines the extensions allowed for selecting files. of form “type A (.A;.B;*.c)|*.A;*.B;*.c|any file (.)|*.*”. See wx.FileDialog() for more information on this.

Returns:

a list of selected files. Will contain only one file unless style=wx.FD_MULTIPLE has been used.

class GSASII.GSASIIctrlGUI.G2HistoDataDialog(parent, title, header, ParmList, ParmFmt, HistoList, ParmData, monoFont=False, **kw)

A dialog for editing histogram data globally.

Parameters:

• ParentFrame (wx.Frame) – reference to parent frame

• title (str) – heading above list of choices

• header (str) – Title to place on window frame

• ParmList (list) – a list of names for the columns

• ParmFmt (list) – a list of formatting strings for the columns

• list – HistoList: a list of histogram names

• ParmData (list) – a list of lists of data matched to ParmList; one for each item in HistoList

• monoFont (bool) – If False (default), use a variable-spaced font; if True use a equally-spaced font.

• kw – optional keyword parameters for the wx.Dialog may be included such as size [which defaults to (320,310)] and style (which defaults to wx.DEFAULT_DIALOG_STYLE | wx.RESIZE_BORDER | wx.CENTRE | wx.OK | wx.CANCEL); note that wx.OK and wx.CANCEL controls the presence of the eponymous buttons in the dialog.

Returns:

the modified ParmData

GetData()

Returns the modified ParmData

class GSASII.GSASIIctrlGUI.G2LstCtrl(parent, ID=-1, pos=wx.Point(-1, -1), size=wx.Size(-1, -1), style=0)

Creates a custom ListCtrl with support for images in column labels

GetColumnSorter()

Custom sorter that handles absolute numerical values for columns 1, 2, and 3 (2nd, 3rd, 4th columns)

GetSortImages()

Returns a tuple of image list indexesthe indexes in the image list for an image to be put on the column header when sorting in descending order.

GSASII.GSASIIctrlGUI.G2MessageBox(parent, msg, title='Error')

Simple code to display a error or warning message

TODO: replace wx.MessageDialog with one derived from wx.Dialog because on most platforms wx.MessageDialog is a native widget and CentreOnParent will not function.

class GSASII.GSASIIctrlGUI.G2MultiChoiceDialog(parent, title, header, ChoiceList, toggle=True, monoFont=False, filterBox=True, extraOpts={}, selected=[], **kw)

A dialog similar to wx.MultiChoiceDialog except that buttons are added to set all choices and to toggle all choices and a filter is available to select from available entries. Note that if multiple entries are placed in the filter box separated by spaces, all of the strings must be present for an item to be shown.

Parameters:

• ParentFrame (wx.Frame) – reference to parent frame

• title (str) – heading above list of choices

• header (str) – Title to place on window frame

• ChoiceList (list) – a list of choices where one more will be selected

• toggle (bool) – If True (default) the toggle and select all buttons are displayed

• monoFont (bool) – If False (default), use a variable-spaced font; if True use a equally-spaced font.

• filterBox (bool) – If True (default) an input widget is placed on the window and only entries matching the entered text are shown.

• extraOpts (dict) – a dict containing a entries of form label_i and value_i with extra options to present to the user, where value_i is the default value. Options are listed ordered by the value_i values.

• selected (list) – list of indicies for items that should be

• kw – optional keyword parameters for the wx.Dialog may be included such as size [which defaults to (320,310)] and style (which defaults to wx.DEFAULT_DIALOG_STYLE|wx.RESIZE_BORDER|wx.CENTRE| wx.OK | wx.CANCEL); note that wx.OK and wx.CANCEL style items control the presence of the eponymous buttons in the dialog.

Returns:

the name of the created dialog

Filter(event)

Read text from filter control and select entries that match. Called by Timer after a delay with no input or if Enter is pressed.

GetSelections()

Returns a list of the indices for the selected choices

OnCheck(event)

for CheckListBox events; if Set Range is in use, this sets/clears all entries in range between start and end according to the value in start. Repeated clicks on the start change the checkbox state, but do not trigger the range copy. The caption next to the button is updated on the first button press.

SetRange(event)

Respond to a press of the Set Range button. Set the range flag and the caption next to the button

SetSelections(selList)

Sets the selection indices in selList as selected. Resets any previous selections for compatibility with wx.MultiChoiceDialog. Note that the state for only the filtered items is shown.

Parameters:

selList (list) – indices of items to be selected. These indices are referenced to the order in self.ChoiceList

onChar(event)

Respond to keyboard events in the Filter box

class GSASII.GSASIIctrlGUI.G2MultiChoiceWindow(parent, title, ChoiceList, SelectList, toggle=True, monoFont=False, filterBox=True, OnChange=None, OnChangeArgs=[], helpText=None)

Creates a sizer similar to G2MultiChoiceDialog except that buttons are added to set all choices and to toggle all choices. This is placed in a sizer, so that it can be used in a frame or panel.

Parameters:

• parent – reference to parent frame/panel

• title (str) – heading above list of choices

• ChoiceList (list) – a list of choices where one more will be selected

• SelectList (list) – a list of selected choices

• toggle (bool) – If True (default) the toggle and select all buttons are displayed

• monoFont (bool) – If False (default), use a variable-spaced font; if True use a equally-spaced font.

• filterBox (bool) – If True (default) an input widget is placed on the window and only entries matching the entered text are shown.

• OnChange (function) – a reference to a callable object, that is called each time any a choice is changed. Default is None which will not be called.

• OnChangeArgs (list) – a list of arguments to be supplied to function OnChange. The default is a null list.

Returns:

the name of the created sizer

Filter(event)

Read text from filter control and select entries that match. Called by Timer after a delay with no input or if Enter is pressed.

GetSelections()

Returns a list of the indices for the selected choices

OnCheck(event)

for CheckListBox events; if Set Range is in use, this sets/clears all entries in range between start and end according to the value in start. Repeated clicks on the start change the checkbox state, but do not trigger the range copy. The caption next to the button is updated on the first button press.

SetRange(event)

Respond to a press of the Set Range button. Set the range flag and the caption next to the button

SetSelections(selList)

Sets the selection indices in selList as selected. Resets any previous selections for compatibility with wx.MultiChoiceDialog. Note that the state for only the filtered items is shown.

Parameters:

selList (list) – indices of items to be selected. These indices are referenced to the order in self.ChoiceList

onChar(event)

Respond to keyboard events in the Filter box

GSASII.GSASIIctrlGUI.G2RadioButtons(parent, loc, key, choices, values=None, OnChange=None)

A customized version of wx.RadioButton that returns a list of coupled RadioButtons

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the widgets. Can be None.

• loc (dict/list) – the dict or list with the initial value to be placed in the CheckBox.

• key (int/str) – the dict key or the list index for the value to be edited by the CheckBox. The loc[key] element must exist. The CheckButton will be initialized from this value.

• choices (list)

• values (list)

• OnChange (function) – specifies a function or method that will be called when the CheckBox is changed (Default is None). The called function is supplied with one argument, the calling event.

class GSASII.GSASIIctrlGUI.G2RefinementProgress(title='Refinement progress', message='All data Rw =', maximum=101, parent=None, trialMode=False, seqLen=0, seqShow=3, style=None)

Defines an replacement for wx.ProgressDialog to be used for showing refinement progress.

Parameters:

• title (str) – string to place on border of window (default is ‘Refinement progress’).

• message (str) – initial string to place on top line of window.

• maximum (int) – maximum value for progress gauge bar on bottom of window.

• parent (wx.Frame) – parent window for creation of this dialog

• trialMode (bool) – Set to True for Levenberg-Marquardt fitting where Rw may be computed several times for a single cycle. Call AdvanceCycle() when trialMode is True to indicate that a cycle has been completed. Default is False.

• seqLen (int) – Number of histograms in sequential fit. A value of zero (default) means that the fit is not a sequential fit.

• seqShow (int) – Number of histograms to shown in a sequential fit (default 3)

• style (int) – optional parameters that determine how the dialog is is displayed.

AdvanceCycle(cycle=None)

Call this directly with Levenberg-Marquardt fitting after a cycle completes. Plots the results.

Destroy()

Destroy the window, but allow events to clear before doing so

SetHistogram(nextHist, histLbl)

Set this before beginning processing of each histogram

SetMaxCycle(value)

Set the maximum number of cycles or histograms (sequential fit). Used to scale settings so the gauge bar completes close to 100%. Ignored for sequential refinements.

Update(value=None, newmsg='')

designed to work with calls intended for wx.ProgressDialog.Update the value is assumed to be the current wR value for the histogram selected with SetHistogram and newmsg goes into the 2nd status line.

GSASII.GSASIIctrlGUI.G2ScrolledGrid(G2frame, lbl, title, tbl, colLbls, colTypes, maxSize=(600, 300), comment='')

Display a scrolled table of information in a dialog window

Parameters:

• G2frame (wx.Frame) – parent for dialog

• lbl (str) – label for window

• title (str) – window title

• tbl (list) – list of lists where inner list is each row

• colLbls (list) – list of str with labels for each column

• colTypes (list) – Data types for each column (such as wg.GRID_VALUE_STRING,wg.GRID_VALUE_FLOAT)

• maxSize (list) – Maximum size for the table in points. Defaults to (600,300)

• comment (str) – optional text that appears below table

Example:

row = ['item1',1.234,'description of item']
colTypes = [wg.GRID_VALUE_STRING,wg.GRID_VALUE_FLOAT+':8,4',wg.GRID_VALUE_STRING]
colLbls = ['item name','value','Description']
G2ScrolledGrid(frm,'window label','title',20*[row],colLbls,colTypes)

class GSASII.GSASIIctrlGUI.G2SingleChoiceDialog(parent, title, header, ChoiceList, monoFont=False, filterBox=True, **kw)

A dialog similar to wx.SingleChoiceDialog except that a filter can be added.

Parameters:

• ParentFrame (wx.Frame) – reference to parent frame

• title (str) – heading above list of choices

• header (str) – Title to place on window frame

• ChoiceList (list) – a list of choices where one will be selected

• monoFont (bool) – If False (default), use a variable-spaced font; if True use a equally-spaced font.

• filterBox (bool) – If True (default) an input widget is placed on the window and only entries matching the entered text are shown.

• kw – optional keyword parameters for the wx.Dialog may be included such as size [which defaults to (320,310)] and style (which defaults to wx.DEFAULT_DIALOG_STYLE | wx.RESIZE_BORDER | wx.CENTRE | wx.OK | wx.CANCEL); note that wx.OK and wx.CANCEL controls the presence of the eponymous buttons in the dialog.

Returns:

the name of the created dialog

Example:

dlg = G2SingleChoiceDialog(G2frame,'Select option from list',
                               'Select option',optList)
dlg.CenterOnParent()
try:
    if dlg.ShowModal() == wx.ID_OK:
        sel = optList[dlg.GetSelection()]
    else:
        return
finally:
    dlg.Destroy()

GetSelection()

Returns the index of the selected choice

class GSASII.GSASIIctrlGUI.G2Slider(parent, id=-1, value=0, minValue=0, maxValue=100, *arg, **kwarg)

Wrapper around wx.Slider widget that implements scaling Also casts floats as integers to avoid py3.10+ errors

SetLineSize(lineSize) → None

Sets the line size for the slider.

SetMax(maxValue) → None

Sets the maximum slider value.

SetMin(minValue) → None

Sets the minimum slider value.

SetValue(value) → None

Sets the slider position.

GSASII.GSASIIctrlGUI.G2SliderWidget(parent, loc, key, label, xmin, xmax, iscale, onChange=None, onChangeArgs=[], sizer=None, nDig=None, size=(50, 20), slsize=(200, 25))

A customized combination of a wx.Slider and a validated wx.TextCtrl (see ValidatedTxtCtrl) that allows either a slider or text entry to set a value within a range.

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the TextCtrl. Can be None.

• loc (dict/list) – the dict or list with the initial value to be placed in the TextCtrl.

• key (int/str) – the dict key or the list index for the value to be edited by the TextCtrl. The loc[key] element must exist and should have a float value. It will be forced to an initial value between xmin and xmax.

• label (str) – A label to be placed to the left of the slider.

• xmin (float) – the minimum allowed valid value.

• xmax (float) – the maximum allowed valid value.

• iscale (float) – number to scale values to integers, which is what the Scale widget uses. If the xmin=1 and xmax=4 and iscale=1 then values only the values 1,2,3 and 4 can be set with the slider. However, if iscale=2 then the values 1, 1.5, 2, 2.5, 3, 3.5 and 4 are all allowed.

• onChange (callable) – function to call when value is changed. Default is None where nothing will be called.

• onChangeArgs (list) – arguments to be passed to onChange function when called.

• sizer (wx.Sizer) – a reference to a wx.BoxSizer to be used to place the TextCtrl and Slider into. If None (the default), the sizer is created.

• size (tuple) – size of the TextCtrl [defaults to (50,20)]

• slsize (tuple) – slsize of the Slider [defaults to (200,25)]

Returns:

returns a wx.BoxSizer containing the widgets

GSASII.GSASIIctrlGUI.G2SpinWidget(parent, loc, key, label, xmin=None, xmax=None, nDig=None, onChange=None, typeHint=<class 'int'>, onChangeArgs=[], size=(50, 25))

A customized combination of a wx.SpinButton and a validated wx.TextCtrl (see ValidatedTxtCtrl) that allows either a the spin button or text entry to set a value within a range.

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the TextCtrl. Can be None.

• loc (dict/list) – the dict or list with the initial value to be placed in the TextCtrl.

• key (int/str) – the dict key or the list index for the value to be edited by the TextCtrl. The loc[key] element must exist and should have a float or int value. It will be forced to an integer initial value between xmin and xmax.

• label (str) – A label to be placed to the left of the entry widget.

• xmin (int) – the minimum allowed valid value. If None it is ignored.

• xmax (int) – the maximum allowed valid value. If None it is ignored.

• nDig (list) – as defined for ValidatedTxtCtrl

• onChange (callable) – function to call when value is changed. Default is None where nothing will be called.

• onChangeArgs (list) – arguments to be passed to onChange function when called.

• size (int) – size of TextCtrl in pixels. Defaults to (50,25).

Returns:

returns a wx.BoxSizer containing the widgets

class GSASII.GSASIIctrlGUI.G2TreeCtrl(parent=None, *args, **kwargs)

Create a wrapper around the standard TreeCtrl so we can “wrap” various events.

AppendItem(parent, text, image=-1, selImage=-1, data=None)

override the standard method so font size can be set

ConvertRelativeHistNum(histtype, histnum)

Converts a histogram type and relative histogram number to a histogram name in the current project

ConvertRelativePhaseNum(phasenum)

Converts relative phase number to a phase name in the current project

GetImageLoc(TreeId)

Get Image data from the Tree. Handles cases where the image name is specified, as well as where the image file name is a tuple containing the image file and an image number

GetItemPyData(treeId)

GetItemData(item) -> TreeItemData

Returns the tree item data associated with the item.

GetRelativeHistNum(histname)

Returns list with a histogram type and a relative number for that histogram, or the original string if not a histogram

GetRelativePhaseNum(phasename)

Returns a phase number if the string matches a phase name or else returns the original string

RestoreExposedItems()

Traverse the top level tree items and restore exposed (expanded) tree items back to their previous state (done after a reload of the tree after a refinement)

SaveExposedItems()

Traverse the top level tree items and save names of exposed (expanded) tree items. Done before a refinement.

SetItemPyData(treeId, data)

SetItemData(item, data) -> None

Sets the item client data.

UpdateImageLoc(TreeId, imagefile)

Saves a new imagefile name in the Tree. Handles cases where the image name is specified, as well as where the image file name is a tuple containing the image file and an image number

class GSASII.GSASIIctrlGUI.GSGrid(parent, name='')

Basic wx.Grid implementation

InstallGridToolTip(rowcolhintcallback, colLblCallback=None, rowLblCallback=None)

code to display a tooltip for each item on a grid from http://wiki.wxpython.org/wxGrid%20ToolTips (buggy!), expanded to column and row labels using hints from https://groups.google.com/forum/#!topic/wxPython-users/bm8OARRVDCs

Parameters:

• rowcolhintcallback (function) – a routine that returns a text string depending on the selected row and column, to be used in explaining grid entries.

• colLblCallback (function) – a routine that returns a text string depending on the selected column, to be used in explaining grid columns (if None, the default), column labels do not get a tooltip.

• rowLblCallback (function) – a routine that returns a text string depending on the selected row, to be used in explaining grid rows (if None, the default), row labels do not get a tooltip.

SetTable(table, *args, **kwargs)

Overrides the standard SetTable method with one that uses GridFractionEditor for all numeric columns (unless useFracEdit is false)

completeEdits()

complete any outstanding edits

setupPopup(lblList, callList)

define a callback that creates a popup menu. The rows associated with the items selected items are selected in the table and if an item is called from the menu, the corresponding function is called to perform an action on the

Parameters:

• lblList (list) – list of str items that will be placed in the popup menu

• callList (list) – list of functions to be called when a

Returns:

a callback that can be used to create the menu

Sample usage:

lblList = ('Delete','Set atom style','Set atom label',
               'Set atom color','Set view point','Generate copy',
               'Generate surrounding sphere','Transform atoms',
               'Generate bonded')
callList = (DrawAtomsDelete,DrawAtomStyle, DrawAtomLabel,
                DrawAtomColor,SetViewPoint,AddSymEquiv,
                AddSphere,TransformSymEquiv,
                FillCoordSphere)
onRightClick = drawAtoms.setupPopup(lblList,callList)
drawAtoms.Bind(wg.EVT_GRID_CELL_RIGHT_CLICK, onRightClick)
drawAtoms.Bind(wg.EVT_GRID_LABEL_RIGHT_CLICK, onRightClick)

class GSASII.GSASIIctrlGUI.GSNoteBook(parent, name='', size=None, style=257)

Notebook used in various locations; implemented with wx.aui extension

ChangeSelection(n) → int

Changes the selection for the given page, returning the previous selection.

FindPage(page) → int

Returns the index of the specified tab window or wxNOT_FOUND if not found.

GSASII.GSASIIctrlGUI.GetCite(key, wrap=None, indent=None)

Return citation information, optionally with text wrapping.

GSASII.GSASIIctrlGUI.GetConfigValsDocs()

Reads the module referenced in fname (often <module>.__file__) and return a dict with names of global variables as keys. For each global variable, the value contains four items:

Returns:

a dict where keys are names defined in module config_example.py where the value is a list of four items, as follows:

• item 0: the default value

• item 1: the current value

• item 2: the initial value (starts same as item 1)

• item 3: the “docstring” that follows variable definition

GSASII.GSASIIctrlGUI.GetExportPath(G2frame)

Determines the default location to use for writing files. Tries sequentially G2frame.LastExportDir and G2frame.LastGPXdir.

Returns:

a string containing the path to be used when writing files or ‘.’ if none of the above are specified.

GSASII.GSASIIctrlGUI.GetImportFile(G2frame, message, defaultDir='', defaultFile='', style=1, parent=None, *args, **kwargs)

Uses a standard or GSASII-customized dialog that gets files from the appropriate import directory. Arguments are used the same as in wx.FileDialog(). Selection of multiple files is allowed if argument style includes wx.FD_MULTIPLE.

The default initial directory (unless overridden with argument defaultDir) is found in G2frame.TutorialImportDir, config setting Import_directory or G2frame.LastImportDir, see GetImportPath().

The path of the first file entered is used to set G2frame.LastImportDir and optionally config setting Import_directory.

Returns:

a list of files or an empty list

GSASII.GSASIIctrlGUI.GetImportPath(G2frame)

Determines the default location to use for importing files. Tries sequentially G2frame.TutorialImportDir, config var Import_directory, G2frame.LastImportDir and G2frame.LastGPXdir

Returns:

a string containing the path to be used when reading files or ‘.’ if none of the above are specified.

GSASII.GSASIIctrlGUI.GetItemOrder(parent, keylist, vallookup, posdict)

Creates a dialog where items can be ordered into columns

Parameters:

• keylist (list) – is a list of keys for column assignments

• vallookup (dict) – is a dict keyed by names in keylist where each item is a dict. Each inner dict contains variable names as keys and their associated values

• posdict (dict) – is a dict keyed by names in keylist where each item is a dict. Each inner dict contains column numbers as keys and their associated variable name as a value. This is used for both input and output.

class GSASII.GSASIIctrlGUI.GridFractionEditor(grid)

A grid cell editor class that allows entry of values as fractions as well as sine and cosine values [as s() and c(), sin() or sind(), etc]. Any valid Python expression will be evaluated.

The current value can be incremented, multiplied or divided by prefixing an expression by +, * or / respectively.

ApplyEdit(row, col, grid)

Called only in wx >= 2.9 Save the value of the control into the grid if EndEdit() returns as True

BeginEdit(row, col, grid) → None

Fetch the value from the table and prepare the edit control to begin editing.

Clone() → GridCellEditor

Create a new object which is the copy of this one.

Create(parent, id, evtHandler) → None

Creates the actual edit control.

EndEdit(row, col, grid, oldval)

End editing the cell.

This function must check if the current value of the editing cell is valid and different from the original value in its string form. If not then simply return None. If it has changed then this method should save the new value so that ApplyEdit can apply it later and the string representation of the new value should be returned.

Notice that this method shoiuld not modify the grid as the change could still be vetoed.

Reset() → None

Reset the value in the control back to its starting value.

SetSize(rect) → None

Size and position the edit control.

StartingKey(event) → None

If the editor is enabled by pressing keys on the grid, this will be called to let the editor do something about that first key if desired.

class GSASII.GSASIIctrlGUI.HelpButton(parent, msg='', helpIndex='', wrap=None)

Create a help button that displays help information. The text can be displayed in a modal message window or it can be a reference to a location in the gsasII help web pages, in which case that page is opened in a web browser.

TODO: it might be nice if it were non-modal: e.g. it stays around until the parent is deleted or the user closes it, but this did not work for me.

Parameters:

• parent – the panel/frame where the button will be placed

• msg (str) – the help text to be displayed. Indentation on multiline help text is stripped (see StripIndents()). If wrap is set as non-zero, all new lines are

• helpIndex (str) –

  selection for the help information in the GSAS-II help files, in the form of an anchor string. That anchor is looked up to find the file name and the URL is constructed from:

  <location> + <filename> + “#” + helpIndex

• wrap (int) – if specified, the text displayed is reformatted by wrapping it to fit in wrap pixels. Default is None which prevents wrapping.

GSASII.GSASIIctrlGUI.HistogramNameTemplate(exporter, stripChars)

Dialog to obtain a string value for grouping histograms

Parameters:

• exporter (obj) – reference to exporter object

• stripChars (str) – Characters that are not allowed in file names

GSASII.GSASIIctrlGUI.HorizontalLine(sizer, parent)

Draws a horizontal line as wide as the window.

GSASII.GSASIIctrlGUI.ImportMsg(parent, msgs)

Show a message with the warnings from importers that could not be installed (due to uninstalled Python packages). Then offer the chance to install GSAS-II packages using SelectPkgInstall()

GSASII.GSASIIctrlGUI.ItemSelector(ChoiceList, ParentFrame=None, title='Select an item', size=None, header='Item Selector', useCancel=True, multiple=False)

Provide a wx dialog to select a single item or multiple items from list of choices

Parameters:

• ChoiceList (list) – a list of choices where one will be selected

• ParentFrame (wx.Frame) – Name of parent frame (default None)

• title (str) – heading above list of choices (default ‘Select an item’)

• size (wx.Size) – Size for dialog to be created (default None – size as needed)

• header (str) – Title to place on window frame (default ‘Item Selector’)

• useCancel (bool) – If True (default) both the OK and Cancel buttons are offered

• multiple (bool) – If True then multiple items can be selected (default False)

Returns:

the selection index or None or a selection list if multiple is true

Called by GSASIIdataGUI.OnReOrgSelSeq() Which is not fully implemented.

Example:

choices = ('NXazint1d 1D file','NXazint1d 2D file')
sel = G2G.ItemSelector(choices, ParentFrame=ParentFrame,
                        header='Select file section',
                        title='Select the section of the file to read')
if sel is None: return False

GSASII.GSASIIctrlGUI.Load2Cells(G2frame, phase)

Accept two unit cells and use NIST*LATTICE to search for a relationship that relates them.

The first unit cell is initialized as the currently selected phase and the second unit cell is set to the first different phase from the tree. The user can initialize the cell parameters to select a different phase for either cell or can type in the values themselves.

Parameters:

• G2frame (wx.Frame) – The main GSAS-II window

• phase (dict) – the currently selected frame

GSASII.GSASIIctrlGUI.MultiColMultiSelDlg(parent, title, header, colInfo, choices)

Provides a dialog widget that can be used to select multiple items from a multicolumn list.

Parameters:

• parent (wx.Frame) – the parent frame (or None)

• title (str) – A title for the dialog window

• header (str) – A instruction string for the dialog window

• colInfo (list) – contains three items for each column: a label for the column, a width for the column (in pixels), and True if the column should be right justified.

• choices (list) – a nested list with values for each row in the table. Within each row should be a list of values for each column. There must be at least one value, but it is OK to have more or fewer values than there are column labels (colInfo). Extra are ignored and unspecified columns are left blank.

Returns:

a list of bool values for each entry in choices, True if selected, or None is the dialog is cancelled.

Example use:

choices = [('xmltodict', 'Bruker .brml Importer'),
           ('zarr', 'MIDAS Zarr importer'),
           ('h5py', 'HDF5 image importer'),
           ('hdf5', 'HDF5 image importer')]
colInfo = [('package', 50, False),
           ('needed by', 200, True)]
res = G2G.MultiColMultiSelDlg(parent, 'window title', 'Instructions', colInfo, choices)

class GSASII.GSASIIctrlGUI.MultiColumnSelection(parent, title, colLabels, choices, colWidths, checkLbl='', height=400, centerCols=False, *args, **kw)

Defines a Dialog widget that can be used to select an item from a multicolumn list. The first column should be short, but remaining columns are word-wrapped if the length of the information extends beyond the column.

When created, the dialog will be shown and <dlg>.Selection will be set to the index of the selected row, or -1. Be sure to use <dlg>.Destroy() to remove the window after reading the selection. If the dialog cannot be shown because a very old version of wxPython is in use, <dlg>.Selection will be None.

If checkLbl is provided with a value, then a set of check buttons starts the table and <dlg>.Selections has the checked rows.

Parameters:

• parent (wx.Frame) – the parent frame (or None)

• title (str) – A title for the dialog window

• colLabels (list) – labels for each column

• choices (list) – a nested list with a value for each row in the table. Within each value should be a list of values for each column. There must be at least one value, but it is OK to have more or fewer values than there are column labels (colLabels). Extra are ignored and unspecified columns are left blank.

• colWidths (list) – a list of int values specifying the column width for each column in the table (pixels). There must be a value for every column label (colLabels).

• checkLbl (str) – A label for a row of checkboxes added at the beginning of the table. This option seems to be broken.

• height (int) – an optional height (pixels) for the table (defaults to 400)

• centerCols (bool) – if True, items in each column are centered. Default is False

Example use:

lbls = ('col 1','col 2','col 3')
choices=(['test1','explanation of test 1'],
         ['b', 'a really really long line that will be word-wrapped'],
         ['test3','more explanation text','optional 3rd column text'])
colWidths=[200,400,100]
dlg = MultiColumnSelection(frm,'select tutorial',lbls,choices,colWidths)
value = choices[dlg.Selection][0]
dlg.Destroy()

class GSASII.GSASIIctrlGUI.MultiDataDialog(parent, title, prompts, values, limits=[[0.0, 1.0]], testfxns=None, formats=['%.5g'], header=None)

Dialog to obtain multiple values from user. Use dlg.GetValues() to get the values set in the window.

Parameters:

• parent (wx.Frame) – parent frame for dialog to be created

• title (str) – title to place on top of window

• prompts (list) – a string to describe each item. Each entry in this list will designate a row in the generated window.

• values (list) – a list of initial values for each item. Use a nested list when multiple entries are placed on a single row of the window (see discussion of formats, below). Number of items in the outer list should match the length of prompts. The total number of items should match formats.

• limits (list) – A nested list with an upper and lower value for each item or for a choice/edit control a list of allowed values. Use a nested list when multiple entries are placed on a single row of the window (see discussion of formats, below). Number of items in the outer list should match the length of prompts. The total number of items should match formats.

• testfxns (list) – A nested list of string test functions. The total number of items should match formats or should be left as the default (None).

• formats (list) –

  A list of values for each entry in the window. Several different types of values are possible:

  • An “old-style” format string (e.g. %5d or %.3f) which will be used to display each item’s value

  • Or a keyword that specifies how the values are used. Allowed keywords are:

    • choice: for a pull-down list;

    • bool: for a yes/no checkbox;

    • str: for a text entry

    • edit: for a pull-down list that allows one to enter an arbitrary value.

  • Alternately, a value can be a list of items, in which case multiple entries are placed on a single row of the window. When this is done, any value in the list other than choice or edit is used as text to be placed between the ComboBoxes.

  The number of items in the outer list should match the length of prompts.

• header (str) – a string to be placed at the top of the window. Ignored if None (the default.)

Example 1:

dlg = G2G.MultiDataDialog(G2frame,title='ISOCIF search',
        prompts=['lattice constants tolerance',
                 'coordinate tolerance',
                 'occupancy tolerance'],
        values=[0.001,0.01,0.1],
        limits=3*[[0.,2.]],formats=3*['%.5g'],
        header=isoCite)
dlg.ShowModal()
latTol,coordTol,occTol = dlg.GetValues()
dlg.Destroy()

Example 2:

nm = [' ','0','1','-1','2','-2','3','-3','4','5','6','7','8','9']
dm = ['1','2','3','4','5','6']
kfmt = ['choice','/','choice',',    ','choice','/','choice',',    ','choice','/','choice',' ']
dlg = MultiDataDialog(G2frame,title='options',
        prompts=[' k-vector 1 (x,y,z)',
                 ' k-vector 2 (x,y,z)'],
        values=[3*['0','','2',''],3*[' ','','2','']],
        limits=[3*[nm[1:],'',dm,''],3*[nm,'',dm,'']],
        formats=[kfmt,kfmt])
if dlg.ShowModal() == wx.ID_OK: print(dlg.GetValues())

class GSASII.GSASIIctrlGUI.MultiIntegerDialog(parent, title, prompts, values)

Input a series of integers based on prompts

class GSASII.GSASIIctrlGUI.MultiStringDialog(parent, title, prompts, values=[], size=-1, addRows=False, hlp=None, lbl=None)

Dialog to obtain a multi string values from user

Parameters:

• parent (wx.Frame) – name of parent frame

• title (str) – title string for dialog

• prompts (list) – list of strings to tell user what they are inputting

• values (list) – list of str default input values, if any

• size (int) – length of the input box in pixels

• addRows (bool) – if True, users can add rows to the table (default is False)

• hlp (str) – if supplied, a help button is added to the dialog that can be used to display the supplied help text in this variable.

• lbl (str) – label placed at top of dialog

Returns:

a wx.Dialog instance

GetValues()

Use this method to get the value(s) entered by the user

Returns:

a list of strings entered by user

Show()

Use this method after creating the dialog to post it

Returns:

True if the user pressed OK; False if the User pressed Cancel

GSASII.GSASIIctrlGUI.MultipleBlockSelector(ChoiceList, ParentFrame=None, title='Select a block', size=None, header='Block Selector')

Provide a wx dialog to select a block of data if the file contains more than one set of data and one must be selected. Used in G2pwd_CIF only.

Returns:

a list of the selected blocks

class GSASII.GSASIIctrlGUI.MultipleChoicesDialog(choicelist, headinglist, head='Select options', title='Please select from options below', parent=None)

A dialog that offers a series of choices, each with a title and a wx.Choice widget. Intended to be used Modally. typical input:

• choicelist=[ (‘a’,’b’,’c’), (‘test1’,’test2’),(‘no choice’,)]

• headinglist = [ ‘select a, b or c’, ‘select 1 of 2’, ‘No option here’]

selections are placed in self.chosen when OK is pressed

Also see GSASIIctrlGUI

GSASII.GSASIIctrlGUI.MultipleChoicesSelector(choicelist, headinglist, ParentFrame=None, **kwargs)

A modal dialog that offers a series of choices, each with a title and a wx.Choice widget. Used in G2pwd_CIF only.

Typical input:

• choicelist=[ (‘a’,’b’,’c’), (‘test1’,’test2’),(‘no choice’,)]

• headinglist = [ ‘select a, b or c’, ‘select 1 of 2’, ‘No option here’]

optional keyword parameters are: head (window title) and title returns a list of selected indicies for each choice (or None)

class GSASII.GSASIIctrlGUI.MyHelp(frame, includeTree=False, morehelpitems=[])

A class that creates the contents of a help menu. The menu will start with two entries:

• ‘Help on <helpType>’: where helpType is a reference to an HTML page to be opened

• About: opens an About dialog using OnHelpAbout. N.B. on the Mac this gets moved to the App menu to be consistent with Apple style.

NOTE: for this to work properly with respect to system menus, the title for the menu must be &Help, or it will not be processed properly:

menu.Append(menu=MyHelp(self,...),title="&Help")

OnCheckUpdates(event)

Check if the GSAS-II repository has an update for the current source files and perform that update if requested.

OnHelpAbout(event)

Display an ‘About GSAS-II’ box

OnHelpById(event)

Called when Help on… is pressed in a menu. Brings up a web page for documentation. Uses the G2frame.dataWindow.helpKey value to select what help is shown, unless a special help key value has been defined for the calling menu id (via a lookup in self.HelpById[], which is used for Tutorials & Overall help). Note that G2frame.dataWindow.helpKey SelectDataTreeItem and reflects the data tree item that has been selected.

Note that self here should be a child of the main window (G2frame) where self.frame is G2frame

OnSelectVersion(event)

Allow the user to select a specific version of GSAS-II

class GSASII.GSASIIctrlGUI.NumberValidator(typ, positiveonly=False, xmin=None, xmax=None, exclLim=[False, False], result=None, key=None, OKcontrol=None, CIFinput=False)

A validator to be used with a TextCtrl to prevent entering characters other than digits, signs, and for float input, a period and exponents.

The value is checked for validity after every keystroke

If an invalid number is entered, the box is highlighted. If the number is valid, it is saved in result[key]

Parameters:

• typ (type) – the base data type. Must be int or float.

• positiveonly (bool) – If True, negative integers are not allowed (default False). This prevents the + or - keys from being pressed. Used with typ=int; ignored for typ=float.

• xmin (number) – Minimum allowed value. If None (default) the lower limit is unbounded

• xmax (number) – Maximum allowed value. If None (default) the upper limit is unbounded

• exclLim (list) – if True exclude xmin/xmax value ([exclMin,exclMax]); (Default=[False,False])

• result (dict/list) – List or dict where value should be placed when valid

• key (any) – key to use for result (int for list)

• OKcontrol (function) – function or class method to control an OK button for a window. Ignored if None (default)

• CIFinput (bool) – allows use of a single ‘?’ or ‘.’ character as valid input.

CheckInput(previousInvalid)

called to test every change to the TextCtrl for validity and to change the appearance of the TextCtrl

Anytime the input is invalid, call self.OKcontrol (if defined) because it is fast. If valid, check for any other invalid entries only when changing from invalid to valid, since that is slower.

Parameters:

previousInvalid (bool) – True if the TextCtrl contents were invalid prior to the current change.

Clone()

Create a copy of the validator, a strange, but required component

OnChar(event)

Called each type a key is pressed ignores keys that are not allowed for int and float types

ShowValidity(tc)

Set the control colors to show invalid input

Parameters:

tc (wx.TextCtrl) – A reference to the TextCtrl that the validator is associated with.

TestValid(tc)

Check if the value is valid by casting the input string into the current type.

Set the invalid variable in the TextCtrl object accordingly.

If the value is valid, save it in the dict/list where the initial value was stored, if appropriate.

Parameters:

tc (wx.TextCtrl) – A reference to the TextCtrl that the validator is associated with.

TransferFromWindow()

Needed by validator, strange, but required component

TransferToWindow()

Needed by validator, strange, but required component

class GSASII.GSASIIctrlGUI.OpenGitTutorial(parent)

Open a tutorial web page from the git repository, optionally copying the tutorial’s exercise data file(s) to the local disk.

ChooseTutorial2(choices)

Select tutorials from a two-column table, when possible

SelectAndDownload(event)

Shows a list of all tutorials so user can select one to view. The data files associated with that directory are then downloaded.

SelectDownloadLoc(event)

Select a download location, Cancel resets to the default

SetTutorialPath()

Get the tutorial location if set; if not pick a default directory in a logical place

onWebBrowse(event)

Shows a list of all tutorials so user can select one to view.

Returns:

the name of the directory where the tutorial is located, which is used if called from SelectAndDownload().

class GSASII.GSASIIctrlGUI.OrderBox(parent, keylist, vallookup, posdict, *arg, **kw)

Creates a panel with scrollbars where items can be ordered into columns

Parameters:

• keylist (list) – is a list of keys for column assignments

• vallookup (dict) – is a dict keyed by names in keylist where each item is a dict. Each inner dict contains variable names as keys and their associated values

• posdict (dict) – is a dict keyed by names in keylist where each item is a dict. Each inner dict contains column numbers as keys and their associated variable name as a value. This is used for both input and output.

OnChoice(event)

Called when a column is assigned to a variable

GSASII.GSASIIctrlGUI.PhaseSelector(ChoiceList, ParentFrame=None, title='Select a phase', size=None, header='Phase Selector')

Provide a wx dialog to select a phase, used in importers if a file contains more than one phase

class GSASII.GSASIIctrlGUI.PickTwoDialog(parent, title, prompt, names, choices)

This does not seem to be in use

GSASII.GSASIIctrlGUI.ReadOnlyTextCtrl(*args, **kwargs)

Create a read-only TextCtrl for display of constants This is probably not ideal as it mixes visual cues, but it does look nice. Addresses 4.2 bug where TextCtrl has no default size

class GSASII.GSASIIctrlGUI.RefinementProgress(title='Residual', message='All data Rw =', maximum=101, parent=None, trialMode=False, seqLen=0, style=None)

Defines a wrapper to place around wx.ProgressDialog to be used for showing refinement progress. At some point a better progress window should be created that keeps useful info on the screen such as some starting and current fit metrics, but for now all this adds is window defaults and a wx.Yield call during progress update calls.

Update(value, newmsg='') → Tuple[bool, bool]

Updates the dialog, setting the progress bar to the new value and updating the message if new one is specified.

class GSASII.GSASIIctrlGUI.SGMagSpinBox(parent, title, text, table, Cents, names, spins, ifGray)

Special version of MessageBox that displays magnetic spin text

Show()

Use this method after creating the dialog to post it

class GSASII.GSASIIctrlGUI.SGMessageBox(parent, title, text, table, spins=[])

Special version of MessageBox that displays space group & super space group text in two blocks

Show()

Use this method after creating the dialog to post it

GSASII.GSASIIctrlGUI.SaveCite(prog, text)

Save citation information as it is referenced so that all of it can be displayed in the About GSAS-II window

GSASII.GSASIIctrlGUI.SaveConfigVars(vars, parent=None)

Write the current config variable values to ~/.GSASII/config.ini

Params dict vars:

a dictionary of variable settings and meanings as created in GetConfigValsDocs(). Most of the information gathered in GetConfigValsDocs is no longer used here.

Parameters:

parent – wx.Frame object or None. No longer used.

Returns:

True if unable to write the file, None otherwise

class GSASII.GSASIIctrlGUI.ScrolledMultiEditor(parent, dictlst, elemlst, prelbl=[], postlbl=[], title='Edit items', header='', size=(300, 250), CopyButton=False, ASCIIonly=False, minvals=[], maxvals=[], sizevals=[], checkdictlst=[], checkelemlst=[], checklabel='')

Define a window for editing a potentially large number of dict- or list-contained values with validation for each item. Edited values are automatically placed in their source location. If invalid entries are provided, the TextCtrl is turned yellow and the OK button is disabled.

The type for each TextCtrl validation is determined by the initial value of the entry (int, float or string). Float values can be entered in the TextCtrl as numbers or also as algebraic expressions using operators + - / * () and **, in addition pi, sind(), cosd(), tand(), and sqrt() can be used, as well as appreviations s(), sin(), c(), cos(), t(), tan() and sq().

Parameters:

• parent (wx.Frame) – name of parent window, or may be None

• dictlst (tuple) – a list of dicts or lists containing values to edit

• elemlst (tuple) – a list of keys/indices for items in dictlst. Note that elemlst must have the same length as dictlst, where each item in elemlst will will match an entry for an entry for successive dicts/lists in dictlst.

• prelbl (tuple) – a list of labels placed before the TextCtrl for each item (optional)

• postlbl (tuple) – a list of labels placed after the TextCtrl for each item (optional)

• title (str) – a title to place in the frame of the dialog

• header (str) – text to place at the top of the window. May contain new line characters.

• size (wx.Size) – a size parameter that dictates the size for the scrolled region of the dialog. The default is (300,250).

• CopyButton (bool) – if True adds a small button that copies the value for the current row to all fields below (default is False)

• ASCIIonly (bool) – if set as True will remove unicode characters from strings

• minvals (list) – optional list of minimum values for validation of float or int values. Ignored if value is None.

• maxvals (list) – optional list of maximum values for validation of float or int values. Ignored if value is None.

• sizevals (list) – optional list of wx.Size values for each input widget. Ignored if value is None.

• checkdictlst (tuple) – an optional list of dicts or lists containing bool values (similar to dictlst).

• checkelemlst (tuple) – an optional list of dicts or lists containing bool key values (similar to elemlst). Must be used with checkdictlst.

• checklabel (string) – a string to use for each checkbutton

Returns:

the wx.Dialog created here. Use method .ShowModal() to display it.

Example for use of ScrolledMultiEditor:

dlg = <pkg>.ScrolledMultiEditor(frame,dictlst,elemlst,prelbl,postlbl,
                                header=header)
if dlg.ShowModal() == wx.ID_OK:
     for d,k in zip(dictlst,elemlst):
         print d[k]

Example definitions for dictlst and elemlst:

    dictlst = (dict1,list1,dict1,list1)
    elemlst = ('a', 1, 2, 3)

This causes items dict1['a'], list1[1], dict1[2] and list1[3] to be edited.

Note that these items must have int, float or str values assigned to them. The dialog will force these types to be retained. String values that are blank are marked as invalid.

ControlOKButton(setvalue)

Enable or Disable the OK button for the dialog. Note that this is passed into the ValidatedTxtCtrl for use by validators.

Parameters:

setvalue (bool) – if True, all entries in the dialog are checked for validity. if False then the OK button is disabled.

class GSASII.GSASIIctrlGUI.ScrolledStaticText(parent, label='', delay=100, lbllen=15, dots=True, **kwargs)

Fits a long string into a small space by scrolling it. Inspired by ActiveText.py from J Healey <rolfofsaxony@gmx.com> https://discuss.wxpython.org/t/activetext-rather-than-statictext/36370

Use examples:

frm = wx.Frame(None) # create a frame
ms = wx.BoxSizer(wx.VERTICAL)
text = 'this is a long string that will be scrolled'
ms.Add(G2G.ScrolledStaticText(frm,label=text))
txt = G2G.ScrolledStaticText(frm,label=text, lbllen=20)
smallfont = wx.SystemSettings.GetFont(wx.SYS_SYSTEM_FONT)
smallfont.SetPointSize(10)
txt.SetFont(smallfont)
ms.Add(txt)
ms.Add(G2G.ScrolledStaticText(frm,label=text,dots=False,delay=250,lbllen=20))
frm.SetSizer(ms)

Parameters:

• parent (w.Frame) – Frame or Panel where widget will be placed

• label (str) – string to be displayed

• delay (int) – time between updates in ms (default is 100)

• lbllen (int) – number of characters to show (default is 15)

• dots (bool) – If True (default) ellipsis (…) are placed at the beginning and end of the string when any characters in the string are not shown. The displayed string length will thus be lbllen+6 most of the time

• (other) – other optional keyword parameters for the wx.StaticText widget such as size or style may be specified.

class GSASII.GSASIIctrlGUI.SelectConfigSetting(parent)

Dialog to select configuration variables and set associated values.

OnBoolSelect(event)

Respond to a change in a True/False variable

OnChange(event=None)

Check if anything been changed. Turn the save button on/off.

OnSave(event)

Write the config variables to ~/.GSASII/config.ini as the current settings

OnSelection()

show a selected variable and allow it to be changed

onSelColor(event)

Select a color from a menu

onSelDir(event)

Select a directory from a menu

onSelExec(event)

Select an executable file from a menu

GSASII.GSASIIctrlGUI.SelectEdit1Var(G2frame, array, labelLst, elemKeysLst, dspLst, refFlgElem)

Select a variable from a list, then edit it and select histograms to copy it to.

Parameters:

• G2frame (wx.Frame) – main GSAS-II frame

• array (dict) – the array (dict or list) where values to be edited are kept

• labelLst (list) – labels for each data item

• elemKeysLst (list) – a list of lists of keys needed to be applied (see below) to obtain the value of each parameter

• dspLst (list) – list list of digits to be displayed (10,4) is 10 digits with 4 decimal places. Can be None.

• refFlgElem (list) – a list of lists of keys needed to be applied (see below) to obtain the refine flag for each parameter or None if the parameter does not have refine flag.

Example:

 array = data
 labelLst = ['v1','v2']
 elemKeysLst = [['v1'], ['v2',0]]
 refFlgElem = [None, ['v2',1]]

* The value for v1 will be in data['v1'] and this cannot be refined while,
* The value for v2 will be in data['v2'][0] and its refinement flag is data['v2'][1]

GSASII.GSASIIctrlGUI.SelectPkgInstall(event)

Offer the user a chance to install Python packages needed by one or more importers. There might be times where something like this will be useful for other GSAS-II actions.

GSASII.GSASIIctrlGUI.SelectSearchVars(G2frame, labelLst, keyDict)

Get a sample parameter and a comment label from the user so we can search for that in the comments.

Returns:

Selection, Key, where Selection is the parameter name to be set (from labelLst) and Key will be a value tag from keyDict or an equation object (from GSASIIexprGUI.ExpressionDialog()). Both will be None if command is cancelled.

GSASII.GSASIIctrlGUI.ShowCitations(event)

Show all work that GSAS-II users may wish to cite

GSASII.GSASIIctrlGUI.ShowHelp(helpType, frame, helpMode=None)

Called to bring up a web page for documentation.

class GSASII.GSASIIctrlGUI.ShowLSParms(G2frame, title, parmDict, varyList, fullVaryList, Controls, size=(650, 430))

Create frame to show least-squares parameters

DrawPanel()

Draws the contents of the entire dialog. Called initially & when radio buttons are pressed

repaintScrollTbl()

Shows the selected variables in a ListCtrl

GSASII.GSASIIctrlGUI.ShowScrolledColText(parent, txt, width=600, height=400, header='Warning info', col1len=999)

Simple code to display tabular information in a scrolled wx.Dialog window.

Lines ending with a colon (:) are centered across all columns and have a grey background. Lines beginning and ending with ‘**’ are also are centered across all columns and are given a yellow background All other lines have columns split by tab (t) characters.

Parameters:

• parent (wx.Frame) – parent window

• txt (str) – text to be displayed

• width (int) – lateral of window in pixels (defaults to 600)

• height (int) – vertical dimension of window in pixels (defaults to 400)

• header (str) – title to be placed on window

GSASII.GSASIIctrlGUI.ShowScrolledInfo(parent, txt, width=600, height=400, header='Warning info', buttonlist=None)

Simple code to display possibly extensive error or warning text in a scrolled window.

Parameters:

• parent (wx.Frame) – parent window for

• txt (str) – text to be displayed

• width (int) – lateral of window in pixels (defaults to 600)

• height (int) – vertical dimension of window in pixels (defaults to 400)

• header (str) – title to be placed on window

• buttonlist (list) – list of button Ids to show, or one or more pairs of values, where the first is a label to place on the button and the second is a routine that is called if the button is pressed. The default is None which places a single “Close” button that returns wx.ID_CANCEL

Returns:

the wx Id for the selected button

Example:

res = ShowScrolledInfo(self.frame,msg,header='Please Note',buttonlist=[
        ('Open', lambda event: event.GetEventObject().GetParent().EndModal(wx.ID_OK)),
        ('Skip', lambda event: event.GetEventObject().GetParent().EndModal(wx.ID_CANCEL))
       ])
if res == wx.ID_OK:
    pass

GSASII.GSASIIctrlGUI.ShowWebPage(URL, frame, browser=False, internal=False)

Called to show a tutorial web page.

Parameters:

• URL (str) – web page URL

• frame (wx.Frame) – parent window (or None)

• browser (bool) – If True, forces the page to be opened in a web browser, regardless of the Help_mode config setting.

class GSASII.GSASIIctrlGUI.SingleFloatDialog(parent, title, prompt, value, limits=[0.0, 1.0], fmt='%.5g')

Dialog to obtain a single float value from user

Parameters:

• parent (wx.Frame) – name of parent frame

• title (str) – title string for dialog

• prompt (str) – string to tell user what they are inputing

• value (str) – default input value, if any

• limits (list) – upper and lower value used to set bounds for entry, use [None,None] for no bounds checking, [None,val] for only upper bounds, etc. Default is [0,1]. Values outside of limits will be ignored.

• format (str) – string to format numbers. Defaults to ‘%.5g’. Use ‘%d’ to have integer input (but dlg.GetValue will still return a float).

Typical usage:

limits = (0,1)
dlg = G2G.SingleFloatDialog(G2frame,'New value','Enter new value for...',default,limits)
if dlg.ShowModal() == wx.ID_OK:
    parm = dlg.GetValue()
dlg.Destroy()

ControlOKButton(setvalue)

Enable or Disable the OK button for the dialog. Note that this is passed into the ValidatedTxtCtrl for use by validators.

Parameters:

setvalue (bool) – if True, all entries in the dialog are checked for validity. if False then the OK button is disabled.

class GSASII.GSASIIctrlGUI.SingleIntDialog(parent, title, prompt, value, limits=[None, None])

Dialog to obtain a single int value from user

Parameters:

• parent (wx.Frame) – name of parent frame

• title (str) – title string for dialog

• prompt (str) – string to tell user what they are inputing

• value (str) – default input value, if any

• limits (list) – upper and lower value used to set bounds for entries. Default is [None,None] – for no bounds checking; use [None,val] for only upper bounds, etc. Default is [0,1]. Values outside of limits will be ignored.

Typical usage:

limits = (0,None)  # allows zero or positive values only
dlg = G2G.SingleIntDialog(G2frame,'New value','Enter new value for...',default,limits)
if dlg.ShowModal() == wx.ID_OK:
    parm = dlg.GetValue()
dlg.Destroy()

class GSASII.GSASIIctrlGUI.SingleStringDialog(parent, title, prompt, value='', size=(200, -1), help='', choices=None)

Dialog to obtain a single string value from user

Parameters:

• parent (wx.Frame) – name of parent frame

• title (str) – title string for dialog

• prompt (str) – string to tell use what they are inputting

• value (str) – default input value, if any

• size (tuple) – specifies default size and width for the text entry section of the dialog [default (200,-1)]. If the vertical size (the second number) is greater than 20 (~ a single line) then the textbox will allow inclusion of new-line characters. In single-line mode, return causes the dialog to close.

• help (str) – if supplied, a help button is added to the dialog that can be used to display the supplied help text/URL for setting this variable. (Default is ‘’, which is ignored.)

• choices (list) – a set of strings that provide optional values that can be selected from; these can be edited if desired.

GetValue()

Use this method to get the value entered by the user :returns: string entered by user

Show()

Use this method after creating the dialog to post it :returns: True if the user pressed OK; False if the User pressed Cancel

class GSASII.GSASIIctrlGUI.SortableLstCtrl(parent)

Creates a read-only table with sortable columns. Sorting is done by clicking on a column label. A triangle facing up or down is added to indicate the column is sorted.

To use, the header is labeled using PopulateHeader(), then PopulateLine() is called for every row in table and finally SetColWidth() is called to set the column widths.

Parameters:

parent (wx.Frame) – parent object for control

Example:

data = [
   (':0:sig-0', '30.7906', '30.7907', 'Pwd=SNAP066555: TOF profile term'),
   (':0:sig-1', '208.419', '208.419', 'Pwd=SNAP066555: TOF profile term'),
   (':0:Scale', '582006', '582006', 'Pwd=SNAP066555: Scale factor'),
   (':1:Scale', '592440', '592440', 'Pwd=SNAP06 (1): Scale factor'),
]
sortPanel = G2G.SortableLstCtrl(G2frame)
sortPanel.PopulateHeader([f'label{i}' for i in range(4)],4*[0])
for i,l in enumerate(data): sortPanel.PopulateLine(i,l)
for i in range(4): sortPanel.SetColWidth(i) # set width to automatic
sortPanel.SetColWidth(1,sortType='float') # sort 1st column by numeric value not str

PopulateHeader(header, justify)

Defines the column labels

Parameters:

• header (list) – a list of strings with header labels

• justify (list) – a list of int values where 0 causes left justification, 1 causes right justification, and -1 causes centering

PopulateLine(key, data)

Enters each row into the table

Parameters:

• key (int) – a unique int value for each line, probably should be sequential

• data (list) – a list of strings for each column in that row

SetColWidth(col, width=None, auto=True, minwidth=0, maxwidth=None, sortType='str')

Sets the column width.

Parameters:

• width (int) – the column width in pixels

• auto (bool) – if True (default) and width is None (default) the width is set by the maximum width entry in the column

• minwidth (int) – used when auto is True, sets a minimum column width

• maxwidth (int) – used when auto is True, sets a maximum column width. Do not use with minwidth

SetInitialSortColumn(col, ascending=True)

Sets the initial column to be used for sorting when the table is first displayed. This method should be called after all PopulateLine calls are complete. The up or down arrow indicator will be displayed on the specified column.

Parameters:

• col (int) – the column index (0-based) to sort by initially

• ascending (bool) – if True (default), sort in ascending order; if False, descending

GSASII.GSASIIctrlGUI.StringSearchTemplate(parent, title, prompt, start, help=None)

Dialog to obtain a single string value from user

Parameters:

• parent (wx.Frame) – name of parent frame

• title (str) – title string for dialog

• prompt (str) – string to tell use what they are inputting

• start (str) – default input value, if any

• help (str) – if supplied, a help button is added to the dialog that can be used to display the supplied help text/URL for setting this variable. (Default is ‘’, which is ignored.)

GSASII.GSASIIctrlGUI.StripIndents(msg, singleLine=False)

Strip unintended indentation from multiline strings. When singleLine is True, all newline are removed, but inserting “%%” into the string will cause a blank line to be inserted at that point and %t% will generate a new line and tab (to indent a line)

Parameters:

• msg (str) – a string containing one or more lines of text. spaces or tabs following a newline are removed.

• singleLine (bool) – removes all newlines from the msg so that the text may be wrapped.

Returns:

the string but reformatted

GSASII.GSASIIctrlGUI.StripUnicode(string, subs='.')

Strip non-ASCII characters from strings

Parameters:

• string (str) – string to strip Unicode characters from

• subs (str) – character(s) to place into string in place of each Unicode character. Defaults to ‘.’

Returns:

a new string with only ASCII characters

class GSASII.GSASIIctrlGUI.Table(data=[], rowLabels=None, colLabels=None, types=None)

Basic data table for use with GSgrid

AppendRows(numRows=1) → bool

Append additional rows at the end of the table.

CanGetValueAs(row, col, typeName) → bool

Returns true if the value of the given cell can be accessed as if it were of the specified type.

CanSetValueAs(row, col, typeName) → bool

Returns true if the value of the given cell can be set as if it were of the specified type.

GetColLabelValue(col) → str

Return the label of the specified column.

GetNumberCols() → int

Must be overridden to return the number of columns in the table.

GetNumberRows() → int

Must be overridden to return the number of rows in the table.

GetRowLabelValue(row) → str

Return the label of the specified row.

GetTypeName(row, col) → str

Returns the type of the value in the given cell.

GetValue(row, col) → Any

Must be overridden to implement accessing the table values as text.

InsertRows(pos=0, numRows=1) → bool

Insert additional rows into the table.

IsEmptyCell(row, col) → bool

May be overridden to implement testing for empty cells.

SetColLabelValue(col, label) → None

Exactly the same as SetRowLabelValue() but for columns.

SetRowLabelValue(row, label) → None

Set the given label for the specified row.

SetValue(row, col, value) → None

Must be overridden to implement setting the table values as text.

class GSASII.GSASIIctrlGUI.ValidatedTxtCtrl(parent, loc, key, nDig=None, notBlank=True, xmin=None, xmax=None, OKcontrol=None, OnLeave=None, typeHint=None, CIFinput=False, exclLim=[False, False], OnLeaveArgs={}, ASCIIonly=False, **kw)

Create a TextCtrl widget that uses a validator to prevent the entry of inappropriate characters and changes color to highlight when invalid input is supplied. As valid values are typed, they are placed into the dict or list where the initial value came from. The type of the initial value must be int, float or str or None (see key and typeHint); this type (or the one in typeHint) is preserved. Values are processed and saved when Enter is pressed, when the mouse is moved to another control (leave window or focus is lost) or after a change and a delay of two seconds.

Float values can be entered in the TextCtrl as numbers or also as algebraic expressions using operators (+ - / * () and **), in addition pi, sind(), cosd(), tand(), and sqrt() can be used, as well as appreviations s, sin, c, cos, t, tan and sq.

Parameters:

• parent (wx.Panel) – name of panel or frame that will be the parent to the TextCtrl. Can be None.

• loc (dict/list) – the dict or list with the initial value to be placed in the TextCtrl.

• key (int/str) –

  the dict key or the list index for the value to be edited by the TextCtrl. The loc[key] element must exist, but may have value None. If None, the type for the element is taken from typeHint and the value for the control is set initially blank (and thus invalid.) This is a way to specify a field without a default value: a user must set a valid value.

  If the value is not None, it must have a base type of int, float, str or unicode; the TextCrtl will be initialized from this value.

• nDig (list) – number of digits, places and optionally the format ([nDig,nPlc,fmt]) after decimal to use for display of float. The format is either ‘f’ (default) or ‘g’. Alternately, None can be specified which causes numbers to be displayed with approximately 5 significant figures for floats. If this is specified, then typeHint = float becomes the default. (Default=None).

• notBlank (bool) – if True (default) blank values are invalid for str inputs.

• xmin (number) – minimum allowed valid value. If None (default) the lower limit is unbounded. NB: test in NumberValidator is val >= xmin not val > xmin

• xmax (number) – maximum allowed valid value. If None (default) the upper limit is unbounded NB: test in NumberValidator is val <= xmax not val < xmax

• exclLim (list) – if True exclude min/max value ([exclMin,exclMax]); (Default=[False,False])

• OKcontrol (function) – specifies a function or method that will be called when the input is validated. The called function is supplied with one argument which is False if the TextCtrl contains an invalid value and True if the value is valid. Note that this function should check all values in the dialog when True, since other entries might be invalid. The default for this is None, which indicates no function should be called.

• OnLeave (function) –

  specifies a function or method that will be called when the focus for the control is lost. The called function is supplied with (at present) three keyword arguments:

  • invalid: (bool) True if the value for the TextCtrl is invalid

  • value: (int/float/str) the value contained in the TextCtrl

  • tc: (wx.TextCtrl) the TextCtrl object

  The number of keyword arguments may be increased in the future should needs arise, so it is best to code these functions with a **kwargs argument so they will continue to run without errors

  The default for OnLeave is None, which indicates no function should be called.

• typeHint (type) – the value of typeHint should be int, float or str (or None). The value for this will override the initial type taken from value for the dict/list element loc[key] if not None and thus specifies the type for input to the TextCtrl. Defaults as None, which is ignored, unless nDig is specified in which case the default is float.

• CIFinput (bool) – for str input, indicates that only printable ASCII characters may be entered into the TextCtrl. Forces output to be ASCII rather than Unicode. For float and int input, allows use of a single ‘?’ or ‘.’ character as valid input.

• OnLeaveArgs (dict) – a dict with keyword args that are passed to the OnLeave function. Defaults to {}

• ASCIIonly (bool) – if set as True will remove unicode characters from strings

• (other) – other optional keyword parameters for the wx.TextCtrl widget such as size or style may be specified.

ChangeValue(val)

Place a value into the text widget and save it into the associated array element. Note that, unlike the stock wx.TextCtrl, val is expected to be in the form expected by the widget (float/int/str) rather than only str’s. For float val values, the value is formatted when placed in the TextCtrl, but the supplied value is what is actually saved.

This routine does not trigger a wx.EVT_TEXT event. This is what should be used inside event callbacks, not SetValue().

OnKeyDown(event)

Special callback for wx 2.9+ on Mac where backspace is not processed by validator

SaveBackgroundColor(color)

Use this color when valid rather than default

SetValue(val, warn=True)

Place a value into the text widget and save it into the associated array element. Note that, unlike the stock wx.TextCtrl, val is expected to be in the form expected by the widget (float/int/str) rather than only str’s. For float val values, the value is formatted when placed in the TextCtrl, but the supplied value is what is actually saved.

This routine triggers a wx.EVT_TEXT event

ShowStringValidity(previousInvalid=True)

Check if input is valid. Anytime the input is invalid, call self.OKcontrol (if defined) because it is fast. If valid, check for any other invalid entries only when changing from invalid to valid, since that is slower.

Parameters:

previousInvalid (bool) – True if the TextCtrl contents were invalid prior to the current change.

class GSASII.GSASIIctrlGUI.VirtualVarBox(parent)

This is used to construct the parameter list display for viewing least squares parameters

OnGetItemAttr(item) → ItemAttr

This function may be overridden in the derived class for a control with wxLC_VIRTUAL style.

OnGetItemText(item, column) → str

This function must be overridden in the derived class for a control with wxLC_VIRTUAL style.

OnRowRightClick(event, row=None)

This adds or removes a variable from the list of logged paremeters.

When a row is right-clicked this seems to be called twice, once event.GetIndex() of -1, then OnRowSelected is called and then this is called again, but where event.GetIndex() is the row that was selected.

OnRowSelected(event, row=None)

Creates an edit window when a parameter is selected

GSASII.GSASIIctrlGUI.XformMatrix(panel, Trans, Uvec, Vvec, OnLeave=None, OnLeaveArgs={})

Display a transformation matrix and two vectors

GSASII.GSASIIctrlGUI.askQuestion(parent, question, title)

Simple code to ask a Y/N question and get answer

GSASII.GSASIIctrlGUI.askSaveDirectory(G2frame)

Ask the user to supply a directory name. Path name is used as the starting point for the next export path search.

Returns:

a directory name (str) or None if Cancel is pressed

GSASII.GSASIIctrlGUI.askSaveFile(G2frame, defnam, extension, longFormatName, parent=None)

Ask the user to supply a file name

Parameters:

• G2frame (wx.Frame) – The main GSAS-II window

• defnam (str) – a default file name

• extension (str) – the default file extension beginning with a ‘.’

• longFormatName (str) – a description of the type of file

• parent (wx.Frame) – the parent window for the dialog. Defaults to G2frame.

Returns:

a file name (str) or None if Cancel is pressed

GSASII.GSASIIctrlGUI.findValsInNotebook(data, target)

Pull a string of values from saved values in the GSAS-II notebook

GSASII.GSASIIctrlGUI.getTextSize(txt)

Get the size of the text string txt in points, returns (x,y)

GSASII.GSASIIctrlGUI.gitCheckUpdates(G2frame)

Used to update to the latest GSAS-II version, but checks for a variety of repository conditions that could make this process more complex. If there are uncommitted local changes, these changes must be cached or deleted first. If there are local changes that have been committed or a new branch has been created, the user (how obstensibly must know use of git) will probably need to do this manually. If GSAS-II has previously been regressed (using gitSelectVersion()), then this is noted as well.

When all is done, function GSASIIpath.gitStartUpdate() is called to actually perform the update.

GSASII.GSASIIctrlGUI.gitSelectBranch(event)

Pull in latest GSAS-II branches on origin server; Allow user to select a branch; checkout that branch and restart GSAS-II. Expected to be used by developers and by expert users only.

GSASII.GSASIIctrlGUI.gitSelectVersion(G2frame)

Used to regress to a previous GSAS-II version, checking first for a variety of repository conditions that could make this process more complex. If there are uncommitted local changes, these changes must be cached or deleted before a different version can be installed. If there are local changes that have been committed or a new branch has been created, the user (how obstensibly must know use of git) will probably need to do this manually. If GSAS-II has previously been regressed (using gitSelectVersion()), then this is noted as well.

When all is done, function GSASIIpath.gitStartUpdate() is called to actually perform the update.

GSASII.GSASIIctrlGUI.gitSwitchMaster2Main()

This is “patch” code to switch from the master branch to the main branch. At some point this will be made part of the update process in the master branch. This routine is not needed in the main branch.

Switching is a bit complicated as additional Python packages are needed and becuase the GSASII.py file gets renamed to G2.py so “shortcuts” need to be re-created to reference that.

class GSASII.GSASIIctrlGUI.gitVersionSelector(parent=None)

Dialog to allow a user to select a version of GSAS-II to install from a git repository

docCommit(commit)

Provides a string with information about a specific git commit.

Returns:

a multi-line string

getVersion()

Gets the selected version that should be installed

Returns:

returns one of three values:

• 0: if the newest version is selected, so that the installation should be updated rather than regressed

• None: if the currently installed version is selected, so that nothing need be done

• A hexsha string: the regressed version that should be selected.

class GSASII.GSASIIctrlGUI.gpxFileSelector(parent, startdir='.', multiple=False, *args, **kwargs)

Create a file selection widget for locating .gpx files as a modal dialog. Displays status information on selected files. After creating this use dlg.ShowModal() to wait for selection of a file. If dlg.ShowModal() returns wx.ID_OK, use dlg.Selection (multiple=False) to obtain the selected file or dlg.Selections (multiple=True) to obtain a list of multiple files.

Parameters:

• parent (wx.Frame) – name of panel or frame that will be the parent to the dialog. Can be None.

• startdir (path) – Specifies the initial directory that is opened when the window is initially opened. Default is ‘.’

• multiple (bool) – if True, checkboxes are used to allow selection of multiple files. Default is False

DirSelected(event=None, *args, **kwargs)

Respond to a directory being selected. List files found in fileBox and clear any selections. Also clear any reference to a timer.

FileSelected(event)

Respond to a file being selected (or checked in multiple mode)

displayGPXrtc(result, fwp)

Show info about selected file in a RichText display

GSASII.GSASIIctrlGUI.haveGUI()

Test if there is a GUI that can be accessed :returns: True if a GUI is available

GSASII.GSASIIctrlGUI.helpLocDict = {}

This is an index to the HTML anchors defined in the GSAS-II help files

GSASII.GSASIIctrlGUI.makeContourSliders(G2frame, Ymax, PlotPatterns, newPlot, plottype)

Create a non-modal dialog for sliders to set contour plot intensity thresholds.

GSASII.GSASIIctrlGUI.patch_condarc()

Comment out any references to “file:” locations in the .condarc file. These should not be there and cause problems.

class GSASII.GSASIIctrlGUI.popupSelectorButton(parent, lbl, choices=None, selected=None, choiceDict=None, OnChange=None, **kw)

Create a button that will invoke a menu with choices that can be selected. Do special stuff if the first item is “all”

TODO: It might be better to make this a wx.ComboCtrl if I can figure out how to make that work, or perhaps make that an option

Parameters:

• parent (wx.Frame) – a panel or frame that is the parent to this button

• lbl (str) – a label for the button

• choices (list) – a list of str’s with labels for the items in the menu

• selected (list) – a list of bool’s that determine if the menu item is initial selected

• OnChange (function) – an optional function that is called after the menu is removed

• others – other keyword parameters are allowed. They will be passed to the OnChange routine.

Param:

dict choiceDict: a dict with both choices and their values (selections). Use this or choices & selected, not both. If this is used, the values are set as radiobutton choices, only the most recent setting is selected.

popupSelector(event)

Show the menu and then get current values. Optionally call the OnChange routine.

GSASII.GSASIIctrlGUI.setColorButton(parent, array, key, callback=None, callbackArgs=[])

Define a button for setting colors This bypasses the bug in wx4.1.x in ColourSelect

GSASII.GSASIIctrlGUI.showUniqueCell(frame, cellSizer, row, cell, SGData=None, editAllowed=False, OnCellChange=None)

function to put cell values into a GridBagSizer. First column (#0) is reserved for labels etc. if editAllowed is True, values are placed in a wx.TextCtrl and if needed two rows are used in the table.

GSASII.GSASIIctrlGUI.skimGPX(fl)

pull out fit information from a .gpx file quickly

Returns:

dict with status info

GSASII.GSASIIctrlGUI.updateNoticeDict = {4919: True}

A dict with versions that should be noted. The value associated with the tag is if all older projects should show the warning, or only the first to be opened.

GSASII.GSASIIctrlGUI.updateNotifier(G2frame, fileVersion)

Posts an update notice when a a specially tagged GSAS-II version is seen for the first time. Versions to be tagged are set in global updateNoticeDict; version info is found in file versioninfo.txt.

Parameters:

• G2frame (wx.Frame) – GSAS-II main window

• fileVersion (int) – version of GSAS-II used to create the current .gpx file

GSASII.GSASIIctrlGUI.viewWebPage(parent, URL='', size=(750, 450), newFrame=False, HTML='')

Creates a child wx.Frame with an OS-managed web browser. The window is modeless, so it can be left open without affecting GSAS-II operations, but will be closed when GSAS-II is ended if a parent window is specified.

The web browser is filled with a supplied URL or HTML text. Reuses the previous window unless newFrame is set to True.

Parameters:

• parent (wx.Frame) – name of main GSAS-II window (G2frame), if None a toplevel window is created (probably not a good idea).

• URL (str) – web page to be viewed. This is ignored if HTML (below) is specified, but argument URL is not optional.

• size (wx.Size) – initial size of Frame to be created. Defaults to (750,450).

• newFrame (bool) – When True, a new frame is opened even if the previously-used frame exists. Default is False.

• HTML (str) – HTML text of a web page to be displayed. If this is specified, the contents of the URL argument is ignored.

Returns:

the wx.Frame object used to display the web page

7.2. GSASIImiscGUI: Misc I/O routines

Module with miscellaneous routines for input and output. Many are GUI routines to interact with user.

Includes support for image reading.

7.2.1. GSASIImiscGUI Classes & Routines

Misc routines for GUI-based input and output, including image reading follow.

This module contains quite a bit of older code that could use some attention, or possibly movement into other modules. It was previously called GSASIIIO.py which is why most modules reference it as G2IO.

GSASII.GSASIImiscGUI.ExportPowder(G2frame, TreeName, fileroot, extension, hint='')

Writes a single powder histogram using the Export routines. This is used in GSASIIimgGUI.AutoIntFrame() only.

Parameters:

• G2frame (wx.Frame) – the GSAS-II main data tree window

• TreeName (str) – the name of the histogram (PWDR …) in the data tree

• fileroot (str) – name for file to be written, extension ignored

• extension (str) – extension for file to be written (start with ‘.’). Must match a powder export routine that has a Writer object.

• hint (str) – a string that must match the export’s format

GSASII.GSASIImiscGUI.ExportPowderList(G2frame)

Returns a list of extensions supported by ExportPowder() along with their descriptions (note that a extension may be repeated but descriptions are unique). This is used in GSASIIimgGUI.AutoIntFrame() only.

Parameters:

G2frame (wx.Frame) – the GSAS-II main data tree window

GSASII.GSASIImiscGUI.ExportSequential(G2frame, data, obj, exporttype)

Used to export from every phase/dataset in a sequential refinement using a .Writer method for either projects or phases. Prompts to select histograms and for phase exports, which phase(s).

Parameters:

• G2frame (wx.Frame) – the GSAS-II main data tree window

• data (dict) – the sequential refinement data object

• obj (exporter) – an exporter object

• exporttype (str) – indicates the type of export (‘project’ or ‘phase’)

GSASII.GSASIImiscGUI.ExportSequentialFullCIF(G2frame, seqData, Controls)

Handles access to CIF exporter a bit differently for sequential fits, as this is not accessed via the usual export menus

GSASII.GSASIImiscGUI.FileDlgFixExt(dlg, file)

this is needed to fix a problem in linux wx.FileDialog

GSASII.GSASIImiscGUI.GetCheckImageFile(G2frame, treeId)

Try to locate an image file if the project and image have been moved together. If the image file cannot be found, request the location from the user.

Parameters:

• G2frame (wx.Frame) – main GSAS-II Frame and data object

• treeId (wx.Id) – Id for the main tree item for the image

Returns:

Npix,imagefile,imagetag with (Npix) number of pixels, imagefile, if it exists, or the name of a file that does exist or False if the user presses Cancel and (imagetag) an optional image number

GSASII.GSASIImiscGUI.GetPowderPeaks(fileName)

Read powder peaks from a file

GSASII.GSASIImiscGUI.IndexPeakListSave(G2frame, peaks)

Save powder peaks from the indexing list

GSASII.GSASIImiscGUI.LoadImage2Tree(imagefile, G2frame, Comments, Data, Npix, Image)

Load an image into the tree. Saves the location of the image, as well as the ImageTag (where there is more than one image in the file), if defined.

GSASII.GSASIImiscGUI.LogCellChanges(G2frame)

Log varied cell parameters into the data tree notebook

GSASII.GSASIImiscGUI.PeakListSave(G2frame, file, peaks)

Save powder peaks to a data file

GSASII.GSASIImiscGUI.ProjFileOpen(G2frame, showProvenance=True)

Read a GSAS-II project file and load into the G2 data tree

GSASII.GSASIImiscGUI.ProjFileSave(G2frame)

Save a GSAS-II project file

GSASII.GSASIImiscGUI.PutG2Image(filename, Comments, Data, Npix, image)

Write an image as a python pickle - might be better as an .edf file?

GSASII.GSASIImiscGUI.ReadImages(G2frame, imagefile)

Read one or more images from a file and put them into the Tree using image importers. Called only in AutoIntFrame.OnTimerLoop().

ToDo: Images are most commonly read in GSASIIdataGUI.GSASII.OnImportGeneric() which is called from GSASIIdataGUI.GSASII.OnImportImage() it would be good if these routines used a common code core so that changes need to be made in only one place.

Parameters:

• G2frame (wx.Frame) – main GSAS-II Frame and data object.

• imagefile (str) – name of image file

Returns:

a list of the id’s of the IMG tree items created

GSASII.GSASIImiscGUI.SaveIntegration(G2frame, PickId, data, Overwrite=False)

Save image integration results as powder pattern(s)

GSASII.GSASIImiscGUI.XYsave(G2frame, XY, labelX='X', labelY='Y', names=[])

Save XY table data

GSASII.GSASIImiscGUI.mkParmDictfromTree(G2frame, sigDict=None)

Load the GSAS-II refinable parameters from the tree into dict parmDict Updating refined values to those from the last cycle. Optionally compute the s.u. values for the parameters and place them in sigDict.

The actions in the routine are used in a number of places around the GSAS-II code where it would be “cleaner” to use this instead. Perhaps that will happen as code revisions are made. One example of this, GSASIIfiles.ExportBaseclass.loadParmDict().

Parameters:

• G2frame (wx.Frame) – a reference to the main GSAS-II window

• sigDict (dict) – a Python dict with sigma (s.u.) values for each parameter

Returns:

parmDict, a dict with the value for all refined and most unrefined GSAS-II parameters used in the diffraction computations. This parmDict version has only values, as opposed to the version used in some parts of the code that has refinement flags and initial values as well.

GSASII.GSASIImiscGUI.objectScan(data, tag, indexStack=[])

Recursively scan an object looking for unexpected data types. This is used in debug mode to scan .gpx files for objects we did not intend to be there.

GSASII.GSASIImiscGUI.saveNewPhase(G2frame, phData, newData, phlbl, msgs, orgFilName)

create a .gpx file from a structure from the BilbaoSite pseudosym site saved in newData

7.3. gltext: draw OpenGL text

Routines that render text on OpenGL without use of GLUT.

Code written by Christian Brugger & Stefan Hacker and distributed under GNU General Public License.

class gltext.Text(text='Text', font=None, font_size=8, foreground=wx.Colour(-1, -1, -1, 255), centered=False)

A simple class for using System Fonts to display text in an OpenGL scene. The Text adds a global Cache of already created text elements to TextElement’s base functionality so you can save some memory and increase speed

property centered

Display the text centered

draw_text(position=wx.RealPoint(0.0, 0.0), scale=1.0, rotation=0)

position (wx.RealPoint) - x/y Position to draw in scene scale (float) - Scale rotation (int) - Rotation in degree

Draws the text to the scene

property font

Font of the object

property font_size

Font size

property foreground

Color/Overlay bitmap of the text

getTextElement()

Returns the text element bound to the Text class

getTexture()

Returns the texture of the bound TextElement

getTexture_size()

Returns a texture size tuple

setCentered(value, reinit=True)

value (bool) - New centered value reinit (bool) - Create a new texture

Sets a new value for ‘centered’

setFont(value, reinit=True)

value (bool) - New Font reinit (bool) - Create a new texture

Sets a new font

setFont_size(value, reinit=True)

value (bool) - New font size reinit (bool) - Create a new texture

Sets a new font size

setForeground(value, reinit=True)

value (bool) - New centered value reinit (bool) - Create a new texture

Sets a new value for ‘centered’

setText(value, reinit=True)

value (bool) - New Text reinit (bool) - Create a new texture

Sets a new text

property text

Text of the object

property text_element

TextElement bound to this class

property texture

Texture of bound TextElement

property texture_size

Size of the used texture

class gltext.TextElement(text='', font=None, foreground=wx.Colour(-1, -1, -1, 255), centered=False)

A simple class for using system Fonts to display text in an OpenGL scene

bind()

Increase refcount

property centered

Is text centered

createTexture()

Creates a texture from the settings saved in TextElement, to be able to use normal system fonts conviently a wx.MemoryDC is used to draw on a wx.Bitmap. As wxwidgets device contexts don’t support alpha at all it is necessary to apply a little hack to preserve antialiasing without sticking to a fixed background color:

We draw the bmp in b/w mode so we can use its data as a alpha channel for a solid color bitmap which after GL_ALPHA_TEST and GL_BLEND will show a nicely antialiased text on any surface.

To access the raw pixel data the bmp gets converted to a wx.Image. Now we just have to merge our foreground color with the alpha data we just created and push it all into a OpenGL texture and we are DONE inhalesdelpy

DRAWBACK of the whole conversion thing is a really long time for creating the texture. If you see any optimizations that could save time PLEASE CREATE A PATCH!!!

deleteTexture()

Deletes the OpenGL texture object

draw_text(position=wx.RealPoint(0.0, 0.0), scale=1.0, rotation=0)

position (wx.RealPoint) - x/y Position to draw in scene scale (float) - Scale rotation (int) - Rotation in degree

Draws the text to the scene

property font

Font of the object

property foreground

Color of the text

isBound()

Return refcount

property owner_cnt

Owner count

release()

Decrease refcount

property text

Text of the object

property texture

Used texture

property texture_size

Size of the used texture