API¶

class SpeedMeter¶

Physical values and their representation¶

value¶

The physical value. Setting it moves the hand.

value is a NumericProperty, float values are ok, and default to 0. If value is lower than min or greater than max, behavior is undefined (it’s up to you to catch the value and apply some behaviour if you’re so inclined).

min¶

The minimum physical value.

min is a NumericProperty, must be an integer and defaults to 0.

max¶

The maximum physical value.

max is a NumericProperty, must be an integer and defaults to 100.

Note that you must have min < max, or undefined results will occur.

tick¶

tick is the physical value between ticks. So for example, if tick is 15, with min = 0 and max = 100, the values represented on the dial will be 0, 15, 30, 45, 60, 75 and 90. Note that, since in this case 15 doesn’t evenly divide the 0..100 interval, the last value isn’t represented, so it is preferable if there is a coherence between min, max and tick, but it won’t prevent the widget from working otherwise.

tick is a NumericProperty, must be an integer and defaults to 10.

subtick¶

subtick is the number of sub-divisions between 2 ticks (without label), thus it is the number of divisions, not a physical value. If it is 0 or 1, there are no subticks.

subtick is a NumericProperty, must be an integer and defaults to 0 (no subtick).

display_first¶

If True (the default), min label isn’t drawn on the dial. This is useful mainly if you draw a (real) clock where min = 0 and max = 12, but you draw only 12 on the clock face and don’t want it to be cluttered by the 0.

You could get a similar result by overriding value_str, but drawing clocks is common enough to deserve this convenience value.

display_first is a BooleanProperty and defaults to True.

display_last¶

If True (the default), the label isn’t drawn on the dial. This function exists mostly by symmetry with display_first.

display_last is a BooleanProperty, and defaults to True.

start_angle¶

end_angle¶

These are the angle at which the dial starts and ends. The basis for the frame is Kivy’s, that is the angles go from 0 to 360 (actually -360 to 360), 0 is up, 90 is right 180 is down and so on, like a map. If start_angle < end_angle, the physical values increase clockwise, they increase counter-clockwise if end_angle > start_angle. So for example, if start_angle = -90 and end_angle = 90, the dial is a half-circle on the upper half, and values are increasing clockwise. If start_angle = 270 (same position as -90 geometrically) and end_angle = 90, the dial is a half-circle on the lower half, and values are increasing counter-clockwise (since start_angle > end_angle). You can play with demo2 to get a feeling of how things influence each others and find the value suiting your needs if you find reasoning on the value too tedious.

start_angle = end_angle is a special case. In that case, the dial is a full circle, and the values increase clockwise. There is no way to have counter-clockwise value increases yet !

start_angle and end_angle are NumericProperty. start_angle defaults to -90 and end_angle defaults to 135.

value_font_size¶

Quite self-explanatory. Most likely, you don’t want to change this.

value_font_size is a NumericProperty, and defaults to 15.

Indication on the dial¶

label¶

If set, the corresponding text is drawn on the dial. By default, the text is at equal distance from min and max and at about 1/3 in the dial. This can be changed with label_radius_ratio and label_angle_ratio.

label is a StringProperty and defaults to ‘’ (nothing to display).

label_font_size¶

Quite self-explanatory.

label_font_size is a NumericProperty, and defaults to 15.

label_icon¶

If set, this is the name of an image (file or atlas part) put on the dial. By default, the text is at equal distance from min and max and at about 1/3 in the dial. This can be changed with label_radius_ratio and label_angle_ratio.

By default, the icon size is half the ‘’‘radius’‘’ of the dial. This can be changed with label_icon_scale.

If both label and label_icon are set, label_icon takes precedence.

label_icon is a StringProperty and defaults to ‘’ (nothing to display).

label_icon_scale¶

The ratio between the radius of the dial and the size of the icon. Default to 0.5, which is more or less balanced. Useful values run from 0 (icon reduced to a single point) to 2.0 (icon covers the surface of the dial).

label_icon_scale is a NumericProperty and defaults to 0.5 (icon is half of the radius).

label_radius_ratio¶

The position of the icon or label from the center of the dial. 0 means the center of the icon is at the center of the dial, 1 that the icon is on the border of the dial, -1 on the border of the dial in the opposite direction. Defaults to 0.3, which puts the icon at a readable place on the dial.

label_radius_ratio is a NumericProperty and defaults to 0.3.

label_angle_ratio¶

The position of the icon or label between the min and max position. Defaults to 0.5, meaning that the icon is at equal distance from the min and max labels (number on the dial). 0 means the icon is on the min label, 1 that it is on the max label. You can’t use this property to go outside of the dial, but you can use a negative label_radius_ratio for that purpose.

label_angle_ratio is a NumericProperty and defaults to 0.5.

needle_color¶

The hand (“needle”) color. This is a string interpreted as an hex_color.

needle_color is a StringProperty and defaults to #6bf2ff, which is close to a slider default color on Linux.

needle_image¶

The hand (“needle”) image.

needle_image is a StringProperty and defaults to ‘needle.png’, a needle picture liberally stolen from the original kivy speedmeter widget ! The widget comes with 2 other images needle2 and needle3.

shadow_color¶: If present, this is the #RGB description of the color of the “shadow” (an arc of circle marking the position of the needle). If it’s not present, there is no shadow. Currently, the shadow width can’t be specified.

Sectors¶

Color sectors can be drawn on the dial, for example to symbolize the cool, warm and overheat part of a dial. This is driven by the sectors and sector_width properties described below.

sectors

This is a list of alternating values and colors. The values are expressed in “physical” terms (a value between min and max), colors are expressed as hex_color strings. If the last value is omitted, it defaults to max. So for example, if your physical values represent the body of human temperature with min=34, max=44, a white arc for hypothermia between 34 and 36° C, green arc between 36 and 38, red between 38 and 42, and nothing after 42 to mean death (!), you do it by putting [34, '#ffffff', 36, '#00ff00', 38, '#ff0000', 42] in sectors. The physical values must be between min and max included, must be sorted in increasing order, and don’t have to be integer values.

sectors is a ListProperty and defaults to [], meaning no sector is drawn.

sector_width¶

This is the width of the sectors. The special value 0 (default) means the whole sector is drawn. Other values indicate the width of the arc, in that case only an arc is drawn.

sector_width is a NumericProperty and defaults to 0.

Other Methods¶

get_value(pos)¶

Parameters:	pos – a pair (x, y).
Returns:	the corresponding physical value

The x,y position has to be inside the dial or None is returned. For example, if you get a MotionEvent, you can find the corresponding physical value (in the min.. max range) with get_value(*motionevent.pos).

collide_point(x, y)¶: This standard widget function is implemented.

value_str(n)¶

Parameters:	n (int) –

This is the method called to convert data n into the string represented on the dial. It defaults to str(int(n)). If you want to have more control over what’s written on the dial, you can derive your own class from SpeedMeter and override this function. See demo1 for an example using fractions of PI.