1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
.. _widgets:
=======
Widgets
=======
.. py:currentmodule:: pyface
A Widget in Pyface is an object wraps a control from the underlying toolkit
and provides standard traits and methods that abstract the differences
between the interfaces presented by the toolkit widgets.
The public API for every widget is provided by the appropriate interface
class: :class:`~pyface.i_widget.IWidget` and its subclasses such as
:class:`~pyface.i_application_window.IApplicationWindow` and
:class:`~pyface.fields.i_text_field.ITextField`.
The actual implementation is provided by the corresponding toolkit-dependent
:class:`~pyface.widget.Widget` subclass, but with shared functionality split
into separate mixins: :class:`~pyface.i_widget.MWidget` and so on, following
the general design described in the :ref:`overview` section.
Lifecycle
=========
When a :class:`~pyface.widget.Widget` instance is created only the traits
are initialized. The underlying toolkit widget is not created until the
widget's :meth:`~pyface.widget.Widget.create` method is called, which is
responsible for creating the toolkit object, configuring it, and connecting
handlers that react to changes at the toolkit level or on the traits,
keeping the state of the Python class synchronised with the state of the
underlying toolkit object. The :meth:`~pyface.widget.Widget.create` method
calls the :meth:`~pyface.widget.Widget._create_control` method to create the
actual toolkit control and configure it, and also calls the
:meth:`~pyface.widget.Widget._add_event_listeners` method to handle hooking
up the different types of change handlers. Some widget subclasses may do
additional things in their :meth:`~pyface.widget.Widget.create` methods,
as appropriate for their purpose.
To destroy the toolkit object, the :meth:`~pyface.widget.Widget.destroy`
method is called which cleans up the code that listens for changes to the
object, and destroys the underlying toolkit control (and, for most toolkits,
any children). The :meth:`~pyface.widget.Widget.destroy` method
calls the :meth:`~pyface.widget.Widget._remove_event_listeners` method to
handle unhooking of change handlers. Some widget subclasses may do
additional things in their :meth:`~pyface.widget.Widget.destroy` methods.
Basic Interface
===============
Every widget has a :attr:`~pyface.i_widget.IWidget.control` trait which
holds a reference to the toolkit control that is actually doing the work.
Additionally, there is a :attr:`~pyface.i_widget.IWidget.parent` trait
which references the toolkit control which is the parent of the widget's
control, however this may be ``None`` for top-level windows.
Additionally, every widget has two states associated with it: it can be
visible or hidden, and it can be enabled or disabled. The visibile
state is accessible via the :attr:`~pyface.i_widget.IWidget.visible`
trait, or by calling :meth:`~pyface.i_widget.IWidget.show`. Similarly
the enabled state is accessible via the
:attr:`~pyface.i_widget.IWidget.enabled` trait, or by calling
:meth:`~pyface.i_widget.IWidget.enable`.
Widgets also provide a trait :attr:`~pyface.i_widget.IWidget.tooltip` that
provides a string to display to the user when they hover the mouse over the
widget. If the string is empty then there will be no tooltip displayed.
IWidget Subclasses
==================
The key subclasses/subinterfaces of :class:`~pyface.i_widget.IWidget` include
the following.
IWindow
-------
The :class:`~pyface.i_window.IWindow` interface represents a top-level
window, and so provides additional traits such as
:attr:`~pyface.i_window.IWindow.size`,
:attr:`~pyface.i_window.IWindow.position` and
:attr:`~pyface.i_window.IWindow.title`, as well as events for the
window's lifecycle and user interactions.
The :meth:`~pyface.i_window.IWindow.open` and
:meth:`~pyface.i_window.IWindow.close` methods provide the standard
way of bring up non-modal windows and closing them with the option of
a user veto.
Additionally there are convenience methods that create message dialogs
correctly parented to the window.
IDialog
-------
The :class:`~pyface.i_dialog.IDialog` interface represents short-lived,
usually modal, dialog windows. Often these are standard system dialogs,
in which case the class is responsible for configuring and invoking them,
but it also includes subclasses which have custom content.
For modal dialogs, :meth:`~pyface.i_dialog.IDialog.open` is blocking,
and returns the :attr:`~pyface.i_dialog.IDialog.return_code` of the
dialog after the user is done. Typical usage looks like::
dialog = MyModalDialog()
if dialog.open() == OK:
# do something based on dialog state
...
else:
# user cancelled, clean-up if needed and stop
...
For custom dialogs, there are protected methods for creating the contents
of the dialog and its buttons. In most cases you will need to, at a minimum,
override the :meth:`~pyface.i_dialog.IDialog._create_dialog_area` method to
populate the widgets inside the main dialog.
Pyface provides a number of standard dialog classes and convenience functions
to access them.
.. toctree::
:maxdepth: 2
standard_dialogs.rst
IApplicationWindow
------------------
The :class:`~pyface.i_application_window.IApplicationWindow` interface
represents a main window of an application with the associated additional
features which go with these, such as menubars, toolbars, and status bars.
Users can supply
:attr:`~pyface.i_application_window.IApplicationWindow.menu_bar_manager`,
:attr:`~pyface.i_application_window.IApplicationWindow.status_bar_manager`
and :attr:`~pyface.i_application_window.IApplicationWindow.tool_bar_managers`
objects to provide the functionality, and the concrete implementations will
use these to create the toolkit-level objects.
Writers of custom subclasses will have to override the
:meth:`~pyface.i_application_window.IApplicationWindow._create_contents`
method to populate the actual contents of the window.
IField
------
The :class:`~pyface.fields.i_field.IField` interface is the base for widgets
which present a value to be edited by the user, such as text fields, sliders,
combo-boxes and so on. The interface is described in more detail in the
section on :ref:`fields`.
|
