PyDVT.View (version 1.1.0, 08/11/2002)
index
/mntdirect/_bliss/users/gobbo/PyDVT/PyDVT/View.py

View.py
Generic base class for data displaying widgets

 
Modules
            
EventHandler
PyDVT
sys
types

 
Classes
            
PyDVT.GUIBinding.Binding.Container
View
Position

 
class Position
      Structure received by mouse event callbacks, containing information about
position of the event, in the several coordinate systems.
The actual data coordinates are stored in the DataCoord member,
a DataPosition object (Data module)
 
  

 
class View(PyDVT.GUIBinding.Binding.Container)
      Base class to data displaying widgets.
 
View objects are connected to a source through SetSource method. A source can
be an object (or sequence objects) of class Filter, or any other class that
implements an interface as difined in SetSource.
 
The base class manages the mouse and keyboard events (to ViewSelect
objects and the application), the popup menu, the mouse pointer,
a cursor, communication to and from linked objects (through EventHandler)
and more.
 
Graphical operations over the view can be easily implemented by subclassing
ViewSelect classes, overriding mouse/keyboard events callbacks (see
ViewSelect's doc).
 
View objects draws to a widget called Drawable, created by derived
classes, overriding CreateDrawable method. It can be retrieved by
GetDrawable().
 
This class is GUI independent, and decides for the importation of the GUI
binding package (QtBinding or TkBinding). Tkinter or Qt must be loaded
previously.
 
Extends Container class, as defined in the binding package.
The base class doesn't manage resizing - up to derived classes/drawables.
 
All internal event exchanging is done through EventHandler objects.
All the application level interface is done to avoid application to deal
with EventHandler, but it can, if it wants to.
 
Standard View derived classes define Filter objects to nicely connect to
these View derived object.
 
 
Interface:
===========================
Container derived methods (Defined in the GUI Binding):
    GetHeight
    GetWidth
    IsVisible
    Show
    SetSize
    SetPointer
 
General methods:
    __init__
    SetSource
    GetSource
    Update
    Refresh
    Invalidate    
    SetOnLine
    LockPosition
    SetCursor
    GetDrawable
    GetDrawableWidth
    GetDrawableHeight
    Save
    Destroy
 
Popup menu methods:
    GetPopupMenu
    AddMenuPopupItem
    AddMenuPopupCascade
    AddMenuSeparator
    DisableMenuItem
    EnableMenuItem
    DeleteMenuItem
    ClearMenu
 
Overridables:        
    EventButtonPress    
    EventButtonPressMotion  
    EventButtonRelease  
    EventMotion
    EventDoubleClick    
    EventKeyPress
    GetSaveFormats
 
 
Virtuals 
===========================
    CreateDrawable  
    DataChanged 
    GetPosition 
    DataCoord2ImageCoord    
    ImageCoord2DataCoord    
    Redraw  
 
 
 
Internal Events:
===========================
    Emits:
        "ButtonPressMotion"
        "ButtonRelease"
        "ButtonPress"
        "Motion"
        "KeyPress"
        "ImageChange"
        "DoubleClick"
    Receives:
        "DataChange"
        "DeleteEvent"
 
  
AddMenuPopupCascade(self, label, menu)
Inserts a new menu in the popup menu
Parameters:
Label:  label of the menu 
Menu:   menu object
AddMenuPopupItem(self, label, Command, Style='command')
Inserts a new item in the popup menu
Parameters:
Label:   label of the menu item
Command: Callback function
Style:  (Not considered in qt)
       'command' to add a command menu item
       'checkbutton' to add a checkbutton menu item (not used in QtBinding)
AddMenuSeparator(self)
Inserts a separator in the popup menu
ClearMenu(self)
Removes all items of the popup menu
CreateDrawable(self)
Virtual: Implements creation of  a Drawable object (which implements the
Drawable interface)
DataChanged(self, source=None)
Virtual: called to inform that data has changed.
If source == None all selections should be updated
Otherwise, the source object that actually changed is passed.
If a "data" not in source's GetOutput, it should
be erased from the View's drawable
For performance reasons DataChanged should be the only method
to call source's GetOutput, since this call triggers the
operations of all cascaded sources.
DataCoord2ImageCoord(self, data_coord)
Virtual: Method that transforms data coordinates object into  
image coordinates
DataCoord is a DataPosition object
Derived class must call DataCoord2SelectionCoord  from 
its DataSelection object and after transform into view coords (since
it does not know the data object itself).
DeleteMenuItem(self, index)
Deletes a menu item from the popup menu
Parameters:
index:  label or index of the menu to item be deleted
        as returned by AddMenuPopupItem or AddMenuPopupCascade
Destroy(self, source=None)
Cleanup.
As event handlers and callbacks, by keeping a reference to other
objects, avoid them to be destroyed (and freed from memory), the
Destroy method has to be explicitly called for View objects
before they get out of scope.
I had tried to use weak references in order not to need this method,
but this generated many other troubles (like impossibility to define
selections locally, difficult control of the destruction sequence,
not interceptable error mesassages...).
DisableMenuItem(self, index)
Disables a menu item in the popup menu
Parameters:
index:  label or index of the menu item to be disabled
        as returned by AddMenuPopupItem or AddMenuPopupCascade
EnableMenuItem(self, index)
Enables a menu item in the popup menu
Parameters:
index:  label or index of the menu item to be enabled
        as returned by AddMenuPopupItem or AddMenuPopupCascade
EventButtonPress(self, pos)
Virtual
Parameters:
   pos: position of the event as return by GetPosition
EventButtonPressMotion(self, pos)
Virtual
Parameters:
   pos: position of the event as return by GetPosition
EventButtonRelease(self, pos)
Virtual
Parameters:
   pos: position of the event as return by GetPosition
EventDoubleClick(self, pos)
Virtual
Parameters:
   pos: position of the event as return by GetPosition
EventKeyPress(self, key, flags)
Virtual: Keyboard event callback
Parameters:
   key: python string with key (if a caracter) or keycode as defined in
        GuiBinding.Bindings.KeyCodes
   flags: indicates state of auxiliary keys
EventMotion(self, pos)
Virtual
Parameters:
   pos: position of the event as return by GetPosition
GetDrawable(self)
Returns drawable object
GetDrawableHeight(self)
Returns height of drawable area - required by ViewSelect objects
GetDrawableWidth(self)
Returns width of drawable area - required by ViewSelect objects
GetHeight(self) from PyDVT.GUIBinding.Binding.Container
GetPopupMenu(self)
Returns popup menu: a Menu object
 
All menu functionalities can me managed directly through GetPopupMenu and
by calling Binding's Menu methos.
The below functions are provided for conveniance.
Even using them it is important to access Menu object in order to call
CheckItem/EnableItem/DisableItem and to add cascade menus.
See:
GUIBinding.Binding.Menu
GetPosition(self, event)
Virtual: Used to transform event coordinates into data coordinates (rule
known by derived classes). Must return the Position object that
will be dispatched to ViewSelect objects and to the application
GetSaveFormats(self)
Returns tuple with supported save formats
GetSource(self)
Gets view's tuple of sources
GetWidth(self) from PyDVT.GUIBinding.Binding.Container
ImageCoord2DataCoord(self, view_coord)
Virtual: Method that transforms View coordinate into a data coordinates
ViewCoordinate is a tuple (x,y)
DataCoord is DataPosition object
Derived class must transform view coords into selection coords and after
call SelectionCoord2DataCoord  from its DataSelection object (since
it does not know the data object itself).
Invalidate(self)
Sends ImageChange event to linked objects
IsVisible(self) from PyDVT.GUIBinding.Binding.Container
LockPosition(self, value)
Controls positioning of view after data change.
Parameters:
    value: If zero, view stays at the same position and zoom state in the
           case of a DataChange event. Otherwise, views returns to initial
           position. By default FlagLockPosition is set to zero.
           (FlagLockPosition shall be interpreted by derived classes)
Redraw(self)
Virtual: Derived classes must code the actual drawing overriding this method
Refresh(self)
Generates rescan of all sources and complete redraw of view.
For simple redrawing Update method should be called instead,
but for the cases where the source data is directly changed,
with no DataChange event sent (or when View object is not
on-line).
Save(self, filename, format)
Saves contents
By default call Save mathod of Drawable, but can be overridden to
have a different behaviour.
View classes shall override GetSaveFormats to return supported formats.
Parameters:
    filename: string, name of the output file
    format: string
SetCursor(self, cursor)
Changes the type of cursor.
A cursor is a ViewSelect object that reacts to mouse and draws itself on the view.
A tipical example is crosshairs.
There's no standarized names for cursors (up to derived classes)
Parameters:
    cursor: ViewSelect object
SetOnLine(self, value)
Controls reponse to DataChange event.
Parameters:
    value:If zero, view does not answer Data change events
SetPointer(self, pointer) from PyDVT.GUIBinding.Binding.Container
SetSize(self, width, height) from PyDVT.GUIBinding.Binding.Container
SetSource(self, source=())
Connects view object to a source or sequence of sources
 
Internally the sources are always stored as a tuple.
GetSource always returns a tuple, even if SetSource was
initialized with a single object or None (== ()).
 
A source can be DataSelection or Filter derived objects.
 
Actually any class can be a source if the derived View knows
how to interface to it.
The common interface (the one implemented to DataSelection
and Filter is:
  - The source have an EventHandler member called eh
    on which the View registers "DataChange" and "DeleteEvent"
    (these should be emmited by the source, and derived View classes
    don't mind registering, since it is done in View base class).
  - The source shall have a GetOutput method on which the
    View gets the actual data in a dictionary, as described
    in the Filter module.
With this interface existing View classes can be connect to
new source classes and new View classes can be connected to
existing source classes.
 
 
Parameters:
    source: DataSelection/Filter object or sequence of objects
Show(self) from PyDVT.GUIBinding.Binding.Container
Update(self)
Causes redraw of view and notification of linked ViewSelect ojects
Derived classes must always call this method to generate the redrawing,
instead calling Redraw, for ViewSelect notification
_ButtonPress(self, event)
Called by derived class / drawable
_ButtonPressMotion(self, event)
Called by derived class / drawable
_ButtonRelease(self, event)
Called by derived class / drawable
_CmdLockPosition(self)
_CmdOnLine(self)
_DataChanged(self, source=None)
_DataDeleted(self, source=None)
_DoubleClick(self, event)
Called by derived class / drawable
_KeyPress(self, key, flags=None)
Called by derived class / drawable
_Motion(self, event)
Called by derived class / drawable
_RightButtonPress(self, event)
Called by derived class / drawable
__init__(self, parent=None, pars={}, **kw)
Constructor
Parameters:
  parent: Parent window
  pars:   Dictionary with View initialization options
    Options defined by base class:
    (If an option is ommited, the default value is taken)
        "ZoomMode":
          Sets View's zoom mode ("ON","OFF",...)
          Default:"ON"
        "ScrollMode":
          Sets View's scroll mode ("ON","OFF",...)
          Default:"ON"
        "AddOnLine":
          If non-zero adds on-line entry in menu
          (enables/disables response to DataChange events)
          Default:0
        "AddLockPosition":
          If non-zero adds lock position entry in menu
          (sets/resets zoom/scroll position lock in a
          DataChange event )
          Default:0
        "AddRefresh":
          If non-zero adds refresh entry in menu
          (requeries sources and redraws contents)
          Default:0
        "DataChangedCallback":
          If defined, sets a callback called to inform a DataChanged event
          has just been processed.
          Callback receives two parameters, the view object and the
          source object that generated the DataChange event
    New initialization options can be defined by derived classes                                           
  kw:     keywords to Container initializatregisterion

 
Author
             Alexandre Gobbo (gobbo@esrf.fr)