Debian Codegraph @

traitsui/examples/demo/Advanced/Scrubber_editor_demo.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 This example demonstrates several different variations on using the
13 ScrubberEditor. A 'scrubber' is a type of widget often seen in certain types
14 of applications, such as video editing, image editing, 3D graphics and
15 animation.
16
17 These types of programs often have many parameters defined over various ranges
18 that the user can tweak to get varying effects or results. Because the number
19 of parameters is typically fairly large, and the amount of screen real estate is
20 fairly limited, these program often use 'scrubbers' to allow the user to adjust
21 the parameter values.
22
23 A scrubber often looks like a simple text field. The user can type in new
24 values, if they need a precise setting, or simply drag the mouse over the value
25 to set a new value, much like dragging a slider control. The visual feedback
26 often comes in the form of seeing both the text value of the parameter change
27 and the effect that the new parameter value has on the underlying model.
28
29 For example, in a 3D graphics program, there might be a scrubber for
30 controlling the rotation of the currently selected object around the Y-axis.
31 As the user scrubs the rotation parameter, they also see the model spin on
32 the screen as well. This visual feedback is what makes a scrubber more useful
33 than a simple text entry field. And the fact that the scrubber takes up no
34 more screen real estate that a text entry field is what makes it more useful
35 than a full-fledged slider in space limited applications.
36
37 The Traits UI ScrubberEditor works as follows:
38
39 - When the mouse pointer moves over the scrubber, the cursor pointer changes
40 shape to indicate that the field has some additional control behavior.
41
42 - The control may optionally change color as well, to visually indicate that
43 the control is 'live'.
44
45 - If you simply click on the scrubber, an active text entry field is
46 displayed, where you can type a new value for the trait, then press the
47 Enter key.
48
49 - If you click and drag while over the scrubber, the value of the trait is
50 modified based on the direction you move the mouse. Right and/or up
51 increases the value, left and/or down decreases the value. Holding the
52 Shift key down while scrubbing causes the value to change by 10 times its
53 normal amount. Holding the Control key down while scrubbing changes the
54 value by 0.1 times its normal amount.
55
56 - Scrubbing is not limited to the area of the scrubber control. You can drag
57 as far as you want in any direction, subject to the maximum limits imposed
58 by the trait or ScrubberEditor definition.
59
60 The ScrubberEditor also supports several different style and functional
61 variations:
62
63 - The visual default is to display only the special scrubber pointer to
64 indicate to the user that 'scrubber' functionality is available.
65
66 - By specifying a 'hover_color' value, you can also have the editor change
67 color when the mouse pointer is over it.
68
69 - By specifying an 'active_color' value, you can have the editor change color
70 while the user is scrubbing.
71
72 - By specifying a 'border_color' value, you can display a solid border around
73 the editor to mark it as something other than an ordinary text field.
74
75 - By specifying an 'increment' value, you can tell the editor what the normal
76 increment value for the scrubber should be. Otherwise, the editor will
77 calculate the increment value itself. Explicitly specifying an increment
78 can be very useful in cases where the underlying trait has an unbounded
79 value, which makes it difficult for the editor to determine what a
80 reasonable increment value might be.
81
82 - The editor will also correctly handle traits with dynamic ranges (i.e.
83 ranges whose high and low limits are defined by other traits). Besides
84 correctly handling the range limits, the editor will also adjust the
85 default tooltip to display the current range of the scrubber.
86
87 In this example, several of the variations described above are shown:
88
89 - A simple integer range with default visual cues.
90
91 - A float range with both 'hover_color' and 'active_color' values specified.
92
93 - An unbounded range with a 'border_color' value specified.
94
95 - A dynamic range. This consists of three scrubbers: one
96 to control the low end of the range, one to control the high end, and one
97 that uses the high and low values to determine its range.
98
99 For comparison purposes, the example also shows the same traits displayed using
100 their default editors.
101
102 Notes:
103
104 - This demo only works on the wx backend.
105 """
106
107 # -- Imports --------------------------------------------------------------
108
109 from traits.api import HasTraits, Range, Float
110
111 from traitsui.api import View, VGroup, HGroup, Item, ScrubberEditor, spring
112
113
114 # -- Shared Item Definition ----------------------------------------
115
116
117 class TItem(Item):
118 editor = ScrubberEditor()
119
120
121 # -- ScrubberDemo Class ---------------------------------------------------
122
123
124 class ScrubberDemo(HasTraits):
125
126 # Define some sample ranges and values:
127 simple_integer = Range(0, 100)
128 rollover_float = Range(-10.0, 10.0)
129 bordered_unbounded = Float()
130 dynamic_low = Range(high=-0.01, value=-10.0)
131 dynamic_high = Range(low=0.01, value=10.0)
132 dynamic_value = Range('dynamic_low', 'dynamic_high', 0.0)
133
134 # Define the demo view:
135 view = View(
136 HGroup(
137 VGroup(
138 Item('simple_integer', editor=ScrubberEditor()),
139 Item(
140 'rollover_float',
141 editor=ScrubberEditor(
142 hover_color=0xFFFFFF, active_color=0xA0CD9E
143 ),
144 ),
145 Item(
146 'bordered_unbounded',
147 editor=ScrubberEditor(
148 hover_color=0xFFFFFF,
149 active_color=0xA0CD9E,
150 border_color=0x808080,
151 ),
152 ),
153 Item('dynamic_low', editor=ScrubberEditor()),
154 Item('dynamic_high', editor=ScrubberEditor()),
155 Item('dynamic_value', editor=ScrubberEditor()),
156 show_border=True,
157 label='Scrubber Editors',
158 ),
159 VGroup(
160 Item('simple_integer'),
161 Item('rollover_float'),
162 Item('bordered_unbounded'),
163 Item('dynamic_low'),
164 Item('dynamic_high'),
165 Item('dynamic_value'),
166 show_border=True,
167 label='Default Editors',
168 ),
169 spring,
170 ),
171 title='Scrubber Editor Demo',
172 )
173
174
175 # -- Create and run the demo ----------------------------------------------
176
177 # Create the demo:
178 demo = ScrubberDemo()
179
180 # Run the demo (if invoked from the command line):
181 if __name__ == '__main__':
182 demo.configure_traits()