| 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() |