User Input

This example shows how to add a few input widgets to a script and how to get data from them. This is a fairly artificial example in that one would normally just use the DIS Expose window for this purpose. However, it demonstrates a few useful techniques, including:

• How to handle a d:m:s time widget with "live" units display
• How to get data from a widget
• Some techniques for laying out widgets
• How to specify help that shows up in the status bar

DISDarks v2 script

Be sure you have permission to use DIS before running this example!!!

import RO.Wdg
import Tkinter
import TUI.Inst.ExposeModel as ExposeModel
from TUI.Inst.ExposeStatusWdg import ExposeStatusWdg

class ScriptClass(object):
    """Take a series of DIS darks with user input.
    """
    def __init__(self, sr):
        """Display exposure status and a few user input widgets.
        """
        # if True, run in debug-only mode (which doesn't DO anything, it just pretends)
        sr.debug = False

        expStatusWdg = ExposeStatusWdg(
            master = sr.master,
            instName = "DIS",
        )
        expStatusWdg.grid(row=0, column=0, sticky="w")
        
        wdgFrame = Tkinter.Frame(sr.master)
     
        gr = RO.Wdg.Gridder(wdgFrame)
        
        self.expModel = ExposeModel.getModel("DIS")
    
        timeUnitsVar = Tkinter.StringVar()
        self.timeWdg = RO.Wdg.DMSEntry (
            master = wdgFrame,
            minValue = self.expModel.instInfo.minExpTime,
            maxValue = self.expModel.instInfo.maxExpTime,
            isRelative = True,
            isHours = True,
            unitsVar = timeUnitsVar,
            width = 10,
            helpText = "Exposure time",
        )
        gr.gridWdg("Time", self.timeWdg, timeUnitsVar)
        
        self.numExpWdg = RO.Wdg.IntEntry(
            master = wdgFrame,
            defValue = 1,
            minValue = 1,
            maxValue = 999,
            helpText = "Number of exposures in the sequence",
        )
        gr.gridWdg("#Exp", self.numExpWdg)
        
        wdgFrame.grid(row=1, column=0, sticky="w")
        
    def run(self, sr):
        """Take a series of DIS darks"""
        expType = "dark"
        expTime = self.timeWdg.getNum()
        numExp = self.numExpWdg.getNum()
    
        fileName = "dis_" + expType
        
        if expTime <= 0:
            raise sr.ScriptError("Specify exposure time")
    
        cmdStr = self.expModel.formatExpCmd(
            expType = expType,
            expTime = expTime,
            fileName = fileName,
            numExp = numExp,
        )
    
        yield sr.waitCmd(
            actor = "disExpose",
            cmdStr = cmdStr,
            abortCmdStr = "abort",
        )

Comments:

• This is a slightly awkward set of widgets to lay out. There is a large status widget above, with a few small input widgets below. I have chosen to create a new frame wdgFrame to hold the input widgets. This frame is used as the master widget for the input widgets. The input widgets are gridded into the widget frame and the widget frame is gridded into sr.master. Using a hierarchy of widgets like this does have a few pitfalls:
  • It is easy to forget which parent to use, which can lead to a very confusing display or worse (see the next item).
  • You must never try to grid and pack widgets into the same master. This leads to an infinite loop. In fact if your script freezes while loading, that is the first thing to look for.
  • The previous two points together lead me to recommend that you stick to using the gridder and avoid the packer.
• gr = RO.Wdg.Gridder(wdgFrame) creates a "gridder" for the widget frame. Gridders specialize in laying out rows of input and status widgets, saving you some of the headache of using Tk's raw gridder or packer.
• The widgets are passed from __init__ to run via self.
• raise sr.ScriptError(...) will report an error to the status bar and halt your script. You can raise any other exception if you prefer, but then you will log the error message and a traceback to the error log (which is excellent for debugging unexpected errors but intrusive for reporting "normal" errors).
• The script window will expand as needed to show your widgets. However, the script window is never resizable (though a future version may offer resizability as an option if it is strongly requested).
• RO.Wdg offers various versions of standard tk widgets including DMSEntry and IntEntry (both used in this script). These offer many advantages over a simple Entry widget including: numerical entry (with input verification and limits) and help text that automatically shows up in the status bar,

Advanced Topic

It is actually possible to create a gridder on sr.master and use it to lay out the status widget and the input widgets. I present the code without comment for folks who understand the Tk gridder and are willing to read the help for RO.Wdg.Gridder.

    gr = RO.Wdg.Gridder(sr.master)
    
    expStatusWdg = ExposeStatusWdg(
        master = sr.master,
        instName = "DIS",
    )
    gr.gridWdg(False, expStatusWdg, colSpan=4)
    sr.master.grid_columnconfigure(3, weight=1)
    ...
    gr.gridWdg("Time", timeWdg, timeUnitsVar)
    ...
    gr.gridWdg("#Exp", numExpWdg)