CONTROL DIALOG - A layer for simplified Tkinter dialogs

A Simple Example

from control_dialog import *

def test_press():
  print "button pressed"

def test_callback(dialog):
  print "Test callback:",dialog.variables
  print "Radio value:",dialog.getValue("Test radio")

def main():

  root = Tk()
  int_val = 1
  float_val = 2.34574563
  min_val = 1.3
  max_val = 3.4
  bool_val = True
  str_val = "Hello"
  selector_options = ("Aust","B","C")
  selector_val = "B"
  list_val = [False,True,True]
  radio_val = 0
  var_list = (("Just some text>>>",),
              ("Test button",None,test_press),
              ("Test Float:",float_val,None,max_val,min_val,3),
              ("Test Bool:",bool_val),
              ("Test String:",str_val),
              (("Test selector box+-",)+selector_options,selector_val),
              (("Test list>>>","Sydney","Melbourne","Adelaide"),list_val,2,1),
              (("Test radio","One","Two","3"),radio_val),
              ("Test Int:",int_val))
  status_line = "This is the status line"
  dialog = ControlDialog(root,var_list,"Control Dialog Test",test_callback,status_line,False)
  dialog.update()
  dialog.lift()
  frame = 0
  while not dialog.exit_request:
    dialog.update()
    sys.stdout.flush()
    dialog.setStatusLine('%10d' % frame)
    frame += 1
  dialog.destroy()  # don't need to do this here but it is good practice

if __name__ == '__main__': main()

Running this code creates a blank parent window plus the following dialog:

This instructions to create the dialog are contained in var_list. Each entry describes a different field to place in the dialog:

("Just some text>>>",)

= Some text, such as an instruction,

("Test button",None,test_press)

= A button with callback test_press()

("Test Float:",float_val,None,max_val,min_val,3)

= A text field for entering a floating point value initially set to float_val and which must be between max_val and min_val. Only 3 decimal points to be shown.

("Test Bool:",bool_val)

= A check button set initially to bool_val'

("Test String:",str_val)

= A simple text field initially set to str_val,

(("Test selector box+-",)+selector_options,selector_val)

= A selector box - more on this latter.

("Test list>>>","Sydney","Melbourne","Adelaide"),list_val)

= A list box initially set using an array of boolean values.

(("Test radio","One","Two","3"),radio_val)

= A radio panel initially set by radio_val

("Test Int:",int_val)

= A text field for entry of an integer value.

Additional information is supplied to the dialog with the constructor call:

Here the parent, var_list, title, apply_callback and status line are added. In the above example the status line is changed regularly to the current frame with:dialog.setStatusLine('%10d' % frame)

An apply callback is used when the APPLY button is pressed to access the values set. Alternatively a callback can be supplied to each of the controls as was necessary with the Test button.

A More Complex Example

In this example a callback function has been supplied for each of the fields so that the dialog may have an immediate effect.

def main():

  def test_press():
    print "button pressed"

  class test_class:
    def __init__(self):
      pass

  def test_press2(value,parent,stage=0):
    print "button pressed:",value,parent,stage
    return False # possibly required for stage 1 validation

  # value callbacks - may be called immediatly on change (stage = 0), at validation (state = 1) or
  # if and only if a change occured from the orininal value at apply stage (return key or apply button)

  def int_fn(name="",value = None, stage = 0):
    if stage == 1:
      return False
    print "int is ", value," at stage:", stage

  def bool_fn(name="",value = None, stage = 0):
    print "bool is ", value, " at stage:",stage

  def selector_fn(name="",value = None, stage = 0):
    if stage == 1:
      return False
    print "selector is ", value," at stage:", stage

  def list_fn(name="",value = None, stage = 0):
    if stage == 1:
      return False
    print "list is ", value," at stage:", stage

  def radio_fn(name="",value = None, stage = 0):
    if stage == 1:
      return False
    print "radio is ", value," at stage:", stage

  import sys

  root = Tk()
  int_val = 1
  float_val = 2.34574563
  min_val = 1.3
  max_val = 3.4
  bool_val = True
  str_val = "Hello"
  selector_options = ("Aust","B","C")
  selector_val = "B"
  list_val = [False,True,True]
  radio_val = 0
  class_instance = test_class()
  var_list = (("Just some text>>>",),
              ("Test button",None,test_press),
              ("Test button2",class_instance,test_press2),
              ("Test Float:",float_val,None,max_val,min_val,3),
              ("Test Bool:",bool_val,bool_fn),
              ("Test String:",str_val),
              (("Test selector box+-",)+selector_options,selector_val,selector_fn),
              (("Test list>>>","Sydney","Melbourne","Adelaide"),list_val,list_fn),
              (("Test radio","One","Two","3"),radio_val,radio_fn),
              ("Test Int:",int_val,int_fn))
  status_line = "This is the status line"
  dialog = ControlDialog(root,var_list,"Control Dialog Test",test_callback,status_line,False)
  #app.mainloop()
  frame = 0
  while not dialog.exit_request:
    dialog.update()
    dialog.lift()
    sys.stdout.flush()
    dialog.setStatusLine('%10d' % frame)
    frame += 1
  dialog.destroy()  # don't need to do this here but it is good practice

if __name__ == '__main__': main()

In this example callbacks have been provided for most of the fields so that changes to the dialog fields can have an immediate effect.

Variable List Protocol

The variable list can be a list or tuple of the following elements:

   ( label,              # must be unique or list/tuple
     intial value,       # determines field type
     callback_function,
     maximum_value,
     minimum_value,
     float_precision     # how many decimals to display
   )

Notes on label:

1. If this is the only item then the label is just static text.
2. If label does not end with >>> then the next field is on a new line.
3. If label ends with +- (before the >>>) then the left and right buttons on the mouse may have increment and decrement functionality
4. If the label is list or tuple then it contains the options for a radio button fields, a list box or a selector box. The first value of a list or tuple is the label for the control.
5. If label is a list or tuple and the +- suffix is found in the first value then the result is a selector box. The left and right mouse buttons are used to select a value.

Notes on initial_value:

1. If the initial value == None then the control is a button and a callback is required.
2. If ,, ,, ,, == bool ,, ,, ,, ,, a check box
3. If ,, ,, ,, == int ,, ,, ,, ,, a text field or radio panel or selectorbox
4. If ,, ,, ,, == float ,, ,, ,, ,, a text field
5. If ,, ,, ,, == string ,, ,, ,, ,, a text field or radio panel or selectorbox
6. If ,, ,, ,, == list of bool ,, ,, ,, ,, a list box
7. For radio panels and selector boxes, the initial value can be one of the options.

Notes on callback:

1. Except for button callbacks, the callback function must generally take 3 arguments: callback(value,parent,stage=0) where value is the new value, parent is the dialog sending the call and stage is 0 on change, 1 for validation and 2 for apply.
2. Button callbacks take no arguments.

Notes on max and min values:

1. These values are optional and may be replaced with None.

Notes on float precision:

1. This value only applies to float fields, is optional and must be an integer.

Application Program Interface

Apart from the control dialog class constructor there are three useful functions:

1. getValue(label) returns the current value of the field referenced by the label it was given.
2. set(label,value) sets the field using the label reference. Instead of using the label, an integer may be used to reference the field by it's position in the variable list.
3. setBy(fields) sets a number or all of the fields using a tuple or list containing tuple or list pairs of values to be used in the set function. Clever people might prefer to use the python map function to do the same thing.

The only way to access variables set through the control_dialog is through callbacks, either by the values passed by individual callbacks or by using the dialog.getValue(label) method.

Field Validation

When Enter is pressed on a text field or the APPLY button is clicked, then a validation function is applied to check that all the values are within limits.

• For integer and float types with maximum and/or minimum values this is obvious enough.
• For float types with a significant figure entry, entries are first reduced to this value.
• For selector boxes and radio types it checks that the current value is one of those given in the label list.
• For list boxes, the maximum and/or minimum values indicate the number of selections to select.

If one or more entries are found to be invalid they are highlighted in red and a message box appears listing the offenders and their crimes.

Installation