traitsui.tabular_adapter module

Defines the adapter classes associated with the Traits UI TabularEditor.

class traitsui.tabular_adapter.AnITabularAdapter

Bases: traits.has_traits.HasPrivateTraits

accepts = Bool(True)

Does the adapter know how to handle the current item or not:

column = Any()

The current column id being adapted (if any):

columns = List(Str)

The list of columns the adapter supports. The items in the list have the same format as the columns trait in the TabularAdapter class, with the additional requirement that the string values must correspond to a string value in the associated TabularAdapter class.

is_cacheable = Bool(True)

Does the value of accepts depend only upon the type of item?

item = Any()

Current item being adapted:

row = Int()

The row index of the current item being adapted:

value = Any()

The current value (if any):

class traitsui.tabular_adapter.ITabularAdapter

Bases: traits.has_traits.Interface

accepts = Bool()

Does the adapter know how to handle the current item or not:

column = Any()

The current column id being adapted (if any):

columns = List(Str)

The list of columns the adapter supports. The items in the list have the same format as the columns trait in the TabularAdapter class, with the additional requirement that the string values must correspond to a string value in the associated TabularAdapter class.

is_cacheable = Bool()

Does the value of accepts depend only upon the type of item?

item = Any()

Current item being adapted:

row = Int()

The row index of the current item being adapted:

value = Any()

The current value (if any):

class traitsui.tabular_adapter.TabularAdapter

Bases: traits.has_traits.HasPrivateTraits

The base class for adapting list items to values that can be edited by a TabularEditor.

adapter_column_indices = Property(depends_on="adapters,columns")

For each adapter, specifies the column indices the adapter handles.

adapter_column_map = Property(depends_on="adapters,columns")

For each adapter, specifies the mapping from column index to column id.

adapters = List(ITabularAdapter, update=True)

List of optional delegated adapters.

alignment = Enum("left", "center", "right")

Horizontal alignment to use for a specified column.

bg_color = Property()

The background color for a row item.

cache = Any({})

Cache of attribute handlers.

cache_flushed = Event(update=True)

Event fired when the cache is flushed.

can_drop = Bool(False)

Can any arbitrary value be dropped onto the tabular view.

can_edit = Bool(True)

Can the text value of each item be edited?

cleanup()

Clean up the adapter to remove references to objects.

column = Int()

The column index of the current item being adapted.

column_dict = Property()

Maps UI name of column to value identifying column to the adapter, if different.

column_id = Any()

The current column id being adapted (if any).

column_map = Property(depends_on="columns")

The mapping from column indices to column identifiers (defined by the columns trait).

column_menu = Any()

The context menu for column header.

columns = List()

A list of columns that should appear in the table. Each entry can have one of two forms: string or (string, id), where string is the UI name of the column, and id is a value that identifies that column to the adapter. Normally this value is either a trait name or an index, but it can be any value that the adapter wants. If only string is specified, then id is the index of the string within columns.

content = Property()

The content of a row/column item (may be any Python value).

default_bg_color = Color(None, update=True)

The default background color for table rows.

default_text_color = Color(None, update=True)

The default text color for table rows.

default_value = Any("")

Specifies the default value for a new row. This will usually need to be overridden.

delete(object, trait, row)

Deletes the specified row item.

This method is only called if the delete operation is specified in the TabularEditor operation trait, and the user requests that the item be deleted from the table.

The adapter can still choose not to delete the specified item if desired, although that may prove confusing to the user.

The default implementation assumes the trait defined by object.trait is a mutable sequence and attempts to perform a del object.trait[row] operation.

drag = Property()

The value to be dragged for a specified row item.

dropped = Enum("after", "before")

Specifies where a dropped item should be placed in the table relative to the item it is dropped on.

even_bg_color = Color(None, update=True)

The default background color for even table rows.

even_text_color = Color(None, update=True)

The default text color for even table rows.

font = Font(None)

The font for a row item.

format = Str("%s")

The Python format string to use for a specified column.

get_alignment(object, trait, column)

Returns the alignment style to use for a specified column.

The possible values that can be returned are: 'left', 'center' or 'right'. All table items share the same alignment for a specified column.

get_bg_color(object, trait, row, column=0)

Returns the background color to use for a specified row or cell.

A result of None means use the default background color; otherwise a toolkit-compatible color should be returned. Note that all columns for the specified table row will use the background color value returned.

get_can_drop(object, trait, row, value)

Returns whether the specified value can be dropped on the specified row.

A value of True means the value can be dropped; and a value of False indicates that it cannot be dropped.

The result is used to provide the user positive or negative drag feedback while dragging items over the table. value will always be a single value, even if multiple items are being dragged. The editor handles multiple drag items by making a separate call to get_can_drop() for each item being dragged.

get_can_edit(object, trait, row)

Returns whether the user can edit a specified row.

A True result indicates that the value can be edited, while a False result indicates that it cannot.

get_column(object, trait, index)

Returns the column id corresponding to a specified column index.

get_column_menu(object, trait, row, column)

Returns the context menu for a specified column.

get_content(object, trait, row, column)

Returns the content to display for a specified cell.

get_default_value(object, trait)

Returns a new default value for the specified object.trait list.

This method is called when insert or append operations are allowed and the user requests that a new item be added to the table. The result should be a new instance of whatever underlying representation is being used for table items.

The default implementation simply returns the value of the adapter’s default_value trait.

get_drag(object, trait, row)

Returns the value to be dragged for a specified row.

A result of None means that the item cannot be dragged. Note that the value returned does not have to be the actual row item. It can be any value that you want to drag in its place. In particular, if you want the drag target to receive a copy of the row item, you should return a copy or clone of the item in its place.

Also note that if multiple items are being dragged, and this method returns None for any item in the set, no drag operation is performed.

get_dropped(object, trait, row, value)

Returns how to handle a specified value being dropped on a specified row.

The possible return values are:

  • 'before': Insert the specified value before the dropped on item.

  • 'after': Insert the specified value after the dropped on item.

Note there is no result indicating do not drop since you will have already indicated that the object can be dropped by the result returned from a previous call to get_can_drop().

get_font(object, trait, row, column=0)

Returns the font to use for displaying a specified row or cell.

A result of None means use the default font; otherwise a toolkit font object should be returned. Note that all columns for the specified table row will use the font value returned.

get_format(object, trait, row, column)

Returns the Python formatting string to apply to the specified cell.

The resulting of formatting with this string will be used as the text to display it in the table.

The return can be any Python string containing exactly one old-style Python formatting sequence, such as '%.4f' or '(%5.2f)'.

get_image(object, trait, row, column)

Returns the image to display for a specified cell.

A result of None means no image will be displayed in the specified table cell. Otherwise the result should either be the name of the image, or an ImageResource object specifying the image to display.

A name is allowed in the case where the image is specified in the TabularEditor images trait. In that case, the name should be the same as the string specified in the ImageResource constructor.

get_item(object, trait, row)

Returns the specified row item.

The value returned should be the value that exists (or logically exists) at the specified row in your data. If your data is not really a list or array, then you can just use row as an integer key or token that can be used to retrieve a corresponding item. The value of row will always be in the range: 0 <= row < len(object, trait) (i.e. the result returned by the adapter len() method).

The default implementation assumes the trait defined by object.trait is a sequence and attempts to return the value at index row. If an error occurs, it returns None instead. This definition should work correctly for lists, tuples and arrays, or any other object that is indexable, but will have to be overridden for all other cases.

get_label(section, obj=None)

Override this method if labels will vary from object to object.

get_menu(object, trait, row, column)

Returns the context menu for a specified cell.

get_row_label(section, obj=None)
get_text(object, trait, row, column)

Returns a string containing the text to display for a specified cell.

If the underlying data representation for a specified item is not a string, then it is your responsibility to convert it to one before returning it as the result.

get_text_color(object, trait, row, column=0)

Returns the text color to use for a specified row or cell.

A result of None means use the default text color; otherwise a toolkit-compatible color should be returned. Note that all columns for the specified table row will use the text color value returned.

get_tooltip(object, trait, row, column)

Returns a string containing the tooltip to display for a specified cell.

You should return the empty string if you do not wish to display a tooltip.

get_width(object, trait, column)

Returns the width to use for a specified column.

If the value is <= 0, the column will have a default width, which is the same as specifying a width of 0.1.

If the value is > 1.0, it is converted to an integer and the result is the width of the column in pixels. This is referred to as a fixed width column.

If the value is a float such that 0.0 < value <= 1.0, it is treated as the unnormalized fraction of the available space that is to be assigned to the column. What this means requires a little explanation.

To arrive at the size in pixels of the column at any given time, the editor adds together all of the unnormalized fraction values returned for all columns in the table to arrive at a total value. Each unnormalized fraction is then divided by the total to create a normalized fraction. Each column is then assigned an amount of space in pixels equal to the maximum of 30 or its normalized fraction multiplied by the available space. The available space is defined as the actual width of the table minus the width of all fixed width columns. Note that this calculation is performed each time the table is resized in the user interface, thus allowing columns of this type to increase or decrease their width dynamically, while leaving fixed width columns unchanged.

image = Str(None, update=True)

The name of the default image to use for column items.

insert(object, trait, row, value)

Inserts value at the specified object.trait[row] index.

The specified value can be:

  • An item being moved from one location in the data to another.

  • A new item created by a previous call to get_default_value().

  • An item the adapter previously approved via a call to get_can_drop().

The adapter can still choose not to insert the item into the data, although that may prove confusing to the user.

The default implementation assumes the trait defined by object.trait is a mutable sequence and attempts to perform an object.trait[row:row] = [value] operation.

item = Any()

Current item being adapted.

label_map = Property(depends_on="columns")

The mapping from column indices to column labels (defined by the columns trait).

len(object, trait)

Returns the number of row items in the specified object.trait.

The result should be an integer greater than or equal to 0.

The default implementation assumes the trait defined by object.trait is a sequence and attempts to return the result of calling len(object.trait). It will need to be overridden for any type of data which for which len() will not work.

menu = Any()

The context menu for a row/column item.

name = Str()

The name of the trait being edited.

object = Instance(HasTraits)

The object whose trait is being edited.

odd_bg_color = Color(None, update=True)

The default background color for odd table rows.

odd_text_color = Color(None, update=True)

The default text color for odd table rows.

row = Int()

The row index of the current item being adapted.

row_label_name = Either(None, Str)

The name of the trait on a row item containing the value to use as a row label. If None, the label will be the empty string.

set_text(object, trait, row, column, text)

Sets the value for the specified cell.

This method is called when the user completes an editing operation on a table cell.

The string specified by text is the value that the user has entered in the table cell. If the underlying data does not store the value as text, it is your responsibility to convert text to the correct representation used.

text = Property()

The text of a row/column item.

text_color = Property()

The text color for a row item.

tooltip = Str()

The tooltip information for a row/column item.

value = Any()

The current value (if any).

width = Float(-1)

Width of a specified column.