/usr/share/pyshared/traitsui/ui

#------------------------------------------------------------------------------
#
#  Copyright (c) 2005, Enthought, Inc.
#  All rights reserved.
#
#  This software is provided without warranty under the terms of the BSD
#  license included in enthought/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!
#
#  Author: David C. Morrill
#  Date:   10/14/2004
#
#------------------------------------------------------------------------------

""" Defines common traits used within the traits.ui package.
"""

#-------------------------------------------------------------------------------
#  Imports:
#-------------------------------------------------------------------------------

from __future__ import absolute_import

from traits.api import (Any, Delegate, Enum, Expression, Float, HasStrictTraits,
    Instance, List, Range, Str, Trait, TraitError, TraitPrefixList, TraitType)

from traits.trait_base import get_resource_path

#-------------------------------------------------------------------------------
#  Trait definitions:
#-------------------------------------------------------------------------------

# Orientation trait:
Orientation = Trait( 'vertical',
                     TraitPrefixList( 'vertical', 'horizontal' ) )

# Styles for user interface elements:
EditorStyle = style_trait = Trait( 'simple',
                     TraitPrefixList( 'simple', 'custom', 'text', 'readonly' ),
                     cols = 4 )

# Group layout trait:
Layout = Trait( 'normal',
                TraitPrefixList( '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:
#-------------------------------------------------------------------------------

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( StatusItem, self ).__init__( **traits )

        if value is not None:
            self.name = value

#-------------------------------------------------------------------------------
#  'ViewStatus' trait:
#-------------------------------------------------------------------------------

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')

    def validate ( self, object, name, value ):
        """ Validates that a specified value is valid for this trait.
        """
        if isinstance( value, basestring ):
            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, basestring ):
                    result.append( StatusItem( name = item ) )
                elif isinstance( item, StatusItem ):
                    result.append( item )
                else:
                    break
            else:
                return result

        self.error( object, name, value )

#-------------------------------------------------------------------------------
#  'Image' trait:
#-------------------------------------------------------------------------------

image_resource_cache = {}
image_bitmap_cache   = {}

def convert_image ( value, level = 3 ):
    """ Converts a specified value to an ImageResource if possible.
    """
    global image_resource_cache

    if not isinstance( value, basestring ):
        return value

    key             = value
    is_traits_image = (value[:1] == '@')
    if not is_traits_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_traits_image:
            try:
                from .image.image import ImageLibrary

                result = ImageLibrary.image_resource( value )
            except:
                result = None
        else:
            from pyface.image_resource import ImageResource
            result = ImageResource( value, search_path = [ search_path ] )

        image_resource_cache[ key ] = result

    return result

def convert_bitmap ( image_resource ):
    """ Converts an ImageResource to a bitmap using a cache.
    """
    global image_bitmap_cache

    bitmap = image_bitmap_cache.get( image_resource )
    if (bitmap is None) and (image_resource is not None):
        #try:
        image_bitmap_cache[ image_resource ] = bitmap = \
            image_resource.create_bitmap()
        #except:
        #    pass

    return bitmap

class Image ( TraitType ):
    """ Defines a trait whose value must be a PyFace ImageResource 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 = 'an ImageResource or string that can be used to define one'

    def __init__ ( self, value = None, **metadata ):
        """ Creates an Image trait.

        Parameters
        ----------
        value : string or ImageResource
            The default value for the Image, either an ImageResource object,
            or a string from which an ImageResource object can be derived.
        """
        super( Image, self ).__init__( convert_image( value ), **metadata )

    def validate ( self, object, name, value ):
        """ Validates that a specified value is valid for this trait.
        """
        from pyface.image_resource import ImageResource

        if value is None:
            return None

        new_value = convert_image( value, 4 )
        if isinstance( new_value, ImageResource ):
            return new_value

        self.error( object, name, value )

    def create_editor ( self ):
        """ Returns the default UI editor for the trait.
        """
        from .editors.api import ImageEditor
        return ImageEditor()

#-------------------------------------------------------------------------------
#  'ATheme' trait:
#-------------------------------------------------------------------------------

def convert_theme ( value, level = 3 ):
    """ Converts a specified value to a Theme if possible.
    """
    if not isinstance( value, basestring ):
        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 ) )

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( ATheme, self ).__init__( convert_theme( value ), **metadata )

    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 )

#-------------------------------------------------------------------------------
#  'BasePMB' class:
#-------------------------------------------------------------------------------

class BaseMB ( HasStrictTraits ):

    def __init__ ( self, *args, **traits ):
        """ Initializes the object.
        """
        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 )
            self.set( left = left, right = right, top = top, bottom = bottom )

        super( BaseMB, self ).__init__( **traits )

#-------------------------------------------------------------------------------
#  'Margin' class:
#-------------------------------------------------------------------------------

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 )

#-------------------------------------------------------------------------------
#  'Border' class:
#-------------------------------------------------------------------------------

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 )

#-------------------------------------------------------------------------------
#  'HasMargin' trait:
#-------------------------------------------------------------------------------

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')

    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:
                self.error( object, name, value )
        elif isinstance( value, tuple ):
            try:
                value = self.klass( *value )
            except:
                self.error( object, name, value )

        if isinstance( value, self.klass ):
            return value

        self.error( object, name, value )

    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( HasMargin, self ).get_default_value()

            self.default_value_type = dvt = 7
            dv = ( self.klass, (), dv.get() )

        return ( dvt, dv )

#-------------------------------------------------------------------------------
#  'HasBorder' trait:
#-------------------------------------------------------------------------------

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')

#-------------------------------------------------------------------------------
#  Other trait definitions:
#-------------------------------------------------------------------------------

# 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' )

# The spacing between two items:
Spacing = Range( -32, 32, 3 )

#-------------------------------------------------------------------------------
#  Other definitions:
#-------------------------------------------------------------------------------

# Types that represent sequences:
SequenceTypes = ( tuple, list )
python-traitsui 4.1.0-1 / usr / share / pyshared / traitsui / ui_traits.py
