def _file_position_changed ( self, file_position ):
        """ Handles the 'file_position' trait being changed.
        """
        if file_position is not None:
            # Reset the current file position to None, so we are ready for a
            # new one:
            do_later( self.set, file_position = None )

            viewers = self.viewers
            for i, viewer in enumerate( viewers ):
                if ((file_position.name      == viewer.name)      and
                    (file_position.file_name == viewer.file_name) and
                    (file_position.lines     == viewer.lines)     and
                    (file_position.object    == viewer.object)):
                    viewer.selected_line = file_position.line
                    if i == (len( viewers ) - 1):
                        return
                    del viewers[i]
                    break
            else:
                # Create the viewer:
                viewer = AnFBIViewer(
                             **file_position.get( 'name', 'file_name', 'line',
                                                  'lines', 'object' ) )

                # Make sure the # of viewers doesn't exceed the maximum allowed:
                if len( viewers ) >= self.max_viewers:
                    del viewers[0]

            # Add the new viewer to the list of viewers (which will cause it to
            # appear as a new notebook page):
            viewers.append( viewer )

    def __init__(self, model=None, **metadata):
        """ Setup and initialize the plot. """
        tui.ModelView.__init__(self, model=model, **metadata)
        axes = self.figure.add_subplot(111)
        self.lines = []
        for i in range(self.model.timeseries.shape[1] - 1):
            line, = axes.plot([0], [1],
                              color='mistyrose',
                              alpha=.5)
            self.lines.append(line)

        axes.set_title('Frequency Content')
        axes.set_ylabel(r'Signal Strength ($\mu$V/sqrt(Hz))')
        axes.set_xlabel('Frequency (Hz)')
        axes.set_xticks([i * 10 for i in range(10)])  # multiples of 10
        axes.set_xlim(0, 65,  # SAMPLE_RATE / 2,
                      auto=False)

#         axes.set_ylim(-1, self.model.timeseries.shape[1] - 1, auto=False)
#         axes.set_yticks(y_ticks)
#         axes.set_yticklabels(y_labels)
        axes.set_yscale('log')
        self.axes = axes
        # l/b/r/t
        do_later(self.figure.tight_layout)  # optimize padding and layout after everything's set up.

    def _item_changed ( self, item ):
        """ Handles the 'item' trait being changed.
        """
        if isinstance( item, HasPayload ):
            item = item.payload

        if isinstance( item, TraitsNode ):
            item = item.value

        if item is not None:
            inspectors       = []
            self._file_names = []
            description      = ''
            for klass in item.__class__.__mro__:
                module = klass.__module__.split( '.' )
                module_name = module[-1]
                if module_name != '__builtin__':
                    module_name += '.py'
                if len( description ) > 0:
                    description += ' -> '
                description += '%s[%s]' % ( klass.__name__, module_name )
                inspector = self.inspector_for( join( *module ), item )
                if inspector is not None:
                    inspectors.append( inspector )
                    self._file_names.append( inspector.file_name )
            self.inspectors  = inspectors
            self.description = description
            do_later( self.set, item = None )

    def _mouse_click(self, event, trait):
        """ Generate a TabularEditorEvent event for a specified mouse event and
            editor trait name.
        """
        x = event.GetX()
        row, flags = self.control.HitTest(wx.Point(x, event.GetY()))
        if row == wx.NOT_FOUND:
            if self.factory.multi_select:
                self.multi_selected = []
                self.multi_selected_rows = []
            else:
                self.selected = None
                self.selected_row = -1
        else:
            if self.factory.multi_select and event.ShiftDown():
                # Handle shift-click multi-selections because the wx.ListCtrl
                # does not (by design, apparently).
                # We must append this to the event queue because the
                # multi-selection will not be recorded until this event handler
                # finishes and lets the widget actually handle the event.
                do_later(self._item_selected, None)

            setattr(self, trait, TabularEditorEvent(
                editor=self,
                row=row,
                column=self._get_column(x, translate=True)
            ))

        # wx should continue with additional event handlers. Skip(False)
        # actually means to skip looking, skip(True) means to keep looking.
        # This seems backwards to me...
        event.Skip(True)

    def _project_changed_for_model_service(self, object, name, old, new):
        """
        Detects if an autosaved version exists for the project, and displays
        a dialog to confirm restoring the project from the autosaved version.

        """

        if old is not None:
            self.timer = None
        if new is not None:
            # Check if an autosaved version exists and if so, display a dialog
            # asking if the user wishes to restore the project from the
            # autosaved version.
            # Note: An autosaved version should exist only if the app crashed
            # unexpectedly. Regular exiting of the workbench should cause the
            # autosaved version to be deleted.
            autosave_loc = self._get_autosave_location(new.location.strip())
            if (os.path.exists(autosave_loc)):
                # Issue a do_later command here so as to allow time for the
                # project view to be updated first to reflect the current
                # project's state.
                do_later(self._restore_from_autosave, new,
                         autosave_loc)
            else:
                self._start_timer(new)
        return

    def _search_results_items_changed(self, event):
        """ Add/remove the items from the context.

        This should only get called when the user adds or deletes a row from the
        GUI. Changing the search term does not affect this.

        Unique names are enforced. The enforcement is done here because the
        variables are constructed before being put on the list so this is the
        first opportunity to check with the context.
        """
        # XXX: use the undo framework for this.

        self.context.defer_events = True

        for var in event.added:
            var.name = self._create_unique_key(var.name)
            self.context[var.name] = var.value

        for var in event.removed:
            del self.context[var.name]

        # This may have been triggered by creating a new var with the UI,
        # in which case, adding the new row needs to finish before we handle
        # the context events.

        def _enable_events(context):
            context.defer_events = False

        do_later(_enable_events, self.context)

    def _object_changed ( self, object ):
        """ Handles the 'object' trait being changed.
        """
        if object is not None:
            # Reset the current object to None, so we are ready for a new one:
            do_later( self.set, object = None )

            name = title = ''
            if isinstance( object, HasPayload ):
                name   = object.payload_name
                title  = object.payload_full_name
                object = object.payload

            viewers = self.viewers
            for i, viewer in enumerate( viewers ):
                if object is viewer.object:
                    if i == (len( viewers ) - 1):
                        return
                    del viewers[i]
                    break
            else:
                # Create the viewer:
                viewer = AnObjectViewer( name   = name,
                                         title  = title ).set(
                                         object = object )

                # Make sure the # of viewers doesn't exceed the maximum allowed:
                if len( viewers ) >= self.max_viewers:
                    del viewers[0]

            # Add the new viewer to the list of viewers (which will cause it to
            # appear as a new notebook page):
            viewers.append( viewer )

 def object_ok_changed ( self, info ):
     """ Handles the user clicking the OK button.
     """
     if self.is_save_file and exists( self.file_name ):
         do_later( self._file_already_exists )
     else:
         info.ui.dispose( True )

    def wait_statement(self, wtime, N=5):
        '''

        '''

        start_time = time.time()
        if self.debug:
            time.sleep(1)

        else:
            if isinstance(wtime, str):
                wtime = float(self._get_interpolation_value(wtime))

            if wtime > N:
                c = Condition()
                c.acquire()
                wd = WaitDialog(wtime=wtime,
                                    condition=c,
                                    parent=self)
                do_later(wd.edit_traits, kind='livemodal')
                c.wait()
                c.release()
                do_later(wd.close)
            else:
                time.sleep(wtime)

        msg = 'actual wait time %0.3f s' % (time.time() - start_time)
        self.log_statement(msg)

 def __init__ ( self, **traits ):
     """ Initializes the object.
     """
     super( ObjectDebugger, self ).__init__( **traits )
     self.module = CBModuleFile( path        = self.file_name,
                                 python_path = self.python_path,
                                 object      = self.object )
     do_later( self.select_object )

 def _profile_changed ( self, file_position ):
     """ Handles the 'profile' trait being changed.
     """
     if file_position is not None:
         do_later( self.set, profile = None )
         if file_position.class_name != '':
             if file_position.method_name != '':
                 self.add_method( file_position )
             else:
                 self.add_class( file_position )

    def _filter_changed(self, old_filter, new_filter):
        """Handles the current filter being changed."""

        if not self._no_notify:
            if new_filter is customize_filter:
                do_later(self._customize_filters, old_filter)
            else:
                self._update_filtering()
                self.model.invalidate()
                self.set_selection(self.selected)

    def on_auto_add_row(self):
        """ Handles the user modifying the current 'auto_add' mode row.
        """
        object = self.auto_add_row
        object.on_trait_change(self.on_auto_add_row, remove=True)

        self.auto_add_row = row = self.editor.create_new_row()
        if row is not None:
            row.on_trait_change(self.on_auto_add_row, dispatch="ui")

        do_later(self.editor.add_row, object, len(self.get_filtered_items()) - 2)

 def add_paths ( self, paths ):
     """ Adds paths to the work queue.
     """
     paths = [ cb_path.path for cb_path in paths
               if cb_path.path not in self.paths ]
     if len( paths ) > 0:
         self.paths.extend( paths )
         if self.lock is None:
             self.lock = Lock()
             do_later( self.start_thread )
         self.init_queue( paths )

    def _size_modified(self, event):
        """ Handles the size of the list control being changed.
        """
        control = self.control
        n = control.GetColumnCount()
        if n == 1:
            dx, dy = control.GetClientSizeTuple()
            control.SetColumnWidth(0, dx - 1)
        elif n > 1:
            do_later(self._set_column_widths)

        event.Skip()

    def _value_changed(self, value):
        """ Handles the history object's 'value' trait being changed.
        """
        if not self._dont_update:
            history = self.history
            try:
                self._dont_update = True
                self.value = history.value
                history.error = False
            except:
                history.error = True

            do_later(self.set, _dont_update=False)

    def _load_history(self, restore=None, select=True):
        """ Loads the current history list into the control.
        """
        control = self.control
        control.Freeze()

        if restore is None:
            restore = control.GetValue()

        control.Clear()
        for value in self.history:
            control.Append(value)

        self._restore = True
        do_later(self._thaw_value, restore, select)

    def warning(self, msg, decorate=True):
        '''
        '''

        if self.logger is not None:
            if self.use_warning_display:
                from src.helpers.gdisplays import gWarningDisplay
                if globalv.show_warnings:
                    if not gWarningDisplay.opened and not gWarningDisplay.was_closed:
                        do_later(gWarningDisplay.edit_traits)

                gWarningDisplay.add_text('{{:<{}s}} -- {{}}'.format(NAME_WIDTH).format(self.logger.name.strip(), msg))

            if decorate:
                msg = '****** {}'.format(msg)
            self._log_('warning', msg)

def sync_camera(reference_figure, target_figure):
    """ Synchronise the camera of the target_figure on the camera of the
        reference_figure.
    """
    reference_figure.scene._renderer.sync_trait('active_camera',
                        target_figure.scene._renderer)
    target_figure.scene._renderer.active_camera.on_trait_change(
            lambda: do_later(target_figure.scene.render))

    def _calculate_indicator_positions(self, shift=None):
        ccm = self.camera_calibration_manager

        zoom = self.parent.zoom
        src, name = self.video_manager.snapshot(identifier=zoom)
        ccm.image_factory(src=src)

        ccm.process_image()
        ccm.title = name

        cond = Condition()
        ccm.cond = cond
        cond.acquire()
        do_later(ccm.edit_traits, view='snapshot_view')
        if shift:
            self.stage_controller.linear_move(*shift, block=False)

        cond.wait()
        cond.release()