Class Command

Known Subclasses:

dejaVuCommands.AddClipPlane, dejaVuCommands.AlignGeoms, dejaVuCommands.AlignGeomsPCOM, dejaVuCommands.CenterGeom, dejaVuCommands.CenterScene, dejaVuCommands.CenterSceneOnVertices, dejaVuCommands.ColorGeomsByName, dejaVuCommands.ColorMapEditor, dejaVuCommands.CreateColorMap, dejaVuCommands.EditColorMap, dejaVuCommands.LoadColorMap, dejaVuCommands.PrintGeometryName, dejaVuCommands.RenderLargeImageCommand, dejaVuCommands.RotateScene, dejaVuCommands.SaveColorMap, dejaVuCommands.SaveImage, dejaVuCommands.SetCamera, dejaVuCommands.SetCameraSizeCommand, dejaVuCommands.SetClip, dejaVuCommands.SetLight, dejaVuCommands.SetObject, dejaVuCommands.SpinCommand, dejaVuCommands.StartContinuousPicking, dejaVuCommands.StopContinuousPicking, dejaVuCommands.ToggleNpr, dejaVuCommands.ToggleStereo, dejaVuCommands.TransformObject, dejaVuCommands.ViewPoints, dejaVuCommands.setAntialiasingCommand, dejaVuCommands.setNPROutlinesCommand, dejaVuCommands.setbackgroundcolorCommand, helpCommands.CitationCommand, helpCommands.ReportBugCommand, helpCommands.SearchCommand, helpCommands.helpCommand, helpCommands.mailingListsCommand, serverCommands.ConnectToServer, serverCommands.StartServer, serverCommands.StartWebControlServer, serverCommands.WebDrivenTutorial, customizationCommands.SetOnAddObjectCmds, customizationCommands.SetUserPreference, customizationCommands.SourceCommand, basicCommand.BrowseCommandsCommand, basicCommand.ExitCommand, basicCommand.ResetUndoCommand, basicCommand.SaveSessionCommand, basicCommand.ShellCommand, basicCommand.UndoCommand, basicCommand.loadModuleCommand, basicCommand.loadMacroCommand, customizeVFGUICommands.BindActionToMouse, customizeVFGUICommands.ChangeFont, customizeVFGUICommands.HideGUICommand, customizeVFGUICommands.ShowGUICommand, customizeVFGUICommands.showHideGUI

Base class for adding commands to a Viewer derived from ViewerFramework
Classes derived from that class can be added to a viewer using the
addCommand method.
Commands are derived from the VFCommand base class and should implement or
overwrite the following methods:

    __init__(self, func=None)
        The constructor has to be overwritten to set the self.flag attribute
        properly.
        self.objArgOnly is turned on when the doit only has one required
        argument which is the current selection.
        This will automatically make this command a Picking command
        self.negateKw is turned on when the doit method takes a boolean
        flag negate which makes this command undoable.

    __call__(self, *args, **kw):
        Entrypoint to the command from the command line. It overloads
        calling the object (command) as a function, which enables calling
        an instance of a command as a method of a viewer once it it has
        been loaded.
        
        Typically, this method checks the arguments supplied and calls the
        doitWrapper method with the arguments supplied.
        
        This method needs to have the same signature than the doit.
        A documentation string supplying the following information will be
        displayed in a tooltip when calling the command from the python
        idle shell.
        This documentation string should provide the synopsis of the
        command and a description of the arguments.
            
    guiCallback(self, event=None, *args, **kw):
        This method is bound by default as the callback of the GUI item
        associated with the command.
        It is the entrypoint of the command through the GUI.
        
        It typically creates an inputform allowing the user to specify any
        argument required for the command.
        The command method showForm is typically called with the name of
        the form to be created and a bunch of optional argument described
        later.
        Once all the parameters are known, the doitWrapper method is
        called to carry out the command.

        The old behavior was to call self.vf.getUserInput. The showForm method
        is a command method and replace the getUserInput method of the
        ViewerFramework. Although some commands still implement the
        getUserInput mechanism.
        
    buildFormDescr(self, formName):
        This method typically creates the inputform descriptor used by the
        guiCallback method to get user input for the command.
        The formName is a string which will be used as a key in the
        cmdForms dictionary to store the form information.
        This method is called by self.showForm
        This method returns an instance of an InputFormDescr which is the
        object describing a inputform in ViewerFramework.
        More information can be found in mglutil/gui/InputForm/Tk/gui.py

        For an example see:
        ViewerFramework.basicCommand.BrowseCommandsCommand: 
         This command creates a non modal non blocking form
         
    setLastUsedValues(self, **kw):
        This method can be used to set the values to that appear in the GUI
        
    getLastUsedValues(self):
        Returns the values fo the parameters for the command

    doit(self, *args, **kw):
        This method does the actual work. It should not implement any
        functionality that should be available outside the application
        for scripting purposes. This method should call such functions or
        object. 
        
    setUpUndo(self, *args, **kw):
        Typically this method should be implemented if the command is
        undoable. It should have the same signature than the doit and the
        __call__ method.
        
Of course, one is free to overwrite any of these methods and for instance
rename doit using a more appropriate name. But, when doing so,
the programmer has to overwrite both __call__ and guiCallback to call
the right method to carry out the work.

Besides these methods which are required to be implemented in a command there
are the following optional methods:
     strArg(self, arg):
         Method to turn a command argument into a string. Used by the log
         method to generate a log string for the command.
         This method can be overwritten or extended by classes subclassing
         Command in order to handle properly instances of objects defined
         by the application when not handled properly by the base class.
         
    checkDependencies():
        This method called when command is loaded. It typically checks for
        dependencies and if all the dependencies are not found the command
        won't be loaded.
        
    onAddCmdToViewer():
        (previously initCommand)
        onAddCmdToViewer is called once when a command is loaded into a
        Viewer. 
        Typically, this method :
            takes care of dependencies (i.e. load other commands that
                                        might be required)
            creates/initializes variables.
        see ViewerFramework.basicCommand.py UndoCommand for an example
            
    customizeGUI(self):
        (obsolete)
        method allowing to modify the GUI associated with a command
        
    onAddObjectToViewer(self, obj):
        (previously named initGeom)
        When a command is loaded that implements an onAddObjectToViewer
        function,this function id called for every object present in the
        application.
        Once the command is loaded, this function will be called for every
        new object added to the application.
        In general, onAddObjectToViewer is used by a command to add a new
        geometry to the geometry container of an object.
        It is also where picking events and building arrays of colors specific
        to each geometry can be registered.
        
    onRemoveObjectFromViewer(self, obj):
        In python if all references to an object are not deleted, memory
        space occupied by that object even after its deletion is not freed.
        
        This function will be called for every object removed (deleted) from
        the application.
        When references to an object are created inside a command which are
        not related to the geomContainer of the object, in order to prevent
        memory leak this command has to implement an onRemoveObjectFromViewer
        to delete those references.

    onCmdRun(self, cmd, *args, **kw):
        if the list in self.vf.cmdsWithOnRun[cmd] holds this command, each
        time cmd runs command.onCmdRun will be called if callListener is true
        
The following methods are helper methods.
    log(self, *args, **kw):
         Method to log a command. args provides a list of positional
         arguments and kw is a dictionary of named arguments. This method
         loops over both args and kw and builds a string representation of
         their values. When a class is passed as one the arguments, an
         additional command is logged to load that class.
         This method also sets the command's lastCmdLog member.

    showForm(self, *args, **kw):
         If the inputForm object associated with the given formName already
         exists than it just deiconify the forms unless the force argument is
         set to true.
         Otherwise, showForm calls buildFormDescr with the given
         formName, then it creates an instance of InputForm with the given
         parameters and stores this object in the cmdForms dictionary, where
         the key is the formName and the value the InputForm object.
         (see the showForm documentation string for the description of the
         arguments)

If a command generates geometries to be displayed in the camera, it is
expected to create the geometry objects and add them to the appropriate
GeometryContainer.  The geometry should be be added to the molecule's geometry
container using the .addGeom method of the geometry container.  If the
geoemtry should be updated uon modification events (i.e. atoms addition,
deletion or editing) the command should pass itself as the 3rd argument to
gcontainer.addGeom().  This will trigger the updateGeom method to be called
upon modification events.

    if the default modification event method is not applicable, a command can
    overwrite it.
    
    def updateGeom(self, event, geomList):
        the event is a ViewerFramework.VF.ModificationEvent instance
        geomList is a list of geometries to be updated

        check out Pmv/mvCommand for an example of updateGeom working for
        several Pmv display commands
         
A Python module implementing commands should implement the following at the
end of the file so the commands are loadable in the application using
the browseCommands command.

commandList -- which is a list of dictionaries containing the following:
               'name': command name (string) used as an alias to invoke
                       the command from the commandline.
               'cmd' : Command Class
               'gui' : Typically is a commandGUI object but can be None
                       if no GUI is associated with the Command

An initModule method
def initModule(viewer):
    for dict in commandList:
        viewer.addCommand(dict['cmd'], dict['name'], dict['gui'])

This method will be used by the browseCommands command to load the
given module into the application but also to determine which
modules implement commands.
    

        Method to turn a command argument into a string,
FIXME describe what types of arguments are handled
        

val/form <- getUserInput(self, formName, force=0, master=None, root=None,
                         modal=1, blocking=0, defaultDirection='row',
                         closeWithWindow=1, okCfg={'text':'OK'},
                         cancelCfg={'text':'Cancel'}, initFunc=None,
                         scrolledFrame=0, width=100, height=200,
                         okcancel=1, onDestroy=None, help=None,
                         posx=None, posy=None)

MAKE SURE that the list of arguments passed to showForm is up to date
with the list of arguments of the InputForm constructor.
showForm will return either the dictionary of values (name of the widget: value
of the widget) if the form has a OK/CANCEL button or the form object itself.

required arguments:
    formName -- String which will be given to buildFormDescr. It refers to
                the name of the inputform to be created.

optional arguments :
    master  -- container widget or the master of the widget to be created
               which means that the current form will be a 'slave' of the
               given master if None is specified then self.vf.GUI.ROOT
               
    root    -- if root is not specified a Tkinter.TopLevel will
               be created.

    modal   -- Flag specifying if the form is modal or not. When a form
               is modal it grabs the focus and only releases it when the
               form is dismissed. When a form is modal an OK and a CANCEL
      button will be automatically added to the form.
      (default = 1)

    blocking -- Flag specifying if the form is blocking or not. When set to
      1 the form is blocking and the calling code will be stopped until the
      form is dismissed. An OK and a CANCEL button will be automatically
      added to the form. (default = 0)

    defaultDirection -- ('row', 'col') specifies the direction in
      which widgets are gridded  into the form by default. (default='row')

    closeWithWindow -- Flag specifying whether or not the form should be
      minimized/maximized  when the master window is. (default=1)

    okCfg -- dictionnary specifying the configuration of the OK button.
             if a callback function is specified using the keyword
             command this callback will be added to the default callback
             Ok_cb

    cancelCfg -- dictionnary specifying the configuration of the CANCEL button
             if a callback function is specified using the keyword
             command this callback will be added to the default callback
             Ok_cb

    initFunc  -- specifies a function to initialize the form.

    onDestroy -- specifies a function to be called when using the close
       widget of a window.

    okcancel -- Boolean Flag to specify whether or not to create the OK and
               CANCEL
                button.
    scrolledFrame -- Flag when set to 1 the main frame is a scrollable frame
                     else it is static Frame (default 0)
    width -- specifies the width of the main frame (400)
    height -- specifies the height of the main frame. (200)
    help   -- specifies the web adress to a help page. If this is provided
              a Help (?) button will be created which will open a
              web browser to the given adress.
              By default help URL is:
              http://www.scripps.edu/~sanner/software/help/PACKNAME/doc/moduleName.html#guiCallback
              Which is the documentation generated by Happydoc from the
              code's documentation strings.
    posy posy position wher the form is displayed
         

gets called by register method of the CommandGUI object after the
gui for a command has been added to a viewer's GUI.
It allows each command to set the configuration of the widgets in its
GUI.

Here is how to get to the widgets:

    # find the mneu bar name
    barName = self.GUI.menuDict['menuBarName']

    # find the bar itsel
    bar = self.vf.GUI.menuBars[barName]

    # find the button name
    buttonName = self.GUI.menuDict['menuButtonName']

    # find the button itself
    button = bar.menubuttons[buttonName]

    # find the entry name
    entryName = self.GUI.menuDict['menuEntryLabel']

    # configure the entry name
    n = button.menu
    n.entryconfig(n.index(entryName), background = 'red' )