1# -------------------------------------------------------------------------
2#
3#  Copyright (c) 2007, Enthought, Inc.
4#  All rights reserved.
5#
6#  This software is provided without warranty under the terms of the BSD
7#  license included in LICENSE.txt and may be redistributed only
8#  under the conditions described in the aforementioned license.  The license
9#  is also available online at http://www.enthought.com/licenses/BSD.txt
10#
11#  Thanks for using Enthought open source!
12#
13#  Author: David C. Morrill
14#  Date:   05/20/2007
15#
16# -------------------------------------------------------------------------
17
18""" A traits UI editor for editing tabular data (arrays, list of tuples, lists
19    of objects, etc).
20"""
21
22
23
24from pyface.ui_traits import Image
25from traits.api import Str, Bool, Property, List, Enum, Instance
26
27from ..basic_editor_factory import BasicEditorFactory
28
29from ..toolkit import toolkit_object
30
31
32class TabularEditor(BasicEditorFactory):
33    """ Editor factory for tabular editors.
34    """
35
36    # -- Trait Definitions ----------------------------------------------------
37
38    #: The editor class to be created:
39    klass = Property()
40
41    #: Should column headers (i.e. titles) be displayed?
42    show_titles = Bool(True)
43
44    #: Should row headers be displayed (Qt4 only)?
45    show_row_titles = Bool(False)
46
47    #: The optional extended name of the trait used to indicate that a complete
48    #: table update is needed:
49    update = Str()
50
51    #: The optional extended name of the trait used to indicate that the table
52    #: just needs to be repainted.
53    refresh = Str()
54
55    #: Should the table update automatically when the table item's contents
56    #: change? Note that in order for this feature to work correctly, the editor
57    #: trait should be a list of objects derived from HasTraits. Also,
58    #: performance can be affected when very long lists are used, since enabling
59    #: this feature adds and removed Traits listeners to each item in the list.
60    auto_update = Bool(False)
61
62    #: The optional extended name of the trait to synchronize the selection
63    #: values with:
64    selected = Str()
65
66    #: The optional extended name of the trait to synchronize the selection rows
67    #: with:
68    selected_row = Str()
69
70    #: Whether or not to allow selection.
71    selectable = Bool(True)
72
73    #: The optional extended name of the trait to synchronize the activated value
74    #: with:
75    activated = Str()
76
77    #: The optional extended name of the trait to synchronize the activated
78    #: value's row with:
79    activated_row = Str()
80
81    #: The optional extended name of the trait to synchronize left click data
82    #: with. The data is a TabularEditorEvent:
83    clicked = Str()
84
85    #: The optional extended name of the trait to synchronize left double click
86    #: data with. The data is a TabularEditorEvent:
87    dclicked = Str()
88
89    #: The optional extended name of the trait to synchronize right click data
90    #: with. The data is a TabularEditorEvent:
91    right_clicked = Str()
92
93    #: The optional extended name of the trait to synchronize right double
94    #: clicked data with. The data is a TabularEditorEvent:
95    right_dclicked = Str()
96
97    #: The optional extended name of the trait to synchronize column
98    #: clicked data with. The data is a TabularEditorEvent:
99    column_clicked = Str()
100
101    #: The optional extended name of the trait to synchronize column
102    #: right clicked data with. The data is a TabularEditorEvent:
103    column_right_clicked = Str()
104
105    #: The optional extended name of the Event trait that should be used to
106    #: trigger a scroll-to command. The data is an integer giving the row.
107    scroll_to_row = Str()
108
109    #: The optional extended name of the Event trait that should be used to
110    #: trigger a scroll-to command. The data is an integer giving the column.
111    scroll_to_column = Str()
112
113    #: Controls behavior of scroll to row
114    scroll_to_row_hint = Enum("center", "top", "bottom", "visible")
115
116    #: Can the user edit the values?
117    editable = Bool(True)
118
119    #: Can the user edit the labels (i.e. the first column)
120    editable_labels = Bool(False)
121
122    #: Are multiple selected items allowed?
123    multi_select = Bool(False)
124
125    #: Should horizontal lines be drawn between items?
126    horizontal_lines = Bool(True)
127
128    #: Should vertical lines be drawn between items?
129    vertical_lines = Bool(True)
130
131    #: Should the columns automatically resize? Don't allow this when the amount
132    #: of data is large.
133    auto_resize = Bool(False)
134
135    #: Should the rows automatically resize (Qt4 only)? Don't allow
136    #: this when the amount of data is large.
137    auto_resize_rows = Bool(False)
138
139    #: Whether to stretch the last column to fit the available space.
140    stretch_last_section = Bool(True)
141
142    #: The adapter from trait values to editor values:
143    adapter = Instance("traitsui.tabular_adapter.TabularAdapter", ())
144
145    #: What type of operations are allowed on the list:
146    operations = List(
147        Enum("delete", "insert", "append", "edit", "move"),
148        ["delete", "insert", "append", "edit", "move"],
149    )
150
151    #: Are 'drag_move' operations allowed (i.e. True), or should they always be
152    #: treated as 'drag_copy' operations (i.e. False):
153    drag_move = Bool(True)
154
155    #: The set of images that can be used:
156    images = List(Image)
157
158    def _get_klass(self):
159        """ Returns the toolkit-specific editor class to be instantiated.
160        """
161        return toolkit_object("tabular_editor:TabularEditor")
162