def find_plugin_dir(plugin_name):
    """
    Return (True, dirname) or (False, errortext), with errortext wording chosen as if the requested plugin ought to exist.
    """
    try:
        userdir = user_plugins_dir()
        if userdir and os.path.isdir(userdir):
            path = os.path.join(userdir, plugin_name)
            if os.path.isdir(path):
                return True, path
    except:
        print_compact_traceback("bug in looking for user-customized plugin %r; trying builtin plugins: ")
        pass
    try:
        appdir = builtin_plugins_dir()
        assert appdir
        if not os.path.isdir(appdir):
            return False, "error: can't find built-in plugins directory [%s] (or it's not a directory)" % (appdir,)
        path = os.path.join(appdir, plugin_name)
        if os.path.isdir(path):
            return True, path
        return False, "can't find plugin %r" % (plugin_name,)
    except:
        print_compact_traceback("bug in looking for built-in plugin %r: " % (plugin_name,))
        return False, "can't find plugin %r" % (plugin_name,)
    pass

 def get_atomtype_from_MMKit(self):
     """
     Return the current atomtype selected in the MMKit.
     
     Note: This appears to be very similar (if not completely redundant) to 
     pastable_atomtype() in this file. 
     """
     elm = self.propMgr.elementChooser.getElement()
     atomtype = None
     if len(elm.atomtypes) > 1: 
         try:
             # Obtain the hybrid index from the hybrid button group, not
             # the obsolete hybrid combobox. Fixes bug 2304. Mark 2007-06-20
             hybrid_name = self.propMgr.elementChooser.atomType
             atype = elm.find_atomtype(hybrid_name)
             if atype is not None:
                 atomtype = atype
         except:
             print_compact_traceback("exception (ignored): ") 
         pass
     if atomtype is not None and atomtype.element is elm:
         return atomtype
         
     # For element that doesn't support hybridization
     return elm.atomtypes[0]    

    def makeMenus(self):
        ### WARNING: this copies and slightly modifies selectMode.makeMenus (not those of our superclass, depositMode!);
        # with slightly more work, we could instead just decide when to call the superclass one here
        # vs. when not to, rather than duplicating the menu items it produces.
        # But we can't do that for now, since we want to ditch its general items
        # whenever there is a selobj which defines make_selobj_cmenu_items,
        # even when we add atom-specific ones it also hardcodes,
        # and later we may also decide to not ditch them if the selobj's make_selobj_cmenu_items returns nothing.
        # DANGER: if this copied code got changed for Qt4, we're introducing a Qt4 porting problem into testmode.
        # [bruce 070228]

        selatom, selobj = self.graphicsMode.update_selatom_and_selobj( None)

        # not doing:
        ## superclass.makeMenus(self) # this makes standard items for selobj if it's atom or bond or Highlightable, and a few more

        self.Menu_spec = []

        # Local minimize [now called Adjust Atoms in history/Undo, Adjust <what> here and in selectMode -- mark & bruce 060705]
        # WARNING: This code is duplicated in depositMode.makeMenus(). mark 060314.
        if selatom is not None and not selatom.is_singlet() and self.w.simSetupAction.isEnabled():
            # see comments in depositMode version
            self.Menu_spec.append(( 'Adjust atom %s' % selatom, lambda e1 = None, a = selatom: self.localmin(a,0) ))
            self.Menu_spec.append(( 'Adjust 1 layer', lambda e1 = None, a = selatom: self.localmin(a,1) ))
            self.Menu_spec.append(( 'Adjust 2 layers', lambda e1 = None, a = selatom: self.localmin(a,2) ))

        # selobj-specific menu items. [revised by bruce 060405; for more info see the same code in depositMode]
        if selobj is not None and hasattr(selobj, 'make_selobj_cmenu_items'):
            try:
                selobj.make_selobj_cmenu_items(self.Menu_spec)
            except:
                print_compact_traceback("bug: exception (ignored) in make_selobj_cmenu_items for %r: " % selobj)

        return # from makeMenus

 def project_2d(self, pt):
     """
     like project_2d_noeyeball, but take into account self.eyeball;
     return None for a point that is too close to eyeball to be projected
     [in the future this might include anything too close to be drawn #e]
     """
     p = self.project_2d_noeyeball(pt)
     if self.eyeball:
         # bruce 041214: use "pfix" to fix bug 30 comment #3
         pfix = self.project_2d_noeyeball(self.org)
         p -= pfix
         try:
             ###e we recompute this a lot; should cache it in self or self.shp--Bruce
             ## Huaicai 04/23/05: made the change as suggested by Bruce above.
             p = p / (dot(pt - self.eyeball, self.normal) / self.eye2Pov)
         except:
             # bruce 041214 fix of unreported bug:
             # point is too close to eyeball for in-ness to be determined!
             # [More generally, do we want to include points which are
             #  projectable without error, but too close to the eyeball
             #  to be drawn? I think not, but I did not fix this yet
             #  (or report the bug). ###e]
             if debug_flags.atom_debug:
                 print_compact_traceback("atom_debug: ignoring math error for point near eyeball: ")
             return None
         p += pfix
     return p

    def _draw_jig(self, glpane, color, highlighted=False):
        """
        Draw a linear motor as a long box along the axis, with a thin cylinder (spoke) to each atom.
        """
        glPushMatrix()
        try:
            glTranslatef( self.center[0], self.center[1], self.center[2])
            q = self.quat
            glRotatef( q.angle*180.0/pi, q.x, q.y, q.z)

            orig_center = V(0.0, 0.0, 0.0)
            drawbrick(color, orig_center, self.axis, 
                      self.length, self.width, self.width, 
                      opacity = self.opacity)
            
            drawLinearSign((0,0,0), orig_center, self.axis, self.length, self.width, self.width)
                # (note: drawLinearSign uses a small depth offset so that arrows are slightly in front of brick)
                # [bruce comment 060302, a guess from skimming drawLinearSign's code]
            for a in self.atoms[:]:
                drawcylinder(color, orig_center, 
                             a.posn()-self.center, 
                             self.sradius, 
                             opacity = self.opacity)
        except:
            #bruce 060208 protect OpenGL stack from exception analogous to that seen for RotaryMotor in bug 1445
            print_compact_traceback("exception in LinearMotor._draw, continuing: ")
        glPopMatrix()

 def close(self, e = None):
     """
     When the user closes the dialog by clicking the 'X' button
     on the dialog title bar, do whatever the cancel button does.
     """
     print "\nfyi: GeneratorBaseClass.close(%r) was called" % (e,)
         # I think this is never called anymore,
         # and would lead to infinite recursion via cancel_btn_clicked
         # (causing bugs) if it was. [bruce 070829]
     
     # Note: Qt wants the return value of .close to be of the correct type,
     # apparently boolean; it may mean whether to really close (just a guess)
     # (or it may mean whether Qt needs to process the same event further,
     #  instead)
     # [bruce 060719 comment, updated after 070724 code review]
     try:
         self.cancel_btn_clicked()
         return True
     except:
         #bruce 060719: adding this print, since an exception here is either
         # an intentional one defined in this file (and should be reported as
         # an error in history -- if this happens we need to fix this code to
         # do that, maybe like _ok_or_preview does), or is a bug. Not
         # printing anything here would always hide important info, whether
         # errors or bugs.
         print_compact_traceback("bug in cancel_btn_clicked, or in not reporting an error it detected: ")
         return False

    def leftDrag(self, event):
        """
        Translate the selected object(s):
        - in the plane of the screen following the mouse,
        - or slide and rotate along the an axis

        @param event: The mouse left drag event.
        @type  event: QMouseEvent instance
        """
        _superclass.leftDrag(self, event)

        if self.cursor_over_when_LMB_pressed == "Empty Space":
            # The _superclass.leftDrag considers this condition.
            # So simply return and don't go further. Fixes bug 2607
            return

        if self.leftDownType in ["TRANSLATE", "A_TRANSLATE"]:
            try:
                self.leftDragTranslation(event)
                return
            except:
                msg1 = "Controlled translation not allowed. "
                msg2 = "Key must be pressed before starting the drag"
                env.history.statusbar_msg(msg1 + msg2)
                if debug_flags.atom_debug:
                    msg3 = "Error occured in " "TranslateChunks_GraphicsMode.leftDragTranslation."
                    msg4 = "Possibly due to a key press that activated. "
                    msg5 = "Rotate groupbox. Aborting drag operation"
                    print_compact_traceback(msg3 + msg4 + msg5)

 def _draw_by_remaking(self, glpane, selected, highlighted, wantlist, draw_now):
     """
     """
     # modified from similar code in ChunkDrawer.draw
     assert not (not wantlist and not draw_now)
     if wantlist:
         match_checking_code = self.begin_tracking_usage()
             # note: method defined in superclass, SubUsageTrackingMixin
         ColorSorter.start(glpane, self.csdl, selected)
             ### REVIEW: is selected arg needed? guess yes,
             # since .finish will draw it based on the csdl state
             # which is determined by that arg. If so, this point needs
             # correcting in the docstring for csdl.draw().
     self.comparator.before_recompute()
     try:
         self._do_drawing()
     except:
         print_compact_traceback(
             "bug: exception in %r._do_drawing, skipping the rest: " % self)
         self.comparator.after_recompute()
             # note: sets self.comparator.valid (in spite of error)
         pass
     else:
         self.comparator.after_recompute()
     if wantlist:
         ColorSorter.finish(draw_now = draw_now)
         # needed by self._invalidate_display_lists for gl_update
         self._glpane = glpane
         self.end_tracking_usage( match_checking_code,
                                  self._invalidate_display_lists )
     return

 def careful_widget_setter(self, value):
     # Note: for some time we used self.widget_setter rather than this method,
     # by mistake, and it apparently worked fine. We'll still use this method
     # as a precaution; also it might be truly needed if the widget quantizes
     # the value, unless the widget refrains from sending signals when
     # programmatically set. [bruce 070815]
     if self.debug:
         print "\n_changes__debug_print: %r setting %r to %r using %r" % \
               ( self, self.widget, value, self.widget_setter )
     self.disconnect() # avoid possible recursion
     try:
         self.widget_setter(value)
     except:
         print_compact_traceback("bug: ignoring exception setting value of %r to %r: " % (self, value))
         print_compact_stack(" fyi: prior exception came from: ")
         self.destroy() #bruce 080930
             # this seems to be safe, but debug output implies it fails to stop formula
             # from continuing to call setter! but that seems unlikely... nevermind for now.
             # Review: do we want subsequent use of self
             # to be silently ok, smaller message, or error? If this destroy worked
             # then I think it should be silently ok, but might not be now,
             # depending on how refs to self continue to be used.
         pass
     else:
         self.connect()
         ### WARNING: .connect is slow, since it runs our Python code to set up an undo wrapper
         # around the slot! We should revise this to tell Qt to block the signals instead.
         # [We can use: bool QObject::blockSignals ( bool block ) ==> returns prior value of signalsBlocked,
         #  now used in a helper function setValue_with_signals_blocked]
         # This will matter for performance when this is used for state which changes during a drag.
         # Note: avoiding the slot call is needed not only for recursion, but to avoid the
         # Undo checkpoint in the wrapper.
         # [bruce comments 071015; see also bug 2564 in other code]
     return

 def kill(self):
     """
     Overrides superclass method. For a Dnasegment , as of 2008-04-09,
     the default implementation is that deleting a segment will delete 
     the segment along with its logical contents (see bug 2749).
     """
     # It is tempting to call self.kill_with_contents , BUT DON'T CALL IT HERE!
     # ...as kill_with_contents  is used elsewhere (before bug 2749 NFR was
     # suggested and it calls self.kill() at the end. So that will create 
     # infinite recursions. 
     ### TODO: code cleanup/ refactoring to resolve kill_with_content issue
     
     #The following block is copied over from self.kill_with_contents()
     #It implements behavior suggested in bug 2749 (deleting a segment will 
     #delete the segment along with its logical contents )
     #See method docsting above on why we shouldn't call that method instead
     for member in self.members:
         if isinstance(member, DnaAxisChunk):          
             ladder = member.ladder
             try:
                 #See a note in dna_model.kill_strand_chunks. Should we 
                 #instead call ladder.kill() and thus kill bothstrand 
                 #and axis chunks. ?
                 ladder.kill_strand_chunks()
             except:
                 print_compact_traceback("bug in killing the ladder chunk")
                 
     DnaStrandOrSegment.kill(self)

 def kill_with_contents(self):  
     """
     Kill this Node including the 'logical contents' of the node. i.e. 
     the contents of the node that are self.members as well as non-members. 
     Example: A DnaSegment's logical contents are AxisChunks and StrandChunks 
     Out of these, only AxisChunks are the direct members of the DnaSegment
     but the 'StrandChunks are logical contents of it (non-members) . 
     So, some callers may specifically want to delete self along with its 
     members and logical contents. These callers should use this method. 
     The default implementation just calls self.kill()
     @see: B{Node.DnaSegment.kill_with_contents}  which is overridden here
           method. 
     @see: EditCommand._removeStructure() which calls this Node API method
     @see: InsertDna_EditCommand._removeSegments()
     @see: dna_model.DnaLadder.kill_strand_chunks() for a comment.
     
     @see: A note in self.kill() about NFR bug 2749
     
     """   
     for member in self.members:            
         if isinstance(member, DnaAxisChunk):                
             ladder = member.ladder
             try:
                 #See a note in dna_model.kill_strand_chunks. Should we 
                 #instead call ladder.kill() and thus kill bothstrand 
                 #and axis chunks. ?
                 ladder.kill_strand_chunks()
             except:
                 print_compact_traceback("bug in killing the ladder chunk")
     
     DnaStrandOrSegment.kill_with_contents(self)

def _safely_call_getEquilibriumDistanceForBond( eltnum1, eltnum2, ltr): #bruce 080405 split this out
    """
    #doc
    eg: args for C-C are (6, 6, '1')

    @return: ideal length in Angstroms (as a positive float),
             or None if the call of getEquilibriumDistanceForBond failed
    """
    try:
        pm = thePyrexSimulator().getEquilibriumDistanceForBond(eltnum1,
                                                               eltnum2,
                                                               ltr)
        assert pm > 2.0, "too-low pm %r for getEquilibriumDistanceForBond%r" % \
               (pm, (eltnum1, eltnum2, ltr))
            # 1.0 means an error occurred; 2.0 is still ridiculously low
            # [not as of 070410]; btw what will happen for He-He??
            # update 070410: it's 1.8 for (202, 0, '1').
            # -- but a new sim-params.txt today changes the above to 170
        nicelen = pm / 100.0 # convert picometers to Angstroms
        return nicelen
    except:
        # be fast when this happens a lot (not important now that our retval
        # is cached, actually; even so, don't print too much)
        if not env.seen_before("error in getEquilibriumDistanceForBond"):
            #e include env.redraw_counter to print more often? no.
            msg = "bug: ignoring exceptions when using " \
                  "getEquilibriumDistanceForBond, like this one: "
            print_compact_traceback(msg)
        return None
    pass

 def __getitem__(self, key):
     # get the "current glpane" and its graphicsMode
     # (for purposes of determining modes & prefs)
     # (how we do it is not necessarily a kluge, given that this is being
     #  used to define a constant value for use when a better one was
     #  not passed)
     if debug_flags.atom_debug:
         print "fyi: getting %r from %r" % (key, self)
         # This happens 5 or 6 times when entering Build Atoms command;
         # not sure why, but probably ok.
         # Historical note: On 081003 I fixed what I thought was a typo below
         # (mainWindow -> mainwindow), here and in another place below,
         # and was surprised that this had no effect, and wondered why the
         # prior presumed exception had been silently discarded. In fact,
         # it was not a typo -- mainWindow is an alias for mainwindow in env.
         # So there was no exception and there is no mystery.
         # (An actual exception here causes, at least, a bug when hovering
         #  over a 3' strand end arrowhead, in Select Chunks mode.)
         # [bruce 081211 comment]
     win = env.mainwindow()
     glpane = win.glpane
     graphicsMode = glpane.graphicsMode
     # let the graphicsMode interpret the prefs key,
     # in case it wants to override it with a local pref
     # (or conceivably, someday, track it in a different way)
     # (note, ThumbView has no graphicsMode, but that doesn't
     #  affect this code since it uses main glpane even when
     #  drawing into a ThumbView. [bruce 080606 comment])
     try:
         res = graphicsMode.get_prefs_value(key)
     except:
         msg = "bug: exception in %r.get_prefs_value(%r), %s" % (graphicsMode, key, "falling back to env.prefs")
         print_compact_traceback(msg + ": ")
         res = env.prefs[key]
     return res

    def insertItems(self, row, items, setAsDefault = True):
        """
        Insert the <items> specified items in this list widget.
        The list widget shows item name string , as a QListwidgetItem.

        This QListWidgetItem object defines a 'key' of a dictionary
        (self._itemDictionary) and the 'value' of this key is the object
        specified by the 'item' itself.
        Example: self._itemDictionary['C6'] = instance of class Atom.

        @param row: The row number for the item.
        @type row: int

        @param items: A list of objects. These objects are treated as values in
                      the self._itemDictionary
        @type items: list

        @param setAsDefault: Not used here. See PM_ListWidget.insertItems where
                             it is used.

        @see: self.renameItemValue() for a comment about
              self._suppress_itemChanged_signal

        """

        #delete unused argument. Should this be provided as an argument in this
        #class method ?
        del setAsDefault

        #self.__init__ for a comment about this flag
        self._suppress_itemChanged_signal = True

        #Clear the previous contents of the self._itemDictionary
        self._itemDictionary.clear()

        #Clear the contents of this list widget, using QListWidget.clear()
        #See U{<http://doc.trolltech.com/4.2/qlistwidget.html>} for details
        self.clear()

        for item in items:
            if hasattr(item.__class__, 'name'):
                itemName = item.name
            else:
                itemName = str(item)
            listWidgetItem = QListWidgetItem(itemName, self)

            #When we support editing list widget items , uncomment out the
            #following line . See also self.editItems -- Ninad 2008-01-16
            listWidgetItem.setFlags( listWidgetItem.flags()| Qt.ItemIsEditable)

            if hasattr(item.__class__, 'iconPath'):
                try:
                    listWidgetItem.setIcon(geticon(item.iconPath))
                except:
                    print_compact_traceback()

            self._itemDictionary[listWidgetItem] = item

        #Reset the flag that temporarily suppresses itemChange signal.
        self._suppress_itemChanged_signal = False

 def draw_after_highlighting(self, 
                             glpane, 
                             dispdef, 
                             pickCheckOnly = False):
     """
     For ESPImage class, this does all the drawing. (Does it after main
     drawing code is finished drawing.) This method ensures that the 
     ESP image jig gets selected even when you click inside the 
     rectangular box (i.e. not just along the edges of the box).
     """
     anythingDrawn = False
     if self.hidden:
         return anythingDrawn
     
     self.pickCheckOnly = pickCheckOnly        
     anythingDrawn = True
     glPushName(self.glname)
     try:
         self._draw(glpane, dispdef) #calls self._draw_jig()
     except:
         anythingDrawn = False
         msg = "ignoring exception when drawing Jig %r" % self
         print_compact_traceback(msg + ": ")
     glPopName()
     
     return anythingDrawn

def node_name(node): # revised 070207
    """
    return the name property of the node, regardless of which
    model tree node interface it's trying to use [slight kluge]
    """
    try:
        node.mt_name # look for (value computed by) ModelTreeNodeInterface method
    except AttributeError:
        pass
    else:
        return node.mt_name

    try:
        node.name # look for legacy Node variable
    except AttributeError:
            pass
    else:
        return node.name

    try:
        return "%s" % node
    except:
        last_resort = safe_repr(node, maxlen = 20) ### FIX: Undefined variable safe_repr, print_compact_traceback
        print_compact_traceback("node_name fails when trying %%s on node %s: " % last_resort )
        return last_resort
    pass

    def changeBackgroundColor(self, idx):
        """
        Slot method for the background color combobox.
        """
        #print "changeBackgroundColor(): Slot method called. Idx =", idx

        if idx == bg_BLUE_SKY:
            self.win.glpane.setBackgroundGradient(idx + 1)
        elif idx == bg_EVENING_SKY:
            self.win.glpane.setBackgroundGradient(idx + 1)
        elif idx == bg_SEAGREEN:
            self.win.glpane.setBackgroundGradient(idx + 1)
        elif idx == bg_BLACK:
            self.win.glpane.setBackgroundColor(black)
        elif idx == bg_WHITE:
            self.win.glpane.setBackgroundColor(white)
        elif idx == bg_GRAY:
            self.win.glpane.setBackgroundColor(gray)
        elif idx == bg_CUSTOM:
            #change background color to Custom Color
            self.chooseCustomBackgroundColor()
        else:
            msg = "Unknown color idx=", idx
            print_compact_traceback(msg)

        self.win.glpane.gl_update() # Needed!
        return

 def colorframe_bgcolor_setter(color):
     #e no convenient/clean way for Formula API to permit but not require this function to receive the formula,
     # unless we store it temporarily in env._formula (which we might as well do if this feature is ever needed)
     try:
         # make sure errors here don't stop the formula from running:
         # (Need to protect against certain kinds of erroneous color values? RGBf_to_QColor does it well enough.)
         ## Qt3 code used: colorframe.setPaletteBackgroundColor(RGBf_to_QColor(color))
         qcolor = RGBf_to_QColor(color)
         palette = QPalette() # QPalette(qcolor) would have window color set from qcolor, but that doesn't help us here
         qcolorrole = QPalette.Window
             ## http://doc.trolltech.com/4.2/qpalette.html#ColorRole-enum says:
             ##   QPalette.Window    10    A general background color.
         palette.setColor(QPalette.Active, qcolorrole, qcolor) # used when window is in fg and has focus
         palette.setColor(QPalette.Inactive, qcolorrole, qcolor) # used when window is in bg or does not have focus
         palette.setColor(QPalette.Disabled, qcolorrole, qcolor) # used when widget is disabled
         colorframe.setPalette(palette)
         colorframe.setAutoFillBackground(True)
         # [Note: the above scheme was revised again by bruce 070430, for improved appearance
         #  (now has thin black border around color patch), based on Ninad's change in UserPrefs.py.]
         ## no longer needed: set color for qcolorrole = QPalette.ColorRole(role) for role in range(14)
         ## no longer needed: colorframe.setLineWidth(500) # width of outline of frame (at least half max possible size)
     except:
         print "data for following exception: ",
         print "colorframe %r has palette %r" % (colorframe, colorframe.palette())
             # fyi: in Qt4, like in Qt3, colorframe is a QFrame
         print_compact_traceback( "bug (ignored): exception in formula-setter: " ) #e include formula obj in this msg?
     pass

 def draw_after_highlighting(self, 
                             glpane, 
                             dispdef, 
                             pickCheckOnly = False):
     """
     For ESPImage class, this does all the drawing. (does it after main
     drawing code is finished drawing) . This method ensures that the 
     ESP image jig gets selected even when you click inside the 
     rectangular box (i.e. not just along the edgets of the box)
     @see: GraphicsMode.Draw_after_highlighting()
     @see: Node.draw_after_highlighting()
     @see:Plane.draw_after_highlighting()
     """
     anythingDrawn = False
     if self.hidden:
         return anythingDrawn
     
     self.pickCheckOnly = pickCheckOnly        
     try:
         anythingDrawn = True
         glPushName(self.glname)
         self._draw(glpane, dispdef) #calls self._draw_jig()
     except:
         anythingDrawn = False
         glPopName()
         print_compact_traceback("ignoring exception when drawing Jig %r: " % self)
     else:
         glPopName()
         
     return anythingDrawn

    def __init__(self):
        ok, nd1_plugin_path = find_plugin_dir("NanoDynamics-1")
        if (not ok):
            env.history.redmsg("Error: can't find " + nd1_plugin_path)
            nd1_plugin_path = "."
        fileName = os.path.join(nd1_plugin_path, "sim-params.txt")

        self._parameterValues = {}
        try:
            print "sim parameters used by NE1 read from: [%s]" % fileName
            parametersFile = open(fileName)
            for line in parametersFile:
                s = line.split()
                if (len(s) > 0 and s[0] == "ne1"):
                    if (len(s) > 1):
                        key = s[1]
                        if (len(s) > 2):
                            value = " ".join(s[2:])
                        else:
                            value = True
                        self._parameterValues[key] = value
        except IOError:
            msg = "Error reading [%s]" % fileName
            print_compact_traceback(msg + ": ")
            env.history.redmsg(msg)
            self._parameterValues = {}