________________________________________________

OVERVIEW OF THE CUSTOMIZED WIDGETS
________________________________________________


All the customized widgets should have :

  1. The ListChooser:

    2. Class to present a list of objects in a scrolled listbox. The entries are given as a list of items associated (items, description) or not (items, None) with a description. Double clicking on the entry will displayed the description in a Pmw.ScrolledText widget.

    - Options:
    The widget configuration dictionary (wcfg) of a Listchooser can contain the following options.
    entries: List of tuple (items,comment) or (items,None) to be added to the listchooser.
    lbwcfg: Listbox widget configuration dictionary, contains the listbox options
    lbpackcfg: dictionary describing the way to pack the listbox, using the pack geometry manager
    mode: Mode of selection in the listchooser ('single','browse', 'multiple' or 'extended').
    title: Title of the ListChooser.
    withComment: specifies if comments associated to the entries default=0
    command: specifies a callback function
    commandEvent: specifies th eevnt to invoke the callback function default is ""
    cwcfg Comments widget configuration dictionary, containing the Pmw.ScrolledText options.

    - Methods:
    add(self, entry, comment=None)
    Add an item associated or not with a comment to the existing item list.
    clear(self)
    Clear all the items
    clearComments(self)
    Clear all comments if existing.
    info(self, event=None)
    Display information about the current selection.
    insert(self,pos, entry, comment=None)
    Insert an item associated or not with a comment at a given position to the existing item list.
    remove(self,entry)
    Remove an item from the item list.
    select(self,first,last=None)
    Add items to the current selection

    - Examples:
    1) Here is an example of en InputFormDescr dictionary describing a ListChooser with comments associated with its items. 
    
     >>>import Tkinter
     >>>from ViewerFramework.gui import InputFormDescr
     >>>from ViewerFramework.customizedWidgets import ListChooser
     >>>idf = InputFormDescr(title = 'ListChooser')
     
     >>>#items with associated comments
     >>>itemswithcomments=[('Charles','San Diego'),('Erik','San Francisco'),
	                   ('Robert','New York'), ('Paul', 'Chicago')]

     >>>#listbox widget description
     >>>listboxwcfg = {'width':10,'height':5}
     
     >>># scrolledtext for the comments description.
     >>>commentwcfg = {'labelpos':'n',
		       'label_text': 'comments',
                       'borderframe': 2,
                       'usehullsize':1,
                       'hull_width':100,
                       'hull_height':80,
                       'text_wrap':'none'}

     >>>idf.append({'widgetType':ListChooser,'name':'lc1',
                    'wcfg':{'title':'With Comments',
		            'entries':itemswithcomments,
			    'mode':'single',
			    'lbwcfg':listboxwcfg,
			    'cwcfg':commentwcfg },
		    'gridcfg':{'sticky':'w'}})

      >>>val = self.vf.getUserInput(idf)
    2) Here is an example of an InputFormDescr dictionary describing a ListChooser with Items only.
    
     >>>itemsonly=[('Charles',None),('Erik',None),('Robert',None), 
                   ('Paul',None)] 
     
     >>>#listbox widget description.
     >>>listboxwcfg = {'width':10,'height':5}   

     >>>idf.append({'widgetType':'ListChooser','name':'lc2',
                    'wcfg':{'title':'Without Comments',
		            'entries':itemsonly,
			    'mode':'multiple',
		            'lbwcfg':listboxwcfg,
		    'gridcfg':{'sticky':'w', 'row':-1}})

  2. The SaveButton and LoadButton Widgets:

    3. The SaveButton and LoadButton widgets are Tkinter widget bound to a callback function opening a FileBrowser to save or load a file.

    - Options: br> The widget configuration dictionary (wcfg) of these widgets can contain the following options.

    buttonType Type of button (Tkinter Class).
    default = Tkinter.Button
    callback Callback function taking the filename as an argument.
    default = None
    idir default = None
    ifile default = None
    title Title of the file browser.
    default = "Save File" or "Load File"
    types Type of the file you want to see in the file browser.
    default = [('All types','*.py')]
    widgetwcfg widget configuration dictionary of the buttonType.
    default = {'text':'Save'} or {'text':'Load'}

    - Example:
    Here is an example of an InputFormDescr dictionary describing a SaveButton or a LoadButton widget.
    
	>>>from ViewerFramework.gui import InputFormDescr
	>>>from ViewerFramework.customizedWidgets import SaveButton
	>>>idf = InputFormDescr(title = 'SaveButton')

	>>>#button  description
	>>>buttonwcfg = {'text':'Save', 'bg':'Red',
                         'fg':'Black','borderwidth':5}

        >>>idf.append({'widgetType':SaveButton,
		       'name':'save',
                       'wcfg':{'buttonType':Tkinter.Button,
                               'title':'Save In File ...',
                               'types':[('All Files','*.*'),
			                ('Python Files','*.py')],
			       'widgetwcfg':buttonwcfg},
		       'gridcfg':{} })
        >>>val = self.vf.getUserInput(idf)

  3. The LoadOrSaveText Widget:

    4. The LoadOrSaveText Widget is composed of a Pmw.ScrolledText widget and two Tkinter.Button widgets.
    The Load Button opens a file browser to load a file in the text zone.
    The Save Button opens a file browser to save the text of the text zone in a file.

    - Options:
    The widget configuration dictionary (wcfg) of the ScrolledText widget can contain the following options.

    loadwcfg, savewcfg Tkinter.Button widget configuration dictionary for the Load and Save Button appearances.
    default = {}
    textpackcfg pack configuration dictionary to pack the scrolledtext.
    default = {}
    textwcfg: Pmw.ScrolledText widget configuration dictionary.
    default = {'usehullsize':1,'hull_width':400, 'hull_height':300,'text_wrap':'none'}

    - Example:
    Here is an example of an InputFormDescr dictionary describing a LoadOrSaveText Widget: 
    
      >>> from ViewerFramework.gui import InputFormDescr
      >>> from ViewerFramework.customizedWidgets import LoadOrSaveText
      >>> import Tkinter
      >>> idf = InputFormDescr(title = 'LoadOrSaveText Widget')
      >>># the LoadOrSaveTextWidget is composed of a ScrolledText widget, 
      >>># a SaveButton and a LoadButton widgets.
      >>># Pmw.ScrolledText widget description dictionary:
      >>>textwcfg = {'labelpos':'n',
                     'label_text': 'load or save text',
                     'borderframe': 2,
                     'usehullsize':1,
                     'hull_width':400,
                     'hull_height':300,
                     'text_padx': 10,
                     'text_pady': 10,
                     'text_wrap':'none'}
		    
      >>># customizedWidgets.SaveButton widget description:
      >>> savewcfg = {'buttonType':Tkinter.Button,
                      'widgetwcfg':{'text':'Save', 
                                    'bg':'Yellow',
                                    'fg':'Blue'}
				 
      >>># customizedWidgets.LoadButton widget description:
      >>>loadwcfg = {'buttonType':Tkinter.Button,
	             'widgetwcfg':{'text':'Load', 'bg':'Yellow',
                                   'fg':'Blue'}
                                    
      >>> idf.append({'widgetType':LoadOrSaveText,
	              'name':'text',
                      'wcfg':{ 'textwcfg':textwcfg,
                               'savewcfg':savewcfg,
                               'loadwcfg':loadwcfg}},
                      'gridcfg':{} })
      >>>val = self.vf.getUserInput(idf)

  4. The FunctionButton widget:

    5. A FunctionButton widget is a button that open:
    • a LoadOrSaveText widget to load a function from a file or to type a function and then save it in a file
    • or a Pmw.ScrolledText to type a function

    - Options:
    The widget configuration dictionary of a FunctionButton widget can contain the following options.
    buttonType Type of button (Tkinter Class).
    default = Tkinter.Checkbutton
    buttonwcfg Widget Configuration dictionary of this buttonType.
    textwcfg widget configuration dictionary of a LoadOrSaveText widget or a Pmw.ScrolledText widget.

    - Example:
    Here is an example of an InputFormDescr dictionary describing a FunctionButton widget.
    
      >>>from ViewerFramework.gui import InputFormDescr
      >>>from ViewerFramework.customizedWidgets import FunctionButton
      >>>import Tkinter
      >>>idf2 = InputFormDescr(title = 'FunctionButton')
      >>>#description of the widgets composing a FunctionButton:
      >>># The checkbutton widget description:
      >>> checkbuttonwcfg = {'text':'Load or Save' }
     
      >>>#LoadOrSaveText widget description is the idf of the previous widget:
      >>>loadorsavewcfg = idf[0]
      >>>ifd2.append({'widgetType':FunctionButton,'name':'loadorsave',
	              'wcfg':{'buttonType':Tkinter.Checkbutton,
		              'buttonwcfg':checkbuttonwcfg,
                              'textwcfg':loadorsavewcfg},
		      'gridcfg':{}})
      >>>val = self.vf.getUserInput(idf2)

  5. The SliderWidget:

    6. - Options:
    The widget configuration dictionary of a SliderWidget widget can contain the following options.
    command Command bound to the sliderwidet.
    default = None
    height height of your widget
    default = 'float'
    immediate simultaneous update or not
    default = 1
    incr increment
    default = None
    init initial value
    default = None
    label Slider's label
    default = NOne
    labelsCursorFormat Format of the label under the cursor if present.
    default = '%4.2f'
    left left margin
    default = 10
    maxval maximum value of the slider
    default = 100.0
    minval minimum value of the slider
    default = 0.0
    right right margin
    default = 10
    sliderType Type of the returned value (string)
    default = 'float'
    withValue Put a label under the cursor with its value.
    default = 1

    - Example:
    Here is an example of an InputFormDescr dictionary describing a SliderWidget.
    
       >>>from ViewerFramework.gui import InputFormDescr
       >>>from ViewerFramework.customizedWidgets import SliderWidget
       >>>import Tkinter
       >>>idf = InputFormDescr(title = 'SliderWidget')
       >>>idf.append( {'name': 'slider',
                       'widgetType':SliderWidget,
                       'wcfg':{'label': 'I am a SliderWidget',
                               'minval':4,'maxval':15, 'incr': 1, 'init':4,
                               'labelsCursorFormat':'%d', 'sliderType':'int'},
                        'gridcfg':{'columnspan':2,'sticky':'w'}})

  6. The ExtendedSliderWidget:

    7. The ExtendedSliderWidget is a Slider associated with an Entry.

    -Options:
    The widget configuration dictionary of an ExtebdeSliderWidget widget contains the options of a Slider plus the following option to describe the entry associated with it.
    entrywcfg Entry's widget configuration dictionary. The keyword 'label' is added to the Tkinter options to add a Label widget.
    entrypackcfg Dictionary containing the options to pack the entry widget.

    - Example:
    Here is an example of an InputFormDescr dictionary describing an ExtendedSliderWidget.
    
      >>>from ViewerFramework.gui import InputFormDescr
      >>>from ViewerFramework.customizedWidgets import ExtendedSlider
      >>>import Tkinter
      >>>idf = InputFormDescr(title = 'ExtendedSlider')
      >>>#Entry's widget description.
      >>>entrywcfg = {'width':3, 'bg':'Blue', 'fg':'White'}

      >>>idf.append( {'name': 'nbchords',
                      'widgetType':ExtendedSliderWidget,
                      'wcfg':{'label': 'nb. Pts Per Residue',
                              'minval':4,'maxval':15, 'incr': 1, 'init':4,
                              'labelsCursorFormat':'%d', 'sliderType':'int'},
                      'gridcfg':{'columnspan':2,'sticky':'w'} })




________________________________________________


Sophie Coon
July 2000
For suggestions or more information please contact:

   sophiec@scripps.edu