Source code for traitsui.ui
# (C) Copyright 2004-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!
""" Defines the UI class used to represent an active traits-based user
interface.
"""
import shelve
import os
from warnings import warn
from pyface.ui_traits import Image
from traits.api import (
Any,
Bool,
Callable,
Dict,
Event,
HasPrivateTraits,
Instance,
Int,
List,
Property,
Str,
TraitError,
observe,
)
from traits.trait_base import traits_home, is_str
from .editor import Editor
from .view_elements import ViewElements
from .handler import Handler, ViewHandler
from .toolkit import toolkit
from .ui_info import UIInfo
from .item import Item
from .group import Group, ShadowGroup
# List of **kind** types for views that must have a **parent** window specified
kind_must_have_parent = ("panel", "subpanel")
[docs]class UI(HasPrivateTraits):
"""Information about the user interface for a View."""
# -------------------------------------------------------------------------
# Trait definitions:
# -------------------------------------------------------------------------
#: The ViewElements object from which this UI resolves Include items
view_elements = Instance(ViewElements)
#: Context objects that the UI is editing
context = Dict(Str, Any)
#: Handler object used for event handling
handler = Instance(Handler)
#: View template used to construct the user interface
view = Instance("traitsui.view.View")
#: Panel or dialog associated with the user interface
control = Any()
#: The parent UI (if any) of this UI
parent = Instance("UI")
#: Toolkit-specific object that "owns" **control**
owner = Any()
#: UIInfo object containing context or editor objects
info = Instance(UIInfo)
#: Result from a modal or wizard dialog:
result = Bool(False)
#: Undo and Redo history
history = Any()
#: The KeyBindings object (if any) for this UI:
key_bindings = Property(depends_on=["view._key_bindings", "context"])
#: The unique ID for this UI for persistence
id = Str()
#: Have any modifications been made to UI contents?
modified = Bool(False)
#: Event when the user interface has changed
updated = Event(Bool)
#: Title of the dialog, if any
title = Str()
#: The ImageResource of the icon, if any
icon = Image
#: Should the created UI have scroll bars?
scrollable = Bool(False)
#: The number of currently pending editor error conditions
errors = Int()
#: The code used to rebuild an updated user interface
rebuild = Callable()
#: Set to True when the UI has finished being destroyed.
destroyed = Bool(False)
# -- Private Traits -------------------------------------------------------
#: Original context when used with a modal dialog
_context = Dict(Str, Any)
#: Copy of original context used for reverting changes
_revert = Dict(Str, Any)
#: List of methods to call once the user interface is created
_defined = List()
#: List of (visible_when,Editor) pairs
_visible = List()
#: List of (enabled_when,Editor) pairs
_enabled = List()
#: List of (checked_when,Editor) pairs
_checked = List()
#: Search stack used while building a user interface
_search = List()
#: List of dispatchable Handler methods
_dispatchers = List()
#: List of editors used to build the user interface
_editors = List()
#: List of names bound to the **info** object
_names = List()
#: Index of currently the active group in the user interface
_active_group = Int()
#: List of top-level groups used to build the user interface
_groups = Property()
_groups_cache = Any()
#: Count of levels of nesting for undoable actions
_undoable = Int(-1)
#: Code used to rebuild an updated user interface
_rebuild = Callable()
#: The statusbar listeners that have been set up:
_statusbar = List()
#: Control which gets focus after UI is created
#: Note: this does not track focus after UI creation
#: only used by Qt backend.
_focus_control = Any()
#: Does the UI contain any scrollable widgets?
#:
#: The _scrollable trait is set correctly, but not used currently because
#: its value is arrived at too late to be of use in building the UI.
_scrollable = Bool(False)
#: Cache for key bindings.
_key_bindings = Instance("traitsui.key_bindings.KeyBindings")
#: List of traits that are reset when a user interface is recycled
#: (i.e. rebuilt).
recyclable_traits = [
"_context",
"_revert",
"_defined",
"_visible",
"_enabled",
"_checked",
"_search",
"_dispatchers",
"_editors",
"_names",
"_active_group",
"_undoable",
"_rebuild",
"_groups_cache",
"_key_bindings",
"_focus_control",
]
#: List of additional traits that are discarded when a user interface is
#: disposed.
disposable_traits = [
"view_elements",
"info",
"handler",
"context",
"view",
"history",
"key_bindings",
"icon",
"rebuild",
]
[docs] def traits_init(self):
"""Initializes the traits object."""
self.info = UIInfo(ui=self)
self.handler.init_info(self.info)
[docs] def ui(self, parent, kind):
"""Creates a user interface from the associated View template object."""
if (parent is None) and (kind in kind_must_have_parent):
kind = "live"
self.view.on_trait_change(
self._updated_changed, "updated", dispatch="ui"
)
self.rebuild = getattr(toolkit(), "ui_" + kind)
self.rebuild(self, parent)
[docs] def dispose(self, result=None, abort=False):
"""Disposes of the contents of a user interface."""
if self.parent is not None:
self.parent.errors -= self.errors
if result is not None:
self.result = result
# Only continue if the view has not already been disposed of:
if self.control is not None:
# Save the user preference information for the user interface:
if not abort:
self.save_prefs()
# Finish disposing of the user interface:
self.finish()
[docs] def recycle(self):
"""Recycles the user interface prior to rebuilding it."""
# Reset all user interface editors:
self.reset(destroy=False)
# Discard any context object associated with the ui view control:
self.control._object = None
# Reset all recyclable traits:
self.reset_traits(self.recyclable_traits)
[docs] def finish(self):
"""Finishes disposing of a user interface."""
# Destroy the control early to silence cascade events when the UI
# enters an inconsistent state.
toolkit().destroy_control(self.control)
# Reset the contents of the user interface
self.reset(destroy=False)
# Make sure that 'visible', 'enabled', and 'checked' handlers are not
# called after the editor has been disposed:
for object in self.context.values():
object.on_trait_change(self._evaluate_when, remove=True)
# Notify the handler that the view has been closed:
self.handler.closed(self.info, self.result)
# Clear the back-link from the UIInfo object to us:
self.info.ui = None
# Destroy the view control:
self.control._object = None
self.control = None
# Dispose of any KeyBindings object we reference:
if self._key_bindings is not None:
self._key_bindings.dispose()
# Break the linkage to any objects in the context dictionary:
self.context.clear()
# Remove specified symbols from our dictionary to aid in clean-up:
self.reset_traits(self.recyclable_traits)
self.reset_traits(self.disposable_traits)
self.destroyed = True
[docs] def reset(self, destroy=True):
"""Resets the contents of a user interface."""
for editor in self._editors:
if editor._ui is not None:
# Propagate result to enclosed ui objects:
editor._ui.result = self.result
editor.dispose()
# Zap the control. If there are pending events for the control in
# the UI queue, the editor's '_update_editor' method will see that
# the control is None and discard the update request:
editor.control = None
# Remove any statusbar listeners that have been set up:
for object, handler, name in self._statusbar:
object.observe(handler, name, remove=True, dispatch="ui")
del self._statusbar[:]
if destroy:
toolkit().destroy_children(self.control)
for dispatcher in self._dispatchers:
dispatcher.remove()
[docs] def find(self, include):
"""Finds the definition of the specified Include object in the current
user interface building context.
"""
context = self.context
result = None
# Get the context 'object' (if available):
if len(context) == 1:
object = list(context.values())[0]
else:
object = context.get("object")
# Try to use our ViewElements objects:
ve = self.view_elements
# If none specified, try to get it from the UI context:
if (ve is None) and (object is not None):
# Use the context object's ViewElements (if available):
ve = object.trait_view_elements()
# Ask the ViewElements to find the requested item for us:
if ve is not None:
result = ve.find(include.id, self._search)
# If not found, then try to search the 'handler' and 'object' for a
# method we can call that will define it:
if result is None:
handler = context.get("handler")
if handler is not None:
method = getattr(handler, include.id, None)
if callable(method):
result = method()
if (result is None) and (object is not None):
method = getattr(object, include.id, None)
if callable(method):
result = method()
return result
[docs] def pop_level(self, level):
"""Restores a previously pushed search stack level."""
del self._search[: len(self._search) - level]
[docs] def prepare_ui(self):
"""Performs all processing that occurs after the user interface is
created.
"""
# Invoke all of the editor 'name_defined' methods we've accumulated:
info = self.info.trait_set(initialized=False)
for method in self._defined:
method(info)
# Then reset the list, since we don't need it anymore:
del self._defined[:]
# Synchronize all context traits with associated editor traits:
self.sync_view()
# Hook all keyboard events:
toolkit().hook_events(self, self.control, "keys", self.key_handler)
# Hook all events if the handler is an extended 'ViewHandler':
handler = self.handler
if isinstance(handler, ViewHandler):
toolkit().hook_events(self, self.control)
# Invoke the handler's 'init' method, and abort if it indicates
# failure:
started = handler.init(info)
if started is False:
raise TraitError("User interface creation aborted")
elif not isinstance(started, bool):
raise ValueError(
"Handler.init() must return True or False, but instead "
f"returned {started}."
)
# For each Handler method whose name is of the form
# 'object_name_changed', where 'object' is the name of an object in the
# UI's 'context', create a trait notification handler that will call
# the method whenever 'object's 'name' trait changes. Also invoke the
# method immediately so initial user interface state can be correctly
# set:
context = self.context
for name in self._each_trait_method(handler):
if name[-8:] == "_changed":
prefix = name[:-8]
col = prefix.find("_", 1)
if col >= 0:
object = context.get(prefix[:col])
if object is not None:
method = getattr(handler, name)
trait_name = prefix[col + 1 :]
self._dispatchers.append(
Dispatcher(method, info, object, trait_name)
)
if object.base_trait(trait_name).type != "event":
method(info)
# If there are any Editor object's whose 'visible', 'enabled' or
# 'checked' state is controlled by a 'visible_when', 'enabled_when' or
# 'checked_when' expression, set up an 'anytrait' changed notification
# handler on each object in the 'context' that will cause the
# 'visible', 'enabled' or 'checked' state of each affected Editor to be
# set. Also trigger the evaluation immediately, so the visible,
# enabled or checked state of each Editor can be correctly initialized:
if (len(self._visible) + len(self._enabled) + len(self._checked)) > 0:
for object in context.values():
object.on_trait_change(self._evaluate_when, dispatch="ui")
self._do_evaluate_when(at_init=True)
# Indicate that the user interface has been initialized:
info.initialized = True
[docs] def sync_view(self):
"""Synchronize context object traits with view editor traits."""
for name, object in self.context.items():
self._sync_view(name, object, "sync_to_view", "from")
self._sync_view(name, object, "sync_from_view", "to")
self._sync_view(name, object, "sync_with_view", "both")
def _sync_view(self, name, object, metadata, direction):
info = self.info
for trait_name, trait in object.traits(**{metadata: is_str}).items():
for sync in getattr(trait, metadata).split(","):
try:
editor_id, editor_name = [
item.strip() for item in sync.split(".")
]
except:
raise TraitError(
"The '%s' metadata for the '%s' trait in "
"the '%s' context object should be of the form: "
"'id1.trait1[,...,idn.traitn]."
% (metadata, trait_name, name)
)
editor = getattr(info, editor_id, None)
if editor is not None:
editor.sync_value(
"%s.%s" % (name, trait_name), editor_name, direction
)
else:
raise TraitError(
"No editor with id = '%s' was found for "
"the '%s' metadata for the '%s' trait in the '%s' "
"context object."
% (editor_id, metadata, trait_name, name)
)
[docs] def get_extended_value(self, name):
"""Gets the current value of a specified extended trait name."""
names = name.split(".")
if len(names) > 1:
value = self.context[names[0]]
del names[0]
else:
value = self.context["object"]
for name in names:
value = getattr(value, name)
return value
[docs] def restore_prefs(self):
"""Retrieves and restores any saved user preference information
associated with the UI.
"""
id = self.id
if id != "":
db = self.get_ui_db()
if db is not None:
try:
ui_prefs = db.get(id)
db.close()
return self.set_prefs(ui_prefs)
except:
pass
return None
[docs] def set_prefs(self, prefs):
"""Sets the values of user preferences for the UI."""
if isinstance(prefs, dict):
info = self.info
for name in self._names:
editor = getattr(info, name, None)
if isinstance(editor, Editor) and (editor.ui is self):
editor_prefs = prefs.get(name)
if editor_prefs is not None:
editor.restore_prefs(editor_prefs)
if self.key_bindings is not None:
key_bindings = prefs.get("$")
if key_bindings is not None:
self.key_bindings.merge(key_bindings)
return prefs.get("")
return None
[docs] def save_prefs(self, prefs=None):
"""Saves any user preference information associated with the UI."""
if prefs is None:
toolkit().save_window(self)
return
id = self.id
if id != "":
db = self.get_ui_db(mode="c")
if db is not None:
db[id] = self.get_prefs(prefs)
db.close()
[docs] def get_prefs(self, prefs=None):
"""Gets the preferences to be saved for the user interface."""
ui_prefs = {}
if prefs is not None:
ui_prefs[""] = prefs
if self.key_bindings is not None:
ui_prefs["$"] = self.key_bindings
info = self.info
for name in self._names:
editor = getattr(info, name, None)
if isinstance(editor, Editor) and (editor.ui is self):
prefs = editor.save_prefs()
if prefs is not None:
ui_prefs[name] = prefs
return ui_prefs
[docs] def get_ui_db(self, mode="r"):
"""Returns a reference to the Traits UI preference database."""
try:
return shelve.open(
os.path.join(traits_home(), "traits_ui"),
flag=mode,
protocol=-1,
)
except:
return None
[docs] def get_editors(self, name):
"""Returns a list of editors for the given trait name."""
return [editor for editor in self._editors if editor.name == name]
[docs] def get_error_controls(self):
"""Returns the list of editor error controls contained by the user
interface.
"""
controls = []
for editor in self._editors:
control = editor.get_error_control()
if isinstance(control, list):
controls.extend(control)
else:
controls.append(control)
return controls
[docs] def add_defined(self, method):
"""Adds a Handler method to the list of methods to be called once the
user interface has been constructed.
"""
self._defined.append(method)
[docs] def add_visible(self, visible_when, editor):
"""Adds a conditionally enabled Editor object to the list of monitored
'visible_when' objects.
"""
try:
self._visible.append(
(compile(visible_when, "<string>", "eval"), editor)
)
except:
pass
# fixme: Log an error here...
[docs] def add_enabled(self, enabled_when, editor):
"""Adds a conditionally enabled Editor object to the list of monitored
'enabled_when' objects.
"""
try:
self._enabled.append(
(compile(enabled_when, "<string>", "eval"), editor)
)
except:
pass
# fixme: Log an error here...
[docs] def add_checked(self, checked_when, editor):
"""Adds a conditionally enabled (menu) Editor object to the list of
monitored 'checked_when' objects.
"""
try:
self._checked.append(
(compile(checked_when, "<string>", "eval"), editor)
)
except:
pass
# fixme: Log an error here...
[docs] def do_undoable(self, action, *args, **kw):
"""Performs an action that can be undone."""
undoable = self._undoable
try:
if (undoable == -1) and (self.history is not None):
self._undoable = self.history.now
action(*args, **kw)
finally:
if undoable == -1:
self._undoable = -1
[docs] def route_event(self, event):
"""Routes a "hooked" event to the correct handler method."""
toolkit().route_event(self, event)
[docs] def key_handler(self, event, skip=True):
"""Handles key events."""
key_bindings = self.key_bindings
handled = (key_bindings is not None) and key_bindings.do(
event, [], self.info, recursive=(self.parent is None)
)
if (not handled) and (self.parent is not None):
handled = self.parent.key_handler(event, False)
if (not handled) and skip:
toolkit().skip_event(event)
return handled
[docs] def evaluate(self, function, *args, **kw_args):
"""Evaluates a specified function in the UI's **context**."""
if function is None:
return None
if callable(function):
return function(*args, **kw_args)
context = self.context.copy()
context["ui"] = self
context["handler"] = self.handler
return eval(function, globals(), context)(*args, **kw_args)
[docs] def eval_when(self, when, result=True):
"""Evaluates an expression in the UI's **context** and returns the
result.
"""
context = self._get_context(self.context)
try:
result = eval(when, globals(), context)
except:
from traitsui.api import raise_to_debug
raise_to_debug()
del context["ui"]
return result
def _get_context(self, context):
"""Gets the context to use for evaluating an expression."""
name = "object"
n = len(context)
if (n == 2) and ("handler" in context):
for name, value in context.items():
if name != "handler":
break
elif n == 1:
name = list(context.keys())[0]
value = context.get(name)
if value is not None:
context2 = value.trait_get()
context2.update(context)
else:
context2 = context.copy()
context2["ui"] = self
return context2
def _evaluate_when(self):
"""Set the 'visible', 'enabled', and 'checked' states for all Editors
controlled by a 'visible_when', 'enabled_when' or 'checked_when'
expression.
"""
self._do_evaluate_when(at_init=False)
def _do_evaluate_when(self, at_init=False):
"""Set the 'visible', 'enabled', and 'checked' states for all Editors.
This function does the job of _evaluate_when. We define it here to
work around the traits dispatching mechanism that automatically
determines the number of arguments of a notification method.
:attr:`at_init` is set to true when this function is called the first
time at initialization. In that case, we want to force the state of
the items to be set (normally it is set only if it changes).
"""
self._evaluate_condition(self._visible, "visible", at_init)
self._evaluate_condition(self._enabled, "enabled", at_init)
self._evaluate_condition(self._checked, "checked", at_init)
def _evaluate_condition(self, conditions, trait, at_init=False):
"""Evaluates a list of (eval, editor) pairs and sets a specified trait
on each editor to reflect the Boolean value of the expression.
1) All conditions are evaluated
2) The elements whose condition evaluates to False are updated
3) The elements whose condition evaluates to True are updated
E.g., we first make invisible all elements for which 'visible_when'
evaluates to False, and then we make visible the ones
for which 'visible_when' is True. This avoids mutually exclusive
elements to be visible at the same time, and thus making a dialog
unnecessarily large.
The state of an editor is updated only when it changes, unless
at_init is set to True.
Parameters
----------
conditions : list of (str, Editor) tuple
A list of tuples, each formed by 1) a string that contains a
condition that evaluates to either True or False, and
2) the editor whose state depends on the condition
trait : str
The trait that is set by the condition.
Either 'visible, 'enabled', or 'checked'.
at_init : bool
If False, the state of an editor is set only when it changes
(e.g., a visible element would not be updated to visible=True
again). If True, the state is always updated (used at
initialization).
"""
context = self._get_context(self.context)
# list of elements that should be activated
activate = []
# list of elements that should be de-activated
deactivate = []
for when, editor in conditions:
try:
cond_value = eval(when, globals(), context)
editor_state = getattr(editor, trait)
# add to update lists only if at_init is True (called on
# initialization), or if the editor state has to change
if cond_value and (at_init or not editor_state):
activate.append(editor)
if not cond_value and (at_init or editor_state):
deactivate.append(editor)
except Exception:
# catch errors in the validate_when expression
from traitsui.api import raise_to_debug
raise_to_debug()
# update the state of the editors
for editor in deactivate:
setattr(editor, trait, False)
for editor in activate:
setattr(editor, trait, True)
def _get__groups(self):
"""Returns the top-level Groups for the view (after resolving
Includes. (Implements the **_groups** property.)
"""
if self._groups_cache is None:
shadow_group = self.view.content.get_shadow(self)
self._groups_cache = shadow_group.get_content()
for item in self._groups_cache:
if isinstance(item, Item):
self._groups_cache = [
ShadowGroup(
shadow=Group(*self._groups_cache),
content=self._groups_cache,
groups=1,
)
]
break
return self._groups_cache
# -- Property Implementations ---------------------------------------------
def _get_key_bindings(self):
if self._key_bindings is None:
# create a new key_bindings instance lazily
view, context = self.view, self.context
if (view is None) or (context is None):
return None
# Get the KeyBindings object to use:
values = list(context.values())
key_bindings = view.key_bindings
if key_bindings is None:
from .key_bindings import KeyBindings
self._key_bindings = KeyBindings(controllers=values)
else:
self._key_bindings = key_bindings.clone(controllers=values)
return self._key_bindings
# -- Traits Event Handlers ------------------------------------------------
def _errors_changed(self, name, old, new):
if self.parent:
self.parent.errors = self.parent.errors - old + new
def _parent_changed(self, name, old, new):
if old is not None:
old.errors -= self.errors
if new is not None:
new.errors += self.errors
def _updated_changed(self):
if self.rebuild is not None:
toolkit().rebuild_ui(self)
def _title_changed(self):
if self.control is not None:
toolkit().set_title(self)
def _icon_changed(self):
if self.control is not None:
toolkit().set_icon(self)
@observe("parent, view, context")
def _pvc_changed(self, event):
parent = self.parent
if (parent is not None) and (self.key_bindings is not None):
# If we don't have our own history, use our parent's:
if self.history is None:
self.history = parent.history
# Link our KeyBindings object as a child of our parent's
# KeyBindings object (if any):
if parent.key_bindings is not None:
parent.key_bindings.children.append(self.key_bindings)
[docs]class Dispatcher(object):
def __init__(self, method, info, object, method_name):
"""Initializes the object."""
self.method = method
self.info = info
self.object = object
self.method_name = method_name
object.on_trait_change(self.dispatch, method_name, dispatch="ui")
[docs] def remove(self):
"""Removes the dispatcher."""
self.object.on_trait_change(
self.dispatch, self.method_name, remove=True
)
