#------------------------------------------------------------------------------
#
#  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/07/2004
#
#------------------------------------------------------------------------------

""" Defines the abstract Editor class, which represents an editing control for
    an object trait in a Traits-based user interface.
"""

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



from traits.api import (Any, Bool, HasPrivateTraits, HasTraits, Instance, Property,
    ReadOnly, Str, Trait, TraitError, TraitListEvent, Undefined,
    cached_property)

from traits.trait_base import not_none

from .editor_factory import EditorFactory

from .context_value import ContextValue

from .undo import UndoItem

from .item import Item

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

# Reference to an EditorFactory object
factory_trait = Trait( EditorFactory )

#-------------------------------------------------------------------------------
#  'Editor' abstract base class:
#-------------------------------------------------------------------------------

class Editor ( HasPrivateTraits ):
    """ Represents an editing control for an object trait in a Traits-based
        user interface.
    """

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

    # The UI (user interface) this editor is part of:
    ui = Instance( 'traitsui.ui.UI' )

    # Full name of the object the editor is editing (e.g. 'object.link1.link2'):
    object_name = Str( 'object' )

    # The object this editor is editing (e.g. object.link1.link2):
    object = Instance( HasTraits )

    # The name of the trait this editor is editing (e.g. 'value'):
    name = ReadOnly

    # The context object the editor is editing (e.g. object):
    context_object = Property

    # The extended name of the object trait being edited. That is,
    # 'object_name.name' minus the context object name at the beginning. For
    # example: 'link1.link2.value':
    extended_name = Property

    # Original value of object.name (e.g. object.link1.link2.value):
    old_value = Any

    # Text description of the object trait being edited:
    description = ReadOnly

    # The Item object used to create this editor:
    item = Instance( Item, () )

    # The GUI widget defined by this editor:
    control = Any

    # The GUI label (if any) defined by this editor:
    label_control = Any

    # Is the underlying GUI widget enabled?
    enabled = Bool( True )

    # Is the underlying GUI widget visible?
    visible = Bool( True )

    # Is the underlying GUI widget scrollable?
    scrollable = Bool( False )

    # The EditorFactory used to create this editor:
    factory = factory_trait

    # Is the editor updating the object.name value?
    updating = Bool( False )

    # Current value for object.name:
    value = Property

    # Current value of object trait as a string:
    str_value = Property

    # The trait the editor is editing (not its value, but the trait itself):
    value_trait = Property

    # The current editor invalid state status:
    invalid = Bool( False )

    #---------------------------------------------------------------------------
    #  Initializes the object:
    #---------------------------------------------------------------------------

    def __init__ ( self, parent, **traits ):
        """ Initializes the editor object.
        """
        HasPrivateTraits.__init__( self, **traits )
        try:
            self.old_value = getattr( self.object, self.name )
        except AttributeError:
            ctrait = self.object.base_trait(self.name)
            if ctrait.type == 'event' or self.name == 'spring':
                # Getting the attribute will fail for 'Event' traits:
                self.old_value = Undefined
            else :
                raise

        # Synchronize the application invalid state status with the editor's:
        self.sync_value( self.factory.invalid, 'invalid', 'from' )

    #---------------------------------------------------------------------------
    #  Finishes editor set-up:
    #---------------------------------------------------------------------------

    def prepare ( self, parent ):
        """ Finishes setting up the editor.
        """
        name = self.extended_name
        if name != 'None':
            self.context_object.on_trait_change( self._update_editor, name,
                                                 dispatch = 'ui' )
        self.init( parent )
        self._sync_values()
        self.update_editor()

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

    def init ( self, parent ):
        """ Finishes initializing the editor by creating the underlying toolkit
            widget.
        """
        raise NotImplementedError

    #---------------------------------------------------------------------------
    #  Assigns focus to the editor's underlying toolkit widget:
    #---------------------------------------------------------------------------

    def set_focus ( self ):
        """ Assigns focus to the editor's underlying toolkit widget.
        """
        raise NotImplementedError

    #---------------------------------------------------------------------------
    #  Disposes of the contents of an editor:
    #---------------------------------------------------------------------------

    def dispose ( self ):
        """ Disposes of the contents of an editor.
        """
        if self.ui is None:
            return

        name = self.extended_name
        if name != 'None':
            self.context_object.on_trait_change( self._update_editor, name,
                                                 remove = True )

        if self._user_from is not None:
            for name, handler in self._user_from:
                self.on_trait_change( handler, name, remove = True )

        if self._user_to is not None:
            for object, name, handler in self._user_to:
                object.on_trait_change( handler, name, remove = True )

        # Break linkages to references we no longer need:
        self.object = self.ui = self.item = self.factory = self.control = \
        self.label_control = self.old_value = self._context_object = None

    #---------------------------------------------------------------------------
    #  Returns the context object the editor is using (Property implementation):
    #---------------------------------------------------------------------------

    @cached_property
    def _get_context_object ( self ):
        """ Returns the context object the editor is using (Property
            implementation).
        """
        object_name = self.object_name
        context_key = object_name.split( '.', 1 )[0]
        if (object_name != '') and (context_key in self.ui.context):
            return self.ui.context[ context_key ]

        # This handles the case of a 'ListItemProxy', which is not in the
        # ui.context, but is the editor 'object':
        return self.object

    #---------------------------------------------------------------------------
    #  Returns the extended trait name being edited (Property implementation):
    #---------------------------------------------------------------------------

    @cached_property
    def _get_extended_name ( self ):
        """ Returns the extended trait name being edited (Property
            implementation).
        """
        return ('%s.%s' % ( self.object_name, self.name )).split( '.', 1 )[1]

    #---------------------------------------------------------------------------
    #  Returns the trait the editor is editing (Property implementation):
    #---------------------------------------------------------------------------

    def _get_value_trait ( self ):
        """ Returns the trait the editor is editing (Property implementation).
        """
        return self.object.trait( self.name )

    #---------------------------------------------------------------------------
    #  Gets/Sets the associated object trait's value:
    #---------------------------------------------------------------------------

    def _get_value ( self ):
        return getattr( self.object, self.name, Undefined )

    def _set_value ( self, value ):
        if self.ui and self.name != 'None':
            self.ui.do_undoable( self.__set_value, value )

    def __set_value ( self, value ):
        self._no_update = True
        try:
            try:
                handler  = self.ui.handler
                obj_name = self.object_name
                name     = self.name
                method   = (getattr( handler, '%s_%s_setattr' % ( obj_name,
                                              name ), None ) or
                            getattr( handler, '%s_setattr' % name, None ) or
                            getattr( handler, 'setattr' ))
                method( self.ui.info, self.object, name, value )
            except TraitError as excp:
                self.error( excp )
                raise
        finally:
            self._no_update = False

    #---------------------------------------------------------------------------
    #  Returns the text representation of a specified object trait value:
    #---------------------------------------------------------------------------

    def string_value ( self, value, format_func = None ):
        """ Returns the text representation of a specified object trait value.

            If the **format_func** attribute is set on the editor factory, then
            this method calls that function to do the formatting.  If the
            **format_str** attribute is set on the editor factory, then this
            method uses that string for formatting. If neither attribute is
            set, then this method just calls the built-in unicode() function.
        """
        factory = self.factory
        if factory.format_func is not None:
            return factory.format_func( value )

        if factory.format_str != '':
            return factory.format_str % value

        if format_func is not None:
            return format_func( value )

        return str( value )

    #---------------------------------------------------------------------------
    #  Returns the text representation of the object trait:
    #---------------------------------------------------------------------------

    def _get_str_value ( self ):
        """ Returns the text representation of the object trait.
        """
        return self.string_value( getattr( self.object, self.name, Undefined ) )

    #---------------------------------------------------------------------------
    #  Returns the text representation of a specified value:
    #---------------------------------------------------------------------------

    def _str ( self, value ):
        """ Returns the text representation of a specified value.
        """
        # In Unicode!
        return str( value )

    #---------------------------------------------------------------------------
    #  Handles an error that occurs while setting the object's trait value:
    #
    #  (Should normally be overridden in a subclass)
    #---------------------------------------------------------------------------

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

    #---------------------------------------------------------------------------
    #  Performs updates when the object trait changes:
    #---------------------------------------------------------------------------

    def _update_editor ( self, object, name, old_value, new_value ):
        """ Performs updates when the object trait changes.
        """
        # If background threads have modified the trait the editor is bound to,
        # their trait notifications are queued to the UI thread. It is possible
        # that by the time the UI thread dispatches these events, the UI the
        # editor is part of has already been closed. So we need to check if we
        # are still bound to a live UI, and if not, exit immediately:
        if self.ui is None:
            return

        # If the notification is for an object different than the one actually
        # being edited, it is due to editing an item of the form:
        # object.link1.link2.name, where one of the 'link' objects may have
        # been modified. In this case, we need to rebind the current object
        # being edited:
        if object is not self.object:
            self.object = eval( self.object_name, globals(), self.ui.context )

        # If the editor has gone away for some reason, disconnect and exit:
        if self.control is None:
            self.context_object.on_trait_change( self._update_editor,
                                    self.extended_name, remove = True )
            return

        # Log the change that was made (as long as it is not for an event):
        if object.base_trait( name ).type != 'event':
            self.log_change( self.get_undo_item, object, name,
                                                 old_value, new_value )

        # If the change was not caused by the editor itself:
        if not self._no_update:
            # Update the editor control to reflect the current object state:
            self.update_editor()

    #---------------------------------------------------------------------------
    #  Logs a change made in the editor:
    #---------------------------------------------------------------------------

    def log_change ( self, undo_factory, *undo_args ):
        """ Logs a change made in the editor.
        """
        # Indicate that the contents of the user interface have been changed:
        ui          = self.ui
        ui.modified = True

        # Create an undo history entry if we are maintaining a history:
        undoable = ui._undoable
        if undoable >= 0:
            history = ui.history
            if history is not None:
                item = undo_factory( *undo_args )
                if item is not None:
                    if undoable == history.now:
                        # Create a new undo transaction:
                        history.add( item )
                    else:
                        # Extend the most recent undo transaction:
                        history.extend( item )

    #---------------------------------------------------------------------------
    #  Updates the editor when the object trait changes external to the editor:
    #
    #  (Should normally be overridden in a subclass)
    #---------------------------------------------------------------------------

    def update_editor ( self ):
        """ Updates the editor when the object trait changes externally to the
            editor.
        """
        pass

    #---------------------------------------------------------------------------
    #  Creates an undo history entry:
    #
    #  (Can be overridden in a subclass for special value types)
    #---------------------------------------------------------------------------

    def get_undo_item ( self, object, name, old_value, new_value ):
        """ Creates an undo history entry.
        """
        return UndoItem( object    = object,
                         name      = name,
                         old_value = old_value,
                         new_value = new_value )

    #---------------------------------------------------------------------------
    #  Returns a tuple of the form ( context_object, name[.name...], callable )
    #  for a specified extended name of the form: name or
    #  context_object_name.name[.name...]:
    #---------------------------------------------------------------------------

    def parse_extended_name ( self, name ):
        """ Returns a tuple of the form ( context_object, 'name[.name...],
            callable ) for a specified extended name of the form: 'name' or
            'context_object_name.name[.name...]'.
        """
        col = name.find( '.' )
        if col < 0:
            object = self.context_object
        else:
            object, name = self.ui.context[ name[ : col ] ], name[ col + 1: ]

        return ( object, name, eval( "lambda obj=object: obj." + name ) )

    #---------------------------------------------------------------------------
    #  Initializes and synchronizes (as needed) editor traits with the value of
    #  corresponding factory traits:
    #---------------------------------------------------------------------------

    def _sync_values ( self ):
        """ Initializes and synchronizes (as needed) editor traits with the
            value of corresponding factory traits.
        """
        factory = self.factory
        for name, trait in factory.traits( sync_value = not_none ):
            value = getattr( factory, name )
            if isinstance( value, ContextValue ):
                self_trait = self.trait( name )
                self.sync_value( value.name, name,
                                 self_trait.sync_value or trait.sync_value,
                                 self_trait.is_list is True )
            elif value is not Undefined:
                setattr( self, name, value )

    #---------------------------------------------------------------------------
    #  Sets/Unsets synchronization between an editor trait and a user object
    #  trait:
    #---------------------------------------------------------------------------

    def sync_value ( self, user_name, editor_name, mode = 'both',
                           is_list = False ):
        """ Sets or unsets synchronization between an editor trait and a user
            object trait.
        """
        if user_name != '':
            key = '%s:%s' % ( user_name, editor_name )

            if self._no_trait_update is None:
                self._no_trait_update = {}

            user_ref = 'user_object'
            col      = user_name.find( '.' )
            if col < 0:
                user_object = self.context_object
                xuser_name  = user_name
            else:
                user_object = self.ui.context[ user_name[ : col ] ]
                user_name   = xuser_name = user_name[ col + 1: ]
                col         = user_name.rfind( '.' )
                if col >= 0:
                    user_ref += ('.' + user_name[ : col ])
                    user_name = user_name[ col + 1: ]

            user_value = compile( '%s.%s' % ( user_ref, user_name ),
                                  '<string>', 'eval' )
            user_ref   = compile( user_ref, '<string>', 'eval' )

            if mode in ( 'from', 'both' ):

                def user_trait_modified ( new ):
                    # Need this to include 'user_object' in closure:
                    user_object
                    if key not in self._no_trait_update:
                        self._no_trait_update[ key ] = None
                        try:
                            setattr( self, editor_name, new )
                        except:
                            from traitsui.api import raise_to_debug
                            raise_to_debug()
                        del self._no_trait_update[ key ]

                user_object.on_trait_change( user_trait_modified, xuser_name )

                if self._user_to is None:
                    self._user_to = []
                self._user_to.append( ( user_object, xuser_name,
                                        user_trait_modified ) )

                if is_list:

                    def user_list_modified ( event ):
                        if isinstance( event, TraitListEvent ):
                            if key not in self._no_trait_update:
                                self._no_trait_update[ key ] = None
                                n = event.index
                                try:
                                    getattr( self, editor_name )[
                                        n: n + len(event.removed)] = event.added
                                except:
                                    from traitsui.api import raise_to_debug
                                    raise_to_debug()
                                del self._no_trait_update[ key ]

                    user_object.on_trait_change( user_list_modified,
                                    xuser_name + '_items' )
                    self._user_to.append( ( user_object, xuser_name + '_items',
                                            user_list_modified ) )

                try:
                    setattr( self, editor_name, eval( user_value ) )
                except:
                    from traitsui.api import raise_to_debug
                    raise_to_debug()

            if mode in ( 'to', 'both' ):

                def editor_trait_modified ( new ):
                    # Need this to include 'user_object' in closure:
                    user_object
                    if key not in self._no_trait_update:
                        self._no_trait_update[ key ] = None
                        try:
                            setattr( eval( user_ref ), user_name, new )
                        except:
                            from traitsui.api import raise_to_debug
                            raise_to_debug()
                        del self._no_trait_update[ key ]

                self.on_trait_change( editor_trait_modified, editor_name )

                if self._user_from is None:
                    self._user_from = []
                self._user_from.append( ( editor_name, editor_trait_modified ) )

                if is_list:

                    def editor_list_modified ( event ):
                        # Need this to include 'user_object' in closure:
                        user_object
                        if key not in self._no_trait_update:
                            self._no_trait_update[ key ] = None
                            n = event.index
                            try:
                                eval( user_value )[ n:
                                    n + len( event.removed ) ] = event.added
                            except:
                                from traitsui.api import raise_to_debug
                                raise_to_debug()
                            del self._no_trait_update[ key ]

                    self.on_trait_change( editor_list_modified,
                             editor_name + '_items' )
                    self._user_from.append( ( editor_name + '_items',
                                              editor_list_modified ) )

                if mode == 'to':
                    try:
                        setattr( eval( user_ref ), user_name,
                                 getattr( self, editor_name ) )
                    except:
                        from traitsui.api import raise_to_debug
                        raise_to_debug()

    #-- 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.
        """
        pass

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

    def save_prefs ( self ):
        """ Returns any user preference information associated with the editor.
        """
        return None

