Traits 3.0 introduces a new editor, called the TabularEditor, located in the traitsui.wx.extras.tabular_editor module that can be used for many of the same purposes as the existing TableEditor. However, while similar in function, each editor has its own particular strengths and weaknesses.
Some of the strengths of the new TabularEditor are:
Some of the weaknesses of the TabularEditor compared to the TableEditor are:
Setting up a TabularEditor for use in a Traits UI is divided into two main parts:
We'll start off first with a description of the TabularEditor class, and describe the adapter interface in a later section.
The TabularEditor class defines a large number of traits which are used to configure the editor. We'll divide the set of traits into several categories, and describe each in turn.
A list of strings that specify what operations the user is allowed to perform on items in the table. The possible values are:
You should include in the list all operations that you want to allow the user to perform (e.g. ['delete','insert','append']).
Objects of the TabularEditorEvent class contain information related to a mouse button click that occurs within the editor. The class has no methods, but does define the following traits:
Depending upon how you have configured the TabularEditor and its associated adapter, the following user interface features may be available:
In the preceding list, the values in parentheses refer to the operation that must be included in the TabularEditor operations trait in order for the specified key to have any effect.
The append, move, edit and insert operations are only available if a single item is selected. The delete operation works when the selection has one or more items.
Depending upon how the TabularEditor and adapter are specified, drag and drop operations may also be available. If multiple items are selected and the user drags one of the selected items, all selected items will be included in the drag operation. If the user drags a non-selected item, only that item will be dragged.
The editor also supports both drag-move and drag-copy semantics. A drag-move operation means that the dragged items will be sent to the target and removed from the list data. A drag-copy operation means that the dragged items will be sent to the target, but will not be deleted from the Item data. Note that in a drag-copy operation, if you do not want the target to receive the same data contained in the list, then you must return a copy or clone of the data when the editor requests the drag data from the adapter.
You can prevent drag-move operations by making sure that the TabularEditor drag_move trait is set to False (the default).
Note that the default operation when a user begins a drag operation is drag_move. A drag-copy operation occurs when the user also holds the Ctrl key down during the drag operation (the mouse pointer changes to indicate the change in drag semantics). If drag_move operations are disabled by setting the TabularEditor drag_move trait to False, any drag-move operation is automatically treated as a drag_copy.
The tabular editor only allows the user to edit the first column of data in the table (a restriction imposed by the underlying OS widget). If the 'edit' operation is enabled, the user can begin editing the first column either by clicking on the row twice, or by selecting the row and pressing the Enter or Escape key.
Finally, the user can resize columns in the table by dragging the column title dividers left or right with the mouse. Once resized in this manner, the column remains that size until the user resizes the column again. This is true even if you assigned a dynamic width to the column (see the TabularAdapter section for more information about what this means). If the user wants to allow a previously user-sized column to be restored to its original developer specified size again, they must right-click on the column title to release its user specified size and restore its original size.
If you enable persistence for the editor by specifying a non-empty id trait for the editor's Item and View objects, any user specified column widths will be saved across application sessions.
The power and flexibility of the tabular editor is mostly a result of the TabularAdapter class, which is the base class from which all tabular editor adapters must be derived.
The TabularEditor object interfaces between the underlying toolkit widget and your program, while the TabularAdapter object associated with the editor interfaces between the editor and your data.
The design of the TabularAdapter base class is such that it tries to make simple cases simple and complex cases possible. How it accomplishes this is what we'll be discussing in the following sections.
First up is the TabularAdapter columns trait, which is a list of values which define, in presentation order, the set of columns to be displayed by the associated TabularEditor.
Each entry in the columns list can have one of two forms:
where string is the user interface name of the column (which will appear in the table column header) and any is any value that you want to use to identify that column to your adapter. Normally this value is either a trait name or an integer index value, but it can be any value you want. If only string is specified, then any is the index of the string within columns.
For example, say you want to display a table containing a list of tuples, each of which has three values: a name, an age, and a weight. You could then use the following value for the columns trait:
columns = [ 'Name', 'Age', 'Weight' ]
By default, the any values (also referred to in later sections as the column ids) for the columns will be the corresponding tuple index values.
Say instead that you have a list of Person objects, with name, age and weight traits that you want to display in the table. Then you could use the following columns value instead:
columns = [ ( 'Name', 'name' ),
( 'Age', 'age' ),
( 'Weight', 'weight' ) ]
In this case, the column ids are the names of the traits you want to display in each column.
Note that it is possible to dynamically modify the contents of the columns trait while the TabularEditor is active. The TabularEditor will automatically modify the table to show the new set of defined columns.
In this section, we'll describe the core interface to the TabularAdapter class. This is the actual interface used by the TabularEditor to access your data and display attributes. In the most complex data representation cases, these are the methods that you must override in order to have the greatest control over what the editor sees and does.
However, the base TabularAdapter class provides default implementations for all of these methods. In subsequent sections, we'll look at how these default implementations provide simple means of customizing the adapter to your needs. But for now, let's start by covering the details of the core interface itself.
To reduce the amount of repetition, we'll use the following definitions in all of the method argument lists that follow in this section:
The adapter interface consists of a number of methods which can be divided into two main categories: those which are sensitive to the type of a particular table item, and those which are not. We'll begin with the methods that are sensitive to an item's type:
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.
Returns the width to use for a specified column. The result can either be a float or integer value.
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.
Returns a boolean value indicating whether the user can edit a specified object.trait[row] item.
A True result indicates that the value can be edited, while a False result indicates that it cannot.
Returns the value to be dragged for a specified object.trait[row] item. 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.
Returns whether the specified value can be dropped on the specified object.trait[row] item. 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.
Returns how to handle a specified value being dropped on a specified object.trait[row] item. The possible return values are:
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.
Returns the font to use for displaying a specified object.trait[row] item.
A result of None means use the default font; otherwise a wx.Font object should be returned. Note that all columns for the specified table row will use the font value returned.
Returns the text color to use for a specified object.trait[row] item.
A result of None means use the default text color; otherwise a wx.Colour object should be returned. Note that all columns for the specified table row will use the text color value returned.
Returns the background color to use for a specified object.trait[row] item.
A result of None means use the default background color; otherwise a wx.Colour object should be returned. Note that all columns for the specified table row will use the background color value returned.
Returns the image to display for a specified object.trait[row].column item.
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.
Returns the Python formatting string to apply to the specified object.trait[row].column item in order to display it in the table.
The result can be any Python string containing exactly one Python formatting sequence, such as '%.4f' or '(%5.2f)'.
Returns a string containing the text to display for a specified object.trait[row].column item.
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.
Sets the value for the specified object.trait[row].column item to the string specified by text.
If the underlying data does not store the value as text, it is your responsibility to convert text to the correct representation used. This method is called when the user completes an editing operation on a table cell.
Returns a string containing the tooltip to display for a specified object.trait[row].column item.
You should return the empty string if you do not wish to display a tooltip.
The following are the remaining adapter methods, which are not sensitive to the type of item or column data:
Returns the specified object.trait[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).
Returns the number of row items in the specified object.trait list.
The result should be an integer greater than or equal to 0.
Deletes the specified object.trait[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.
Inserts value at the specified object.trait[row] index. The specified value can be:
The adapter can still choose not to insert the item into the data, although that may prove confusing to the user.
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.
Having just taken a look at the core TabularAdapter interface, you might now be thinking that there are an awful lot of methods that need to be specified to get an adapter up and running. But as we mentioned earlier, TabularAdapter is not an abstract base class. It is a concrete base class with implementations for each of the methods in its interface. And the implementations are written in such a way that you will hopefully hardly ever need to override them.
In this section, we'll explain the general implementation style used by these methods, and how you can take advantage of them in creating your own adapters.
One of the things you probably noticed as you read through the core adapter interface section is that most of the methods have names of the form: get_xxx or set_xxx, which is similar to the familiar getter/setter pattern used when defining trait properties. The adapter interface is purposely defined this way so that it can expose and leverage a simple set of design rules.
The design rules are followed consistently in the implementations of all of the adapter methods described in the first section of the core adapter interface, so that once you understand how they work, you can easily apply the design pattern to all items in that section. Then, only in the case where the design rules will not work for your application will you ever have to override any of those TabularAdapter base class method implementations.
So the first thing to understand is that if an adapter method name has the form: get_xxx or set_xxx it really is dealing with some kind of trait called xxx, or which contains xxx in its name. For example, the get_alignment method retrieves the value of some alignment trait defined on the adapter. In the following discussion we'll simply refer to an attribute name generically as attribute, but you will need to replace it by an actual attribute name (e.g. alignment) in your adapter.
The next thing to keep in mind is that the adapter interface is designed to easily deal with items that are not all of the same type. As we just said, the design rules apply to all adapter methods in the first group, which were defined as methods which are sensitive to an item's type. Item type sensitivity plays an important part in the design rules, as we will see shortly.
With this in mind, we now describe the simple design rules used by the first group of methods in the TabularAdapter class:
When getting or setting an adapter attribute, the method first retrieves the underlying item for the specified data row. The item, and type (i.e. class) of the item, are then used in the next rule.
The method gets or sets the first trait it finds on the adapter that matches one of the following names:
where:
Note that this last rule always finds a matching trait, since the TabularAdapter base class provides traits that match the simple attribute form for all attributes these rules apply to. Some of these are simple traits, while others are properties. We'll describe the behavior of all these default traits shortly.
The basic idea is that rather than override the first group of core adapter methods, you simply define one or more simple traits or trait properties on your TabularAdapter subclass that provide or accept the specified information.
All of the adapter methods in the first group provide a number of arguments, such as object, trait, row and column. In order to define a trait property, which cannot be passed this information directly, the adapter always stores the arguments and values it computes in the following adapter traits, where they can be easily accessed by a trait getter or setter method:
As mentioned previously, the TabularAdapter class provides trait definitions for all of the attributes these rules apply to. You can either use the default values as they are, override the default, set a new value, or completely replace the trait definition in a subclass. A description of the default trait implementation for each attribute is as follows:
The default value for a new row.
The default value is the empty string, but you will normally need to assign a different (default) value.
The default Python formatting string for a column item.
The default value is '%s' which will simply convert the column item to a displayable string value.
The text to display for the column item.
The implementation of the property checks the type of the column's column id:
Note that format refers to the value returned by a call to get_format for the current column item.
The text color for a row item.
The property implementation checks to see if the current table row is even or odd, and based on the result returns the value of the even_text_color or odd_text_color trait if the value is not None, and the value of the default_text_color trait if it is. The definition of these additional traits are as follows:
Remember that a None value means use the default text color.
The background color for a row item.
The property implementation checks to see if the current table row is even or odd, and based on the result returns the value of the even_bg_color or odd_bg_color trait if the value is not None, and the value of the default_bg_color trait if it is. The definition of these additional traits are as follows:
Remember that a None value means use the default background color.
The alignment to use for a specified column.
The default value is 'left'.
The width of a specified column.
The default value is -1, which means a dynamically sized column with an unnormalized fractional value of 0.1.
Specifies whether the text value of the current item can be edited.
The default value is True, which means that the user can edit the value.
A property which returns the value to be dragged for a specified row item.
The property implementation simply returns the current row item.
Specifies whether the specified value be dropped on the current item.
The default value is False, meaning that the value cannot be dropped.
Specifies where a dropped item should be placed in the table relative to the item it is dropped on.
The default value is 'after'.
The font to use for the current item.
The default value is the standard default Traits font value.
The name of the default image to use for a column.
The default value is None, which means that no image will be displayed for the column.
# The text of a row/column item: text = Property
The tooltip information for a column item.
The default value is the empty string, which means no tooltip information will be displayed for the column.
The preceding discussion applies to all of the methods defined in the first group of TabularAdapter interface methods. However, the design rules do not apply to the remaining five adapter methods, although they all provide a useful default implementation:
Returns the value of the object.trait[row] item.
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.
Note that this method is the one called in the first design rule described previously to retrieve the item at the current table row.
Returns the number of items in the specified object.trait list.
Again, 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.
Deletes the specified object.trait[row] item.
The default implementation assumes the trait defined by object.trait is a mutable sequence and attempts to perform a del object.trait[row] operation.
Inserts a new value at the specified object.trait[row] index.
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.
Returns a new default value for the specified object.trait list.
The default implementation simply returns the value of the adapter's default_value trait.
Having now learned about the core adapter interface as well as the design rules supported by the default method implementations, you're probably wondering how you can use a TabularAdapter for creating a real user interface.
So in this section we'll cover a simple example of creating a TabularAdapter subclass to try and show how all of the pieces fit together.
In subsequent tutorials, we'll provide complete examples of creating user interfaces using both the TabularEditor and TabularAdapter in combination.
For this example, let's assume we have the following two classes:
class Person ( HasTraits ):
name = Str
age = Int
address = Str
class MarriedPerson ( Person ):
partner = Instance( Person )
where Person represents a single person, and MarriedPerson represents a married person and is derived from Person but adds the partner trait to reference the person they are married to.
Now, assume we also have the following additional class:
class Report ( HasTraits ):
people = List( Person )
which has a people trait which contains a list of both Person and MarriedPerson objects, and we want to create a tabular display showing the following information:
In addition:
Given this set of requirements, we can now define the following TabularAdapter subclass:
class ReportAdapter ( TabularAdapter ):
columns = [ ( 'Name', 'name' ),
( 'Age', 'age' ),
( 'Address', 'address' )
( 'Spouse', 'spouse' ) ]
font = 'Courier 10'
age_alignment = Constant( 'right' )
MarriedPerson_age_image = Property
MarriedPerson_bg_color = Color( 0xE0E0FF )
MarriedPerson_spouse_text = Property
Person_spouse_text = Constant( '' )
def _get_MarriedPerson_age_image ( self ):
if self.item.age < 18:
return 'red_flag'
return None
def _get_MarriedPerson_spouse_text ( self ):
return self.item.partner.name
Hopefully, this simple example conveys some of the power and flexibility that the TabularAdapter class provides you. But, just in case it doesn't, let's go over some of the more interesting details:
Although this is completely subjective, some of the things that the author feels stand out about this approach are:
Look for a complete traits UI example based on this sample problem definition in the Single and Married Person Example tutorial in this section.
Now, as the complexity of a tabular view increases, the definition of the TabularAdapter class could possibly start to get large and unwieldy. At this point we could begin refactoring our design to use the ITabularAdapter interface and AnITabularAdapter implementation class to create sub-adapters that can be added to our TabularAdapter subclass to extend its functionality even further. Creating sub-adapters and adding them via the TabularAdapter adapters trait is a topic covered in a follow-on tutorial.