Range widgets

Range widgets denote any widget class, that is based on the abstract Range widget class. Those widgets usually support setting a value within a defined value range, such as scaling widgets or scrollbars.

Range

The Range widget class is an abstract class, which enables inheriting classes to set and use value ranges. It can make use of float values, thus providing a high and for most cases exact resolution of values and it supports setting minimum and maximum values as well as stepwise increments.

You usually will not create a Range object directly, but inherit from it in your own widget classes. The constructor of a Range

range = Range (minimum, maximum, step)
        
needs some arguments, which define the minimum range value, the maximum range value and the step range to use for increments or decrements of the Range.

The minimum attribute defines the lower limit of the value range it serves, while the maximum attribute defines the upper limit of it. Both can be set either via the attribute or the set_minimum() or set_maximum() methods.

if range.minimum < 0:
    range.set_minimum (0)
if range.maximum > 100:
    range.set_maximum (100)
        

The step attribute of the Range is useful to increment or decrement the value of it in a constant manner. By default it is set to 1.0.

range.step = 10.0
range.set_step (-3.2)
        
It is possible to set the step attribute to a negative value. Although this is confusing in most cases (the in- and decrements will be swapped), it can be useful for the application logic in some (rare) situations.

The value of the Range can be read and set via the value attribute and set_value() method. It can not grow beyond the upper or lower limit of the Range. Assigning a value not within those limitations will let it raise an exception.

range.value = 4.59
range.set_value (4.59)
        

For an efficient usage of the Range within loops, etc. the increase() and decrease() are supplied by it.

range.increase ()
range.decrease ()
        
Those will in- or decrease the value of the range by the set step value, but respect its upper and lower limit. Using those both methods will let you avoid additional exception handling code or limit checks.

The Range raises a SIG_VALCHANGED event, whenever its value changed. This means a real value change, reassignments of the same value are ignored. The following example code shows this behaviour.

def val_changed (range):
   print "The value changed to: %d" % range.value

range.connect_signal (SIG_VALCHANGED, val_changed, range)
if range.value != 10.0:
    range.value = 10.0 # Signal handler is invoked.
range.value = 10.0     # Nothing happens.
        

Scale

Scale widgets separate in an abstract Scale base class, which mainly contains internal code needed by its both subclasses, the VScale and HScale widget. A Scale, inherited from the Range, is a widget that lets you pick a value from a range using a vertical (VScale) or horizontal (HScale) slider. Those both widgets only differ in their appearance.

To create a HScale or VScale widget, you typically will use the same constructor syntax as for the Range widget.

hscale = HScale (minimum, maximum, step)
vscale = VScale (minimum, maximum, step)
        
As well as for the Range, the minimum and maximum arguments set the upper an lower limit of the value range, while the step argument sets the step range and defaults to 1.0.

The most important attributes and methods are already explained in the section called “Range”, so they will not be explained here again.

The Scale widgets listen to the three available mouse events,

  • SIG_MOUSEDOWN - Invoked, when a mouse button is pressed down on the Scale.

  • SIG_MOUSEUP - Invoked, when a mouse button is released on the Scale.

  • SIG_MOUSEMOVE - Invoked, when the mouse moves over the Scale.

ScrollBar

Similar to the Scale widget, the ScrollBar lets you pick a value from a range, but additionally contains two buttons at its ends, which allow the user to increment or decrement the value stepwise. The ScrollBar is usually not used as standalone widget, but instead serves as control in more complex widgets, which need scrolling abilities.

In contrast to the Scale, the ScrollBar uses a slider with a variable size, which depends on the length of the ScrollBar and the maximum value of it. The slider however has a defined minimum size, so that it will not shrink to an unusable size by default.

The procedure to create a ScrollBar is similar to the Scale and Range.

hscrollbar = HScrollBar (minimum, maximum, step)
vscrollbar = VScrollBar (minimum, maximum, step)
        

The most important attributes and methods are already explained in the section called “Scale” and the section called “Range”, so they will not be explained here again.

The Scrollbar widgets listen to the three available mouse events,

  • SIG_MOUSEDOWN - Invoked, when a mouse button is pressed down on the ScrollBar.

  • SIG_MOUSEUP - Invoked, when a mouse button is released on the ScrollBar.

  • SIG_MOUSEMOVE - Invoked, when the mouse moves over the ScrollBar.