Debian Codegraph @

traitsui/examples/demo/Advanced/Invalid_state_handling.py

raw
1 # (C) Copyright 2004-2023 Enthought, Inc., Austin, TX
2 # All rights reserved.
3 #
4 # This software is provided without warranty under the terms of the BSD
5 # license included in LICENSE.txt and may be redistributed only under
6 # the conditions described in the aforementioned license. The license
7 # is also available online at http://www.enthought.com/licenses/BSD.txt
8 #
9 # Thanks for using Enthought open source!
10
11 """
12 Sometimes the inputs to a model are not correlated. That is, any valid model
13 input produces a corresponding valid model state. However, in other cases, some
14 or all of the model inputs are correlated. That is, there may exist one or more
15 combinations of individually valid model inputs which produce invalid model
16 states.
17
18 In cases where this can happen, it is very often desirable to warn the user if
19 a particular combination of input values will not produce a usable result. This
20 problem cannot be solved solely though the use of carefully chosen trait types
21 and editors, because each individual input may be valid, but it is the
22 combination of inputs which is invalid.
23
24 Solving this problem therefore typically requires providing a way of determining
25 whether or not the model is in a valid state, and then communicating that
26 information to the user via the user interface.
27
28 This demonstration provides an example of doing this using the TraitEditor's
29 'invalid' trait. Each trait editor has an 'invalid' trait which can be set
30 equal to the name of a trait in the user interface context which contains a
31 boolean value reflecting whether or not the user interface (and underlying
32 model) are in a invalid state or not. A True value for the trait indicates that
33 the editor's current value produces an invalid model state. By associating the
34 same 'invalid' trait with one or more editors in the user interface, the
35 resulting user interface can indicate to the user which combination of input
36 values is producing the invalid state.
37
38 In this example, we have a very simple model which allows the user to control
39 the mass and velocity of a system. The model also defines the kinetic energy
40 of the resulting system. For safety reasons, the kinetic energy of the system
41 should not exceed a certain threshold. If it does, the user should be warned
42 so that they can reduce either or both of the system mass and velocity back down
43 to a safe level.
44
45 In the model, an 'error' property is defined which is True whenever the
46 kinetic energy level of the system exceeds the safety threshold. This trait is
47 then synchronized with the user interface's 'mass', velocity' and 'status'
48 editors, turning them red whenever the model enters an invalid state.
49
50 The 'status' trait is another property, based on the 'error' trait, which
51 provides a human readable description of the current system state.
52
53 Note that in this example, we synchronize the 'error' trait with the user
54 interface using 'sync_to_view' metadata, whose value is a list of user
55 interface editor traits the trait should be synchronized 'to' (i.e. changes to
56 the 'error' trait will be copied to the corresponding trait in the editor, but
57 not vice versa). We could also have explicitly set the 'invalid' trait of each
58 corresponding editor in the view definition to 'error' as well.
59
60 To use the demo, simply use the 'mass' and 'velocity' sliders and observe the
61 changes to the 'kinetic_energy' of the system. When the kinetic energy exceeds
62 50,000, notice how the 'mass', 'velocity' and 'status' fields turn red, and
63 that when the kinetic energy drops below 50,000, the fields return to their
64 normal color.
65 """
66
67 # -- Imports --------------------------------------------------------------
68
69 from traits.api import (
70 HasTraits,
71 Range,
72 Float,
73 Bool,
74 Str,
75 Property,
76 )
77
78 from traitsui.api import View, VGroup, Item
79
80 # -- System Class ---------------------------------------------------------
81
82
83 class System(HasTraits):
84
85 # The mass of the system:
86 mass = Range(0.0, 100.0)
87
88 # The velocity of the system:
89 velocity = Range(0.0, 100.0)
90
91 # The kinetic energy of the system:
92 kinetic_energy = Property(Float, observe='mass, velocity')
93
94 # The current error status of the system:
95 error = Property(
96 Bool,
97 sync_to_view='mass.invalid, velocity.invalid, status.invalid',
98 observe='kinetic_energy',
99 )
100
101 # The current status of the system:
102 status = Property(Str, observe='error')
103
104 view = View(
105 VGroup(
106 VGroup(
107 Item('mass'),
108 Item('velocity'),
109 Item('kinetic_energy', style='readonly', format_str='%.0f'),
110 label='System',
111 show_border=True,
112 ),
113 VGroup(
114 Item('status', style='readonly', show_label=False),
115 label='Status',
116 show_border=True,
117 ),
118 )
119 )
120
121 def _get_kinetic_energy(self):
122 return (self.mass * self.velocity * self.velocity) / 2.0
123
124 def _get_error(self):
125 return self.kinetic_energy > 50000.0
126
127 def _get_status(self):
128 if self.error:
129 return 'The kinetic energy of the system is too high.'
130
131 return ''
132
133
134 # -- Create and run the demo ----------------------------------------------
135
136 # Create the demo:
137 demo = System()
138
139 # Run the demo (if invoked from the command line):
140 if __name__ == '__main__':
141 demo.configure_traits()