Source code for pyface.ui_traits
# (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!
""" Defines common traits used within the pyface library. """
from collections.abc import Sequence
import logging
try:
import numpy as np
except ImportError:
np = None
from traits.api import (
ABCHasStrictTraits,
DefaultValue,
Enum,
Range,
TraitError,
TraitFactory,
TraitType,
)
from traits.trait_base import get_resource_path
from pyface.color import Color
from pyface.font import Font
from pyface.i_image import IImage
from pyface.util.color_parser import ColorParseError
from pyface.util.font_parser import simple_parser, FontParseError
logger = logging.getLogger(__name__)
# -------------------------------------------------------------------------------
# Images
# -------------------------------------------------------------------------------
# cache of lookups from string to ImageResource instance
image_resource_cache = {}
# cache of conversions of ImageResource instances to toolkit bitmaps
image_bitmap_cache = {}
[docs]def convert_image(value, level=3):
""" Converts a specified value to an ImageResource if possible.
"""
if not isinstance(value, str):
return value
key = value
is_pyface_image = value.startswith("@")
if not is_pyface_image:
search_path = get_resource_path(level)
key = "%s[%s]" % (value, search_path)
result = image_resource_cache.get(key)
if result is None:
if is_pyface_image:
try:
from .image.image import ImageLibrary
result = ImageLibrary.image_resource(value)
except Exception as exc:
logger.error("Can't load image resource '%s'." % value)
logger.exception(exc)
result = None
else:
from pyface.image_resource import ImageResource
result = ImageResource(value, search_path=[search_path])
image_resource_cache[key] = result
return result
[docs]def convert_bitmap(image):
""" Converts an ImageResource to a bitmap using a cache.
"""
from pyface.i_image_resource import IImageResource
if not isinstance(image, IImageResource):
# don't try to cache non-ImageResource IImages as they may be
# dynamically changing
return image.create_bitmap()
bitmap = image_bitmap_cache.get(image)
if (bitmap is None) and (image is not None):
image_bitmap_cache[image] = bitmap = image.create_bitmap()
return bitmap
[docs]class Image(TraitType):
""" Defines a trait whose value must be a IImage or a string
that can be converted to an IImageResource.
"""
#: Define the default value for the trait.
default_value = None
#: A description of the type of value this trait accepts.
info_text = "an IImage or string that can be used to define an ImageResource" # noqa: E501
def __init__(self, value=None, **metadata):
""" Creates an Image trait.
Parameters
----------
value : string or ImageResource
The default value for the Image, either an IImage object,
or a string from which an ImageResource object can be derived.
"""
super().__init__(convert_image(value), **metadata)
[docs] def validate(self, object, name, value):
""" Validates that a specified value is valid for this trait.
"""
if value is None:
return None
new_value = convert_image(value, 4)
if isinstance(new_value, IImage):
return new_value
self.error(object, name, value)
[docs] def create_editor(self):
""" Returns the default UI editor for the trait.
"""
from traitsui.editors.api import ImageEditor
return ImageEditor()
# -------------------------------------------------------------------------------
# Color
# -------------------------------------------------------------------------------
[docs]class PyfaceColor(TraitType):
""" A Trait which casts strings and tuples to a Pyface Color value.
"""
#: The default value should be a tuple (factory, args, kwargs)
default_value_type = DefaultValue.callable_and_args
def __init__(self, value=None, **metadata):
if value is not None:
color = self.validate(None, None, value)
default_value = (Color, (), {'rgba': color.rgba})
else:
default_value = (Color, (), {})
super().__init__(default_value, **metadata)
[docs] def validate(self, object, name, value):
if isinstance(value, Color):
return value
if isinstance(value, str):
try:
return Color.from_str(value)
except ColorParseError:
self.error(object, name, value)
is_array = (
np is not None
and isinstance(value, (np.ndarray, np.void))
)
if is_array or isinstance(value, Sequence):
channels = tuple(value)
if len(channels) == 4:
return Color(rgba=channels)
elif len(channels) == 3:
return Color(rgb=channels)
self.error(object, name, value)
[docs] def info(self):
return (
"a Pyface Color, a #-hexadecimal rgb or rgba string, a standard "
"color name, or a sequence of RGBA or RGB values between 0 and 1"
)
# -------------------------------------------------------------------------------
# Font
# -------------------------------------------------------------------------------
[docs]class PyfaceFont(TraitType):
""" A Trait which casts strings to a Pyface Font value.
"""
#: The default value should be a tuple (factory, args, kwargs)
default_value_type = DefaultValue.callable_and_args
#: The parser to use when converting text to keyword args. This should
#: accept a string and return a dictionary of Font class trait values (ie.
#: "family", "size", "weight", etc.).
parser = None
def __init__(self, value=None, *, parser=simple_parser, **metadata):
self.parser = parser
if value is not None:
try:
font = self.validate(None, None, value)
except TraitError:
raise ValueError(
"expected " + self.info()
+ f", but got {value!r}"
)
default_value = (
Font,
(),
font.trait_get(transient=lambda x: not x),
)
else:
default_value = (Font, (), {})
super().__init__(default_value, **metadata)
[docs] def validate(self, object, name, value):
if isinstance(value, Font):
return value
if isinstance(value, str):
try:
return Font(**self.parser(value))
except FontParseError:
self.error(object, name, value)
self.error(object, name, value)
# -------------------------------------------------------------------------------
# Borders, Margins and Layout
# -------------------------------------------------------------------------------
[docs]class BaseMB(ABCHasStrictTraits):
def __init__(self, *args, **traits):
""" Map posiitonal arguments to traits.
If one value is provided it is taken as the value for all sides.
If two values are provided, then the first argument is used for
left and right, while the second is used for top and bottom.
If 4 values are provided, then the arguments are mapped to
left, right, top, and bottom, respectively.
"""
n = len(args)
if n > 0:
if n == 1:
left = right = top = bottom = args[0]
elif n == 2:
left = right = args[0]
top = bottom = args[1]
elif n == 4:
left, right, top, bottom = args
else:
raise TraitError(
"0, 1, 2 or 4 arguments expected, but %d " "specified" % n
)
traits.update(
{"left": left, "right": right, "top": top, "bottom": bottom}
)
super().__init__(**traits)
[docs]class Margin(BaseMB):
# The amount of padding/margin at the top:
top = Range(-32, 32, 0)
# The amount of padding/margin at the bottom:
bottom = Range(-32, 32, 0)
# The amount of padding/margin on the left:
left = Range(-32, 32, 0)
# The amount of padding/margin on the right:
right = Range(-32, 32, 0)
[docs]class Border(BaseMB):
# The amount of border at the top:
top = Range(0, 32, 0)
# The amount of border at the bottom:
bottom = Range(0, 32, 0)
# The amount of border on the left:
left = Range(0, 32, 0)
# The amount of border on the right:
right = Range(0, 32, 0)
[docs]class HasMargin(TraitType):
""" Defines a trait whose value must be a Margin object or an integer or
tuple value that can be converted to one.
"""
# The desired value class:
klass = Margin
# Define the default value for the trait:
default_value = Margin(0)
# A description of the type of value this trait accepts:
info_text = (
"a Margin instance, or an integer in the range from -32 to 32 "
"or a tuple with 1, 2 or 4 integers in that range that can be "
"used to define one"
)
[docs] def validate(self, object, name, value):
""" Validates that a specified value is valid for this trait.
"""
if isinstance(value, int):
try:
value = self.klass(value)
except Exception:
self.error(object, name, value)
elif isinstance(value, tuple):
try:
value = self.klass(*value)
except Exception:
self.error(object, name, value)
if isinstance(value, self.klass):
return value
self.error(object, name, value)
[docs] def get_default_value(self):
""" Returns a tuple of the form:
(default_value_type, default_value)
which describes the default value for this trait.
"""
dv = self.default_value
dvt = self.default_value_type
if dvt < 0:
if isinstance(dv, int):
dv = self.klass(dv)
elif isinstance(dv, tuple):
dv = self.klass(*dv)
if not isinstance(dv, self.klass):
return super().get_default_value()
self.default_value_type = dvt = DefaultValue.callable_and_args
dv = (self.klass, (), dv.trait_get())
return (dvt, dv)
[docs]class HasBorder(HasMargin):
""" Defines a trait whose value must be a Border object or an integer
or tuple value that can be converted to one.
"""
# The desired value class:
klass = Border
# Define the default value for the trait:
default_value = Border(0)
# A description of the type of value this trait accepts:
info_text = (
"a Border instance, or an integer in the range from 0 to 32 "
"or a tuple with 1, 2 or 4 integers in that range that can be "
"used to define one"
)
#: The position of an image relative to its associated text.
Position = Enum("left", "right", "above", "below")
#: The alignment of text within a control.
Alignment = Enum("default", "left", "center", "right")
#: Whether the orientation of a widget's contents is horizontal or vertical.
Orientation = Enum("vertical", "horizontal")
# -------------------------------------------------------------------------------
# Legacy TraitsUI Color and Font Traits
# -------------------------------------------------------------------------------
def TraitsUIColor(*args, **metadata):
""" Returns a trait whose value must be a GUI toolkit-specific color.
This is copied from the deprecated trait that is in traits.api. It adds
a deferred dependency on TraitsUI.
This trait will be replaced by native Pyface color traits in Pyface 8.0.
New code should not use this trait.
"""
from traitsui.toolkit_traits import ColorTrait
return ColorTrait(*args, **metadata)
TraitsUIColor = TraitFactory(TraitsUIColor)
def TraitsUIFont(*args, **metadata):
""" Returns a trait whose value must be a GUI toolkit-specific font.
This is copied from the deprecated trait that is in traits.api. It adds
a deferred dependency on TraitsUI.
This trait will be replaced by native Pyface font traits in Pyface 8.0.
New code should not use this trait.
"""
from traitsui.toolkit_traits import FontTrait
return FontTrait(*args, **metadata)
TraitsUIFont = TraitFactory(TraitsUIFont)
