Source code for pyface.tasks.i_editor_area_pane

# (C) Copyright 2005-2022 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in 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!

import logging


from traits.api import (
    Bool,
    Callable,
    Dict,
    Event,
    File,
    HasTraits,
    Instance,
    List,
    Str,
)


from pyface.tasks.i_editor import IEditor
from pyface.tasks.i_task_pane import ITaskPane

# Logger.
logger = logging.getLogger(__name__)


[docs]class IEditorAreaPane(ITaskPane): """ A central pane that contains tabbed editors. There are currently two implementations of this interface in Tasks. EditorAreaPane provides a simple, tabbed editor area. AdvancedEditorAreaPane additionally permits arbitrary splitting of the editor area so that editors can be displayed side-by-side. """ # 'IEditorAreaPane' interface -----------------------------------------# #: The currently active editor. active_editor = Instance(IEditor) #: The list of all the visible editors in the pane. editors = List(IEditor) #: A list of extensions for file types to accept via drag and drop. #: Note: This functionality is provided because it is very common, but #: drag and drop support is in general highly toolkit-specific. If more #: sophisticated support is required, subclass an editor area #: implementation. file_drop_extensions = List(Str) #: A file with a supported extension was dropped into the editor area. file_dropped = Event(File) #: Whether to hide the tab bar when there is only a single editor. hide_tab_bar = Bool(False) # ------------------------------------------------------------------------ # 'IEditorAreaPane' interface. # ------------------------------------------------------------------------
[docs] def activate_editor(self, editor): """ Activates the specified editor in the pane. """
[docs] def add_editor(self, editor): """ Adds an editor to the pane. """
[docs] def create_editor(self, obj, factory=None): """ Creates an editor for an object. If a factory is specified, it will be used instead of the editor factory registry. Otherwise, this method will return None if a suitable factory cannot be found in the registry. Note that the editor is not added to the pane. """
[docs] def edit(self, obj, factory=None, use_existing=True): """ Edit an object. This is a convenience method that creates and adds an editor for the specified object. If 'use_existing' is set and the object is already being edited, then that editor will be activated and a new editor will not be created. Returns the (possibly new) editor for the object. """
[docs] def get_editor(self, obj): """ Returns the editor for an object. Returns None if the object is not being edited. """
[docs] def get_factory(self, obj): """ Returns an editor factory suitable for editing an object. Returns None if there is no such editor factory. """
[docs] def register_factory(self, factory, filter): """ Registers a factory for creating editors. The 'factory' parameter is a callabe of form: callable(editor_area=editor_area, obj=obj) -> IEditor Often, factory will be a class that provides the 'IEditor' interface. The 'filter' parameter is a callable of form: callable(obj) -> bool that indicates whether the editor factory is suitable for an object. If multiple factories apply to a single object, it is undefined which factory is used. On the other hand, multiple filters may be registered for a single factory, in which case only one must apply for the factory to be selected. """
[docs] def remove_editor(self, editor): """ Removes an editor from the pane. """
[docs] def unregister_factory(self, factory): """ Unregisters a factory for creating editors. """
[docs]class MEditorAreaPane(HasTraits): # 'IEditorAreaPane' interface -----------------------------------------# active_editor = Instance(IEditor) editors = List(IEditor) file_drop_extensions = List(Str) file_dropped = Event(File) hide_tab_bar = Bool(False) # Protected traits ----------------------------------------------------- _factory_map = Dict(Callable, List(Callable)) # ------------------------------------------------------------------------ # 'IEditorAreaPane' interface. # ------------------------------------------------------------------------
[docs] def create_editor(self, obj, factory=None): """ Creates an editor for an object. """ if factory is None: factory = self.get_factory(obj) if factory is not None: return factory(editor_area=self, obj=obj) return None
[docs] def edit(self, obj, factory=None, use_existing=True): """ Edit an object. """ if use_existing: # Is the object already being edited in the window? editor = self.get_editor(obj) if editor is not None: self.activate_editor(editor) return editor # If not, create an editor for it. editor = self.create_editor(obj, factory) if editor is None: logger.warning("Cannot create editor for obj %r", obj) else: self.add_editor(editor) self.activate_editor(editor) return editor
[docs] def get_editor(self, obj): """ Returns the editor for an object. """ for editor in self.editors: if editor.obj == obj: return editor return None
[docs] def get_factory(self, obj): """ Returns an editor factory suitable for editing an object. """ for factory, filters in self._factory_map.items(): for filter_ in filters: # FIXME: We should swallow exceptions, but silently? try: if filter_(obj): return factory except: pass return None
[docs] def register_factory(self, factory, filter): """ Registers a factory for creating editors. """ self._factory_map.setdefault(factory, []).append(filter)
[docs] def unregister_factory(self, factory): """ Unregisters a factory for creating editors. """ if factory in self._factory_map: del self._factory_map[factory]