Source code for traitsui.ui_traits
# (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 common traits used within the traits.ui package.
"""
from pyface.ui_traits import (
Alignment,
Border,
HasBorder,
HasMargin,
Image,
Margin,
Position,
convert_bitmap,
convert_image,
)
from traits.api import (
Any,
Delegate,
Enum,
Expression,
Float,
HasStrictTraits,
List,
PrefixList,
Range,
Str,
TraitError,
TraitType,
)
from .helper import SequenceTypes
# -------------------------------------------------------------------------
# Trait definitions:
# -------------------------------------------------------------------------
# Orientation trait:
Orientation = PrefixList(("vertical", "horizontal"))
# Styles for user interface elements:
EditorStyle = style_trait = PrefixList(
("simple", "custom", "text", "readonly"), cols=4
)
# Group layout trait:
Layout = PrefixList(("normal", "split", "tabbed", "flow", "fold"))
# Trait for the default object being edited:
AnObject = Expression("object")
# The default dock style to use:
DockStyle = dock_style_trait = Enum(
"fixed",
"horizontal",
"vertical",
"tab",
desc="the default docking style to use",
)
# The category of elements dragged out of the view:
ExportType = Str(desc="the category of elements dragged out of the view")
# Delegate a trait value to the object's **container** trait:
ContainerDelegate = container_delegate = Delegate(
"container", listenable=False
)
# An identifier for the external help context:
HelpId = help_id_trait = Str(desc="the external help context identifier")
# A button to add to a view:
AButton = Any()
# AButton = Trait( '', Str, Instance( 'traitsui.menu.Action' ) )
# The set of buttons to add to the view:
Buttons = List(
AButton, desc="the action buttons to add to the bottom of the view"
)
# View trait specified by name or instance:
AView = Any()
# AView = Trait( '', Str, Instance( 'traitsui.view.View' ) )
# FIXME: on AButton and AView: TraitCompound handlers with deferred-import
# Instance traits are just broken. The Instance trait tries to update the
# top-level CTrait's fast_validate table when the import is resolved. However,
# sometimes the CTrait gets copied for unknown reasons and the copy's
# fast_validate table is not updated although the TraitCompound's
# slow_validates table is modified.
# -------------------------------------------------------------------------
# 'StatusItem' class:
# -------------------------------------------------------------------------
[docs]class StatusItem(HasStrictTraits):
#: The name of the trait the status information will be synched with:
name = Str("status")
#: The width of the status field. The possible values are:
#:
#: - abs( width ) > 1.0: Width of the field in pixels = abs( width )
#: - abs( width ) <= 1.0: Relative width of the field when compared to
#: the other relative width fields.
width = Float(0.5)
def __init__(self, value=None, **traits):
"""Initializes the item object."""
super().__init__(**traits)
if value is not None:
self.name = value
# -------------------------------------------------------------------------
# 'ViewStatus' trait:
# -------------------------------------------------------------------------
[docs]class ViewStatus(TraitType):
"""Defines a trait whose value must be a single StatusItem instance or a
list of StatusItem instances.
"""
#: Define the default value for the trait:
default_value = None
#: A description of the type of value this trait accepts:
info_text = (
"None, a string, a single StatusItem instance, or a list or "
"tuple of strings and/or StatusItem instances"
)
[docs] def validate(self, object, name, value):
"""Validates that a specified value is valid for this trait."""
if isinstance(value, str):
return [StatusItem(name=value)]
if isinstance(value, StatusItem):
return [value]
if value is None:
return value
result = []
if isinstance(value, SequenceTypes):
for item in value:
if isinstance(item, str):
result.append(StatusItem(name=item))
elif isinstance(item, StatusItem):
result.append(item)
else:
break
else:
return result
self.error(object, name, value)
# -------------------------------------------------------------------------
# 'ATheme' trait:
# -------------------------------------------------------------------------
[docs]def convert_theme(value, level=3):
"""Converts a specified value to a Theme if possible."""
if not isinstance(value, str):
return value
if (value[:1] == "@") and (value.find(":") >= 2):
try:
from .image.image import ImageLibrary
info = ImageLibrary.image_info(value)
except:
info = None
if info is not None:
return info.theme
from .theme import Theme
return Theme(image=convert_image(value, level + 1))
[docs]class ATheme(TraitType):
"""Defines a trait whose value must be a traits UI Theme or a string that
can be converted to one.
"""
#: Define the default value for the trait:
default_value = None
#: A description of the type of value this trait accepts:
info_text = "a Theme or string that can be used to define one"
def __init__(self, value=None, **metadata):
"""Creates an ATheme trait.
Parameters
----------
value : string or Theme
The default value for the ATheme, either a Theme object, or a
string from which a Theme object can be derived.
"""
super().__init__(convert_theme(value), **metadata)
[docs] def validate(self, object, name, value):
"""Validates that a specified value is valid for this trait."""
from .theme import Theme
if value is None:
return None
new_value = convert_theme(value, 4)
if isinstance(new_value, Theme):
return new_value
self.error(object, name, value)
# -------------------------------------------------------------------------------
# Other trait definitions:
# -------------------------------------------------------------------------
# The spacing between two items:
Spacing = Range(-32, 32, 3)