#-------------------------------------------------------------------------
#
#  Copyright (c) 2005, Enthought, Inc.
#  All rights reserved.
#
#  This software is provided without warranty under the terms of the BSD
#  license included in enthought/LICENSE.txt and may be redistributed only
#  under the conditions described in the aforementioned license.  The license
#  is also available online at http://www.enthought.com/licenses/BSD.txt
#
#  Thanks for using Enthought open source!
#
#  Author: David C. Morrill
#  Date:   10/21/2004
#
#-------------------------------------------------------------------------

""" Defines a text editor which displays a text field and maintains a history
    of previously entered values.
"""

#-------------------------------------------------------------------------
#  Imports:
#-------------------------------------------------------------------------

from traits.api \
    import Any, on_trait_change

from pyface.timer.api \
    import do_later

from editor \
    import Editor

from history_control \
    import HistoryControl

#-------------------------------------------------------------------------
#  '_HistoryEditor' class:
#-------------------------------------------------------------------------


class _HistoryEditor(Editor):
    """ Simple style text editor, which displays a text field and maintains a
        history of previously entered values, the maximum number of which is
        specified by the 'entries' trait of the HistoryEditor factory.
    """

    #-------------------------------------------------------------------------
    #  Trait definitions:
    #-------------------------------------------------------------------------

    # The history control:
    history = Any

    #-------------------------------------------------------------------------
    #  Finishes initializing the editor by creating the underlying toolkit
    #  widget:
    #-------------------------------------------------------------------------

    def init(self, parent):
        """ Finishes initializing the editor by creating the underlying toolkit
            widget.
        """
        self.history = history = HistoryControl(
            value=self.value,
            entries=self.factory.entries,
            auto_set=self.factory.auto_set)
        self.control = history.create_control(parent)

        self.set_tooltip()

    def dispose(self):
        """ Disposes of the contents of an editor.
        """
        self.history.dispose()
        self.history = None

        super(_HistoryEditor, self).dispose()

    #-------------------------------------------------------------------------
    #  Handles the user entering input data in the edit control:
    #-------------------------------------------------------------------------

    @on_trait_change('history:value')
    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)

    #-------------------------------------------------------------------------
    #  Updates the editor when the object trait changes external to the editor:
    #-------------------------------------------------------------------------

    def update_editor(self):
        """ Updates the editor when the object trait changes externally to the
            editor.
        """
        if not self._dont_update:
            self._dont_update = True
            self.history.value = self.value
            self.history.error = False
            self._dont_update = False

    #-------------------------------------------------------------------------
    #  Handles an error that occurs while setting the object's trait value:
    #-------------------------------------------------------------------------

    def error(self, excp):
        """ Handles an error that occurs while setting the object's trait value.
        """
        pass

    #-- UI preference save/restore interface ---------------------------------

    #-------------------------------------------------------------------------
    #  Restores any saved user preference information associated with the
    #  editor:
    #-------------------------------------------------------------------------

    def restore_prefs(self, prefs):
        """ Restores any saved user preference information associated with the
            editor.
        """
        self.history.history = \
            prefs.get('history', [])[: self.factory.entries]

    #-------------------------------------------------------------------------
    #  Returns any user preference information associated with the editor:
    #-------------------------------------------------------------------------

    def save_prefs(self):
        """ Returns any user preference information associated with the editor.
        """
        # If the view closed successfully, try to update the history with the
        # current value:
        if self.ui.result:
            self._dont_update = True
            self.history.set_value(self.value)
            self._dont_update = False

        return {'history': self.history.history[:]}

# EOF #########################################################################
