Source code for pyface.workbench.i_workbench_window_layout
# (C) Copyright 2005-2023 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!
""" The workbench window layout interface. """
from traits.api import Event, HasTraits, Instance, Interface, Str
from traits.api import provides
from .i_editor import IEditor
from .i_view import IView
[docs]class IWorkbenchWindowLayout(Interface):
""" The workbench window layout interface.
Window layouts are responsible for creating and managing the internal
structure of a workbench window (it knows how to add and remove views and
editors etc).
"""
# The Id of the editor area.
# FIXME v3: This is toolkit specific.
editor_area_id = Str()
# The workbench window that this is the layout for.
window = Instance("pyface.workbench.api.WorkbenchWindow")
# Events ----
# Fired when an editor is about to be opened (or restored).
editor_opening = Event(IEditor)
# Fired when an editor has been opened (or restored).
editor_opened = Event(IEditor)
# Fired when an editor is about to be closed.
editor_closing = Event(IEditor)
# Fired when an editor has been closed.
editor_closed = Event(IEditor)
# Fired when a view is about to be opened (or restored).
view_opening = Event(IView)
# Fired when a view has been opened (or restored).
view_opened = Event(IView)
# Fired when a view is about to be closed (*not* hidden!).
view_closing = Event(IView)
# Fired when a view has been closed (*not* hidden!).
view_closed = Event(IView)
# FIXME v3: The "just for convenience" returns are a really bad idea.
#
# Why? They allow the call to be used on the LHS of an expression...
# Because they have nothing to do with what the call is supposed to be
# doing, they are unlikely to be used (because they are so unexpected and
# inconsistently implemented), and only serve to replace two shorter lines
# of code with one long one, arguably making code more difficult to read.
[docs] def activate_editor(self, editor):
""" Activate an editor.
Returns the editor (just for convenience).
"""
[docs] def activate_view(self, view):
""" Activate a view.
Returns the view (just for convenience).
"""
[docs] def add_editor(self, editor, title):
""" Add an editor.
Returns the editor (just for convenience).
"""
[docs] def add_view(self, view, position=None, relative_to=None, size=(-1, -1)):
""" Add a view.
Returns the view (just for convenience).
"""
[docs] def close_editor(self, editor):
""" Close an editor.
Returns the editor (just for convenience).
"""
[docs] def close_view(self, view):
""" Close a view.
FIXME v3: Currently views are never 'closed' in the same sense as an
editor is closed. When we close an editor, we destroy its control.
When we close a view, we merely hide its control. I'm not sure if this
is a good idea or not. It came about after discussion with Dave P. and
he mentioned that some views might find it hard to persist enough state
that they can be re-created exactly as they were when they are shown
again.
Returns the view (just for convenience).
"""
[docs] def close(self):
""" Close the entire window layout.
FIXME v3: Should this be called 'destroy'?
"""
[docs] def create_initial_layout(self, parent):
""" Create the initial window layout.
Returns the layout.
"""
[docs] def contains_view(self, view):
""" Return True if the view exists in the window layout.
Note that this returns True even if the view is hidden.
"""
# Methods for saving and restoring the layout -------------------------#
[docs] def get_toolkit_memento(self):
""" Return any toolkit-specific data that should be part of the memento.
"""
[docs]@provides(IWorkbenchWindowLayout)
class MWorkbenchWindowLayout(HasTraits):
""" Mixin containing common code for toolkit-specific implementations. """
# 'IWorkbenchWindowLayout' interface -----------------------------------
# The Id of the editor area.
# FIXME v3: This is toolkit specific.
editor_area_id = Str()
# The workbench window that this is the layout for.
window = Instance("pyface.workbench.api.WorkbenchWindow")
# Events ----
# Fired when an editor is about to be opened (or restored).
editor_opening = Event(IEditor)
# Fired when an editor has been opened (or restored).
editor_opened = Event(IEditor)
# Fired when an editor is about to be closed.
editor_closing = Event(IEditor)
# Fired when an editor has been closed.
editor_closed = Event(IEditor)
# Fired when a view is about to be opened (or restored).
view_opening = Event(IView)
# Fired when a view has been opened (or restored).
view_opened = Event(IView)
# Fired when a view is about to be closed (*not* hidden!).
view_closing = Event(IView)
# Fired when a view has been closed (*not* hidden!).
view_closed = Event(IView)
# ------------------------------------------------------------------------
# 'IWorkbenchWindowLayout' interface.
# ------------------------------------------------------------------------
[docs] def add_view(self, view, position=None, relative_to=None, size=(-1, -1)):
""" Add a view. """
raise NotImplementedError()
[docs] def create_initial_layout(self, parent):
""" Create the initial window layout. """
raise NotImplementedError()
[docs] def contains_view(self, view):
""" Return True if the view exists in the window layout. """
raise NotImplementedError()
[docs] def refresh(self):
""" Refresh the window layout to reflect any changes. """
raise NotImplementedError()
[docs] def reset_editors(self):
""" Activate the first editor in every group. """
raise NotImplementedError()
[docs] def reset_views(self):
""" Activate the first view in every region. """
raise NotImplementedError()
# Methods for saving and restoring the layout -------------------------#
[docs] def get_view_memento(self):
""" Returns the state of the views. """
raise NotImplementedError()
[docs] def set_view_memento(self, memento):
""" Restores the state of the views. """
raise NotImplementedError()
[docs] def get_editor_memento(self):
""" Returns the state of the editors. """
raise NotImplementedError()
[docs] def set_editor_memento(self, memento):
""" Restores the state of the editors. """
raise NotImplementedError()
[docs] def get_toolkit_memento(self):
""" Return any toolkit-specific data that should be part of the memento.
"""
return None
# ------------------------------------------------------------------------
# Protected 'MWorkbenchWindowLayout' interface.
# ------------------------------------------------------------------------
def _get_editor_references(self):
""" Returns a reference to every editor. """
editor_manager = self.window.editor_manager
editor_references = {}
for editor in self.window.editors:
# Create the editor reference.
#
# If the editor manager returns 'None' instead of a resource
# reference then this editor will not appear the next time the
# workbench starts up. This is useful for things like text files
# that have an editor but have NEVER been saved.
editor_reference = editor_manager.get_editor_memento(editor)
if editor_reference is not None:
editor_references[editor.id] = editor_reference
return editor_references
