1
.. index:: View; customizing
3
.. _customizing-a-view:
9
As shown in the preceding two chapters, it is possible to specify a window in
10
TraitsUI simply by creating a View object with the appropriate contents. In
11
designing real-life applications, however, you usually need to be able to
12
control the appearance and behavior of the windows themselves, not merely their
13
content. This chapter covers a variety of options for tailoring the appearance
14
of a window that is created using a View, including the type of window that a
15
View appears in, the :term:`command button`\ s that appear in the window, and
16
the physical properties of the window.
18
.. index:: kind attribute
20
.. _specifying-window-type-the-kind-attribute:
22
Specifying Window Type: the **kind** Attribute
23
----------------------------------------------
25
Many types of windows can be used to display the same data content. A form can
26
appear in a window, a wizard, or an embedded panel; windows can be *modal*
27
(i.e., stop all other program processing until the box is dismissed) or not, and
28
can interact with live data or with a buffered copy. In TraitsUI, a single View
29
can be used to implement any of these options simply by modifying its **kind**
30
attribute. There are seven possible values of **kind**:
32
.. index:: modal; window kind, live; window kind, livemodal window kind
33
.. index:: nonmodal window kind, wizard; window kind, panel; window kind
34
.. index:: subpanel; window kind
44
These alternatives are described below. If the **kind** attribute of a View
45
object is not specified, the default value is 'modal'.
47
.. index:: windows; stand-alone, modal; definition, live; definition
49
.. _stand-alone-windows:
54
The behavior of a stand-alone TraitsUI window can vary over two significant
55
degrees of freedom. First, it can be :term:`modal`, meaning that when the window
56
appears, all other GUI interaction is suspended until the window is closed; if
57
it is not modal, then both the window and the rest of the GUI remain active and
58
responsive. Second, it can be :term:`live`, meaning that any changes that the
59
user makes to data in the window is applied directly and immediately to the
60
underlying model object or objects; otherwise the changes are made to a copy of
61
the model data, and are only copied to the model when the user commits them
62
(usually by clicking an :guilabel:`OK` or :guilabel:`Apply` button; see
63
:ref:`command-buttons-the-buttons-attribute`). The four possible combinations of
64
these behaviors correspond to four of the possible values of the 'kind '
65
attribute of the View object, as shown in the following table.
67
.. _matrix-of-traits-ui-windows-table:
69
.. rubric:: Matrix of TraitsUI windows
71
+-------------+----------------+-----------------+
73
+=============+================+=================+
74
|**not live** |:term:`nonmodal`|:term:`modal` |
75
+-------------+----------------+-----------------+
76
|**live** |:term:`live` |:term:`livemodal`|
77
+-------------+----------------+-----------------+
79
All of these window types are identical in appearance. Also, all types support
80
the **buttons** attribute, which is described in
81
:ref:`command-buttons-the-buttons-attribute`. Usually, a window with command
82
buttons is called a :term:`dialog box`.
84
.. TODO: Add diagrams and/or examples to clarify.
86
.. index:: wizard, windows; wizard
93
Unlike a window, whose contents generally appear as a single page or a tabbed
94
display, a :term:`wizard` is presented as a series of pages that a user must
95
navigate sequentially.
97
.. TODO: Add a reference to the section on the organization of Views via
98
Groups, once it's been added.
100
.. TODO: add code and screenshot for a simple tabbed display and of the same
101
View presented as a Wizard.
103
TraitsUI Wizards are always modal and live. They always display a standard
104
wizard button set; i.e., they ignore the **buttons** View attribute. In short,
105
wizards are considerably less flexible than windows, and are primarily suitable
106
for highly controlled user interactions such as software installation.
108
.. index:: panel, subpanel, windows; panel, windows; subpanel
110
.. _panels-and-subpanels:
115
Both dialog boxes and wizards are secondary windows that appear separately from
116
the main program display, if any. Often, however, you might need to create a
117
window element that is embedded in a larger display. For such cases, the
118
**kind** of the corresponding View object should be 'panel' or 'subpanel '.
120
A :term:`panel` is very similar to a window, except that it is embedded in a
121
larger window, which need not be a TraitsUI window. Like windows, panels
122
support the **buttons** View attribute, as well as any menus and toolbars that
123
are specified for the View (see :ref:`menus-and-menu-bars`). Panels are always
126
A :term:`subpanel` is almost identical to a panel. The only difference is that
127
subpanels do not display :term:`command button`\ s even if the View specifies
130
.. Do subpanels support menus and toolbars? If not, add this to the
131
documentation. (If so, why do they?)
133
.. index:: buttons; attribute
135
.. _command-buttons-the-buttons-attribute:
137
Command Buttons: the **buttons** Attribute
138
------------------------------------------
140
A common feature of many windows is a row of command buttons along the bottom of
141
the frame. These buttons have a fixed position outside any scrolled panels in
142
the window, and are thus always visible while the window is displayed. They are
143
usually used for window-level commands such as committing or cancelling the
144
changes made to the form data, or displaying a help window.
146
In TraitsUI, these command buttons are specified by means of the View object's
147
**buttons** attribute, whose value is a list of buttons to display. [6]_
148
Consider the following variation on Example 3:
151
pair: examples; buttons
153
.. _example-4-using-a-view-object-with-buttons:
155
.. rubric:: Example 4: Using a View object with buttons
159
# configure_traits_view_buttons.py -- Sample code to demonstrate
162
from traits.api import HasTraits, Str, Int
163
from traitsui.api import View, Item
164
from traitsui.menu import OKButton, CancelButton
166
class SimpleEmployee(HasTraits):
171
employee_number = Str
174
view1 = View(Item(name = 'first_name'),
175
Item(name = 'last_name'),
176
Item(name = 'department'),
177
buttons = [OKButton, CancelButton])
179
sam = SimpleEmployee()
180
sam.configure_traits(view=view1)
182
The resulting window has the same content as before, but now two buttons are
183
displayed at the bottom: :guilabel:`OK` and :guilabel:`Cancel`:
185
.. figure:: images/ui_for_ex4.jpg
186
:alt: Dialog box with three fields and OK and Cancel buttons.
188
Figure 4: User interface for Example 4
190
There are six standard buttons defined by TraitsUI. Each of the standard
191
buttons has matching a string alias. You can either import and use the button
192
names, or simply use their aliases:
194
.. index:: buttons; standard, UndoButton, ApplyButton, RevertButton, OKButton
195
.. index:: CancelButton
197
.. _command-button-aliases-table:
199
.. rubric:: Command button aliases
201
+--------------+---------------------------+
202
|Button Name |Button Alias |
203
+==============+===========================+
204
|UndoButton |'Undo' |
205
+--------------+---------------------------+
206
|ApplyButton |'Apply' |
207
+--------------+---------------------------+
208
|RevertButton |'Revert' |
209
+--------------+---------------------------+
210
|OKButton |'OK' (case sensitive!) |
211
+--------------+---------------------------+
212
|CancelButton |'Cancel' |
213
+--------------+---------------------------+
215
Alternatively, there are several pre-defined button lists that can be imported
216
from traitsui.menu and assigned to the buttons attribute:
218
.. index:: OKCancelsButtons, ModalButtons, LiveButtons
220
* OKCancelButtons = ``[OKButton, CancelButton ]``
221
* ModalButtons = ``[ ApplyButton, RevertButton, OKButton, CancelButton, HelpButton ]``
222
* LiveButtons = ``[ UndoButton, RevertButton, OKButton, CancelButton, HelpButton ]``
224
Thus, one could rewrite the lines in Example 4 as follows, and the
225
effect would be exactly the same::
227
from traitsui.menu import OKCancelButtons
229
buttons = OKCancelButtons
233
The special constant NoButtons can be used to create a window or panel
234
without command buttons. While this is the default behavior, NoButtons can
235
be useful for overriding an explicit value for **buttons**. You can also specify
236
``buttons = []`` to achieve the same effect. Setting the **buttons** attribute
237
to an empty list has the same effect as not defining it at all.
239
It is also possible to define custom buttons and add them to the **buttons**
240
list; see :ref:`custom-command-buttons` for details.
242
.. index:: View; attributes, attributes; View
244
.. _other-view-attributes:
246
Other View Attributes
247
---------------------
249
.. index:: dock attribute; View, height attribute; View, icon attribute
250
.. index:: image attribute; View, item_theme attribute; View
251
.. index:: label_theme attribute; View, resizable attribute; View
252
.. index:: scrollable attribute, statusbar attribute, style attribute; View
253
.. index:: title attribute, width attribute; View, x attribute, y attribute
255
.. _attributes-of-view-by-category-table:
257
.. rubric:: Attributes of View, by category
259
+----------+---------------------+---------------------------------------------+
260
|Category |Attributes |Description |
261
+==========+=====================+=============================================+
262
|Window |* **dock** |These attributes control the visual |
263
|display |* **height** |properties of the window itself, regardless |
264
| |* **icon** |of its content. |
266
| |* **item_theme** |.. index:: close_result attribute |
267
| |* **label_theme** |.. index:: handler attribute |
268
| |* **resizable** |.. index:: key_bindings attribute |
269
| |* **scrollable** |.. index:: menubar attribute |
270
| |* **statusbar** |.. index:: model_view attribute |
271
| |* **style** |.. index:: on_apply attribute |
272
| |* **title** |.. index:: toolbar attribute |
273
| |* **width** |.. index:: updated attribute |
274
| |* **x** |.. index:: content attribute; View |
275
| |* **y** |.. index:: drop_class attribute |
276
+----------+---------------------+---------------------------------------------+
277
|Command |* **close_result** |TraitsUI menus and toolbars are generally |
278
| |* **handler** |implemented in conjunction with custom |
279
| |* **key_bindings** |:term:`Handler`\ s; see |
280
| |* **menubar** |:ref:`menus-and-menu-bars` for details. The |
281
| |* **model_view** |**key_bindings** attribute references the set|
282
| |* **on_apply** |of global key bindings for the view. |
284
| |* **updated** |.. index:: export attribute; View |
285
| | |.. index:: imports attribute |
286
| | |.. index:: object attribute; View |
287
+----------+---------------------+---------------------------------------------+
288
|Content |* **content** |The **content** attribute is the top-level |
289
| |* **drop_class** |Group object for the view. The **object** |
290
| |* **export** |attribute is the object being edited. The |
291
| |* **imports** |**imports** and **drop_class** attributes |
292
| |* **object** |control what objects can be dragged and |
293
| | |dropped on the view. |
295
| | |.. index:: help attribute; View |
296
| | |.. index:: help_id attribute; View |
297
+----------+---------------------+---------------------------------------------+
298
|User help |* **help** |The **help** attribute is a deprecated way to|
299
| |* **help_id** |specify that the View has a Help button. Use |
300
| | |the buttons attribute instead (see |
301
| | |:ref:`command-buttons-the-buttons-attribute` |
302
| | |for details). The **help_id** attribute is |
303
| | |not used by Traits, but can be used by a |
304
| | |custom help handler. |
306
| | |.. index:: id attribute; View |
307
+----------+---------------------+---------------------------------------------+
308
|Unique |* **id** |The **id** attribute is used as a key to save|
309
|identifier| |user preferences about a view, such as |
310
| | |customized size and position, so that they |
311
| | |are restored the next time the view is |
312
| | |opened. The value of **id** must be unique |
313
| | |across all Traits-based applications on a |
314
| | |system. If no value is specified, no user |
315
| | |preferences are saved for the view. |
316
+----------+---------------------+---------------------------------------------+
319
.. rubric:: Footnotes
321
.. [6] Actually, the value of the **buttons** attribute is really a list of
322
Action objects, from which GUI buttons are generated by TraitsUI. The
323
Action class is described in :ref:`actions`.
added
removed
docs/source/traitsui_user_manual/custom_view.rst
