traitsui.editor module

Defines the abstract Editor class, which represents an editing control for an object trait in a Traits-based user interface.

class traitsui.editor.Editor(parent, **traits)

Bases: HasPrivateTraits

Represents an editing control for an object trait in a Traits-based user interface.

context_object = Property()

The context object the editor is editing (e.g. object):

control = Any(clean_up=True)

The GUI widget defined by this editor:

description = ReadOnly()

Text description of the object trait being edited:

dispose()

Disposes of the contents of an editor.

This disconnects any synchronised values and resets references to other objects.

Subclasses may chose to override this method to perform additional clean-up.

enabled = Bool(True)

Is the underlying GUI widget enabled?

error(excp)

Handles an error that occurs while setting the object’s trait value.

Parameters:

excp (Exception) – The exception which occurred.

extended_name = Property()

The extended name of the object trait being edited. That is, ‘object_name.name’ minus the context object name at the beginning. For example: ‘link1.link2.value’:

factory = Instance(EditorFactory, clean_up=True)

The EditorFactory used to create this editor:

get_control_widget()

Get the concrete widget for the control.

The default implementation returns the control, however some editors in some backends may store a layout or sizer instead of a proper widget or control, which may not be suitable for certain usages.

get_undo_item(object, name, old_value, new_value)

Creates an undo history entry.

Can be overridden in a subclass for special value types.

Parameters:

• object (HasTraits instance) – The object being modified.

• name (str) – The name of the trait that is to be changed.

• old_value (any) – The original value of the trait.

• new_value (any) – The new value of the trait.

init(parent)

Create and initialize the underlying toolkit widget.

This method must be overriden by subclasses. Implementations must ensure that the control trait is set to an appropriate toolkit object.

Parameters:

parent (toolkit control) – The parent toolkit object of the editor’s toolkit objects.

invalid = Bool(False)

The current editor invalid state status:

item = Instance(Item, (), clean_up=True)

The Item object used to create this editor:

label_control = Any(clean_up=True)

The GUI label (if any) defined by this editor:

log_change(undo_factory, *undo_args)

Logs a change made in the editor with undo/redo history.

Parameters:

• undo_factory (callable) – Callable that creates an undo item. Often self.get_undo_item.

• *undo_args – Any arguments to pass to the undo factory.

name = ReadOnly()

The name of the trait this editor is editing (e.g. ‘value’):

no_trait_update(name)

Context manager that blocks updates from the named trait.

object = Instance(HasTraits, clean_up=True)

The object this editor is editing (e.g. object.link1.link2):

object_name = Str("object")

Full name of the object the editor is editing (e.g. ‘object.link1.link2’):

old_value = Any(clean_up=True)

Original value of object.name (e.g. object.link1.link2.value):

parse_extended_name(name)

Extract the object, name and a getter from an extended name

Parameters:

name (str) – The extended name to parse.

Returns:

object, name, getter – The object from the context, the (extended) name of the attributes holding the value, and a callable which gets the current value from the context.

Return type:

any, str, callable

prepare(parent)

Finish setting up the editor.

Parameters:

parent (toolkit control) – The parent toolkit object of the editor’s toolkit objects.

raise_to_debug()

Context manager that uses raise to debug to raise exceptions.

restore_prefs(prefs)

Restores saved user preference information for the editor.

Editors with state may choose to override this. It will only be used if the editor has an id value.

Parameters:

prefs (dict) – A dictionary of preference values.

save_prefs()

Returns any user preference information for the editor.

Editors with state may choose to override this. It will only be used if the editor has an id value.

Returns:

prefs – A dictionary of preference values, or None if no preferences to be saved.

Return type:

dict or None

scrollable = Bool(False)

Is the underlying GUI widget scrollable?

set_focus()

Assigns focus to the editor’s underlying toolkit widget.

This method must be overriden by subclasses.

set_tooltip(control=None)

Sets the tooltip for a specified toolkit control.

This uses the tooltip_text method to get the text to use.

Parameters:

control (optional toolkit control) – The toolkit control that is having the tooltip set. If None then the editor’s control is used.

Returns:

tooltip_set – Whether or not a tooltip value could be set.

Return type:

bool

set_tooltip_text(control, text)

Sets the tooltip for a toolkit control to the provided text.

This method must be overriden by subclasses.

Parameters:

• text (str) – The text to use for the tooltip.

• control (toolkit control) – The toolkit control that is having the tooltip set.

str_value = Property()

Current value of object trait as a string:

string_value(value, format_func=None)

Returns the text representation of a specified object trait value.

This simply delegates to the factory’s string_value method. Sub-classes may choose to override the default implementation.

Parameters:

• value (any) – The value being edited.

• format_func (callable or None) – A function that takes a value and returns a string.

sync_value(user_name, editor_name, mode='both', is_list=False, is_event=False)

Synchronize an editor trait and a user object trait.

Also sets the initial value of the editor trait from the user object trait (for modes ‘from’ and ‘both’), and the initial value of the user object trait from the editor trait (for mode ‘to’), as long as the relevant traits are not events.

Parameters:

• user_name (str) – The name of the trait to be used on the user object. If empty, no synchronization will be set up.

• editor_name (str) – The name of the relevant editor trait.

• mode (str, optional; one of 'to', 'from' or 'both') – The direction of synchronization. ‘from’ means that trait changes in the user object should be propagated to the editor. ‘to’ means that trait changes in the editor should be propagated to the user object. ‘both’ means changes should be propagated in both directions. The default is ‘both’.

• is_list (bool, optional) – If true, synchronization for item events will be set up in addition to the synchronization for the object itself. The default is False.

• is_event (bool, optional) – If true, this method won’t attempt to initialize the user object or editor trait values. The default is False.

tooltip_text()

Get the text for a tooltip, checking various sources.

This checks for text from, in order:

• the editor’s description trait

• the base trait’s ‘tooltip’ metadata

• the base trait’s ‘desc’ metadata

Returns:

text – The text for the tooltip, or None if no suitable text can be found.

Return type:

str or None

ui = Instance("traitsui.ui.UI", clean_up=True)

The UI (user interface) this editor is part of:

update_editor()

Updates the editor when the value changes externally to the editor.

This should normally be overridden in a subclass.

updating = Bool(False)

Is the editor updating the object.name value?

updating_value()

Context manager to handle updating value.

value = Property()

Current value for object.name:

value_trait = Property()

The trait the editor is editing (not its value, but the trait itself):

visible = Bool(True)

Is the underlying GUI widget visible?