Buttons.py

Run a button from the right-hand bar, and add your own. You provide a function and some info, and this module takes care of the button and the settings dialog box.

Run( category, name, settings=None )

category      e.g. 'Modeling'
name      the button's caption e.g. 'MIL Rates' or 'MIL'
settings      qubtree.Node such as returned by GetSettings()
optionally override the settings from the dialog box

Simulates a click on one of the buttons.

GetSettings( category, name )

category      e.g. 'Modeling'
name      the button's caption e.g. 'MIL Rates' or 'MIL'
returns      qubtree.Node

Gets the names and values of settings in a button's dialog box.
Useful to find out setting names in preparation for Run().

AddTaskButton( name, func, shortName, dlogOnLClick, dlogOnRClick, hint, description, propertiesCaption, properties, category="Scripts", DataChannel=False, DataList=False, FileList=False, Process=False, Threads=False )

name      the button's caption
func      a function(propertiesDict) to run when the button is clicked.
shortName      the button's caption when showing small buttons (5 letters max)
dlogOnLClick      whether to show a settings dialog when the button is left-clicked
dlogOnRClick      whether to show a settings dialog when the button is right-clicked
hint      a tool-tip for the button
description      an extended description for the "Edit Buttons" window
propertiesCaption      some text for the top of the settings dialog
properties      a list of settings, either ChoiceField and TextField (below), or e.g. DialogText from Dialogs.
category      which group of buttons to add to, default "Scripts"
DataChannel      whether to show "Data Channel" at the top-left of the properties dialog
DataList      whether to show the data file list in the properties dialog
FileList      if the data list is visible, whether to include "file list" as an option
Process      whether to show the "process data" panel in the properties dialog
Threads      whether to show the "threads" panel in the properties dialog

Adds a button to the "Scripts" category in the right-hand button bar. When clicked, it will put up a dialog box to edit the settings, then run your function.

Your function should have one argument: a dictionary mapping setting-name to setting-value. See ChoiceField and TextField for how to specify settings and defaults.

class ChoiceField( name, caption, choices, default )

name      the name you'll use to look up the setting's value in your function (not visible to the user)
caption      the text displayed in the settings dialog
choices      a list of strings for the user to choose from.
default      the string which is chosen initially (should be in choices as well)

Creates a choice field for use in AddTaskButton's properties list. The user is allowed to choose one of a list of strings.

class TextField( name, caption, default, acceptor )

name      the name you'll use to look up the setting's value in your function (not visible to the user)
caption      the text displayed in the settings dialog
default      initial value, as a string
acceptor      a function which converts a string from the settings dialog into the desired type, or raises an exception if it is invalid or out of bounds.

Creates a text field (free-response) for use in AddTaskButton's properties list.

You can use a predefined acceptor function (in Buttons.py) or specify your own. It must take a string as argument, and return whatever kind of value you expect. acceptString is simply the identity function -- no conversion required. If the conversion is impossible, or the value is e.g. out of bounds, the acceptor should raise an exception with an informative message.


Examples

# The button's function takes one argument: a dictionary of named settings.
# This example merely prints all its settings.

def TestReport(settings):
    for setname in settings.keys():
        QUB.Report( setname + ': ' + str(settings[setname]) )
    QUB.Report("-------------------------")

test = AddTaskButton( 'TestReport', # button text
                      TestReport,   # function
                      'TRpt',       # short text for small buttons
                      0,            # show settings dialog on left-click?
                      1,            # show settings dialog on right-click?
                      "Test Buttons.AddTaskButton",   # tool-tip
                      "See PythonScripts/Buttons.py", # description for the "Edit Buttons" dialog
                      "Please mess with these settings:", # caption for the settings dialog

# the last arg. is a list of settings.
# Settings have a name such as "abc" which is used for look-up in the function,
# and a caption such as "Pick one:" for display in the settings dialog.
# They can be either a ChoiceField (pick one of these strings) (in the example, 'b' is given as the default),
# or a TextField -- free response.
# The optional 4th argument to the TextField constructor is an "acceptor":
# a function which converts a string to whatever type your function expects,
# or throws an exception to reject the new setting.
# The default acceptor performs no conversions (it stays as a string).
                      
               [ChoiceField("abc", "Pick one:", ['a', 'b', 'c'], 'b'),
                TextField("anything", "No limits:", ""),
                TextField("number", "Any number:", "0", acceptFloat),
                TextField("int", "Any integer:", "0", acceptInt),
                TextField("bounded", "Float between 0 and 1:", "0", acceptFloatBetween(0, 1)),
                TextField("boundedInt", "Int between 0 and 9:", "0", acceptIntBetween(0, 9)),
                TextField("positive", "Positive int:", "1", acceptIntGreaterThan(0)),
                TextField("negative", "Negative int:", "-1", acceptIntLessThan(0))] )


# Here's a smaller example that also shows how to put up your own dialogs:
def Greet(props):
    answer = QUB.Dialog(props['greeting'],                               # dialog caption
                        ['Good', 'OK', 'Bad'],                           # buttons
                        [Dialogs.DialogText('Comments', 'Comments:')] )  # list of fields
    QUB.Report( answer['button'] + ': ' + answer['Comments'] )

AddTaskButton( 'Greet', Greet, 'Hi', 0, 1,
               "Interact with the machine on a more human level",
               "A simple example of how to add your own buttons via python.\nSee PythonScripts/Greet.py", "Customize the message:",
               [TextField("greeting", "The greeting:", "Hello.  How are you today?", acceptString)] )