NAME
Tk::Gauge - create a multitude of analog gauge widgets.
SYNOPSIS
use Tk::Gauge;
my $g = $mw->Gauge( -option => value );DESCRIPTION
This widget creates an analog gauge. A gauge has various components: a radius highlighted by a circumference, one or more needles, a hub, three granularities of tick marks, one of which has a value label, a caption, title and specialized bands that visually compartmentalize the gauge.
A gauge's appearance is specified by manipulating a set of approximately 60 options, all described below. Given this flexibility one may create instruments including, but not limited to, a 12 or 24 hour clock, CPU meter, voltmeter, fuel and temperature gauge, speedometer and tachometer.
The following option/value pairs are supported (default value in parentheses):
- -background ('white')
-
The gauge's background color.
- -bands (undef)
-
This is the gauge's band(s) descriptor. A band demarcates a section of the gauge; for instance, a tachometer usually has a red band around a portion of its circumference indicating when the engine's RPM has exceeded "redline". The value of -bands must be an array reference, with each element of the array a hash reference having key/value pairs laying out the details of one band. Other than the actual key/value pairs, the format is identical to the -needles option, and you can see samples of that in the EXAMPLES section. Here are the -bands options and their default values:
{ -arccolor => 'white', -minimum => 0, -maximum => 100, -piecolor => 'white', -tag => '', }-arccolor is relevant if -bandstyle => 'band', while -piecolor is relevant if -bandstyle => 'pieslice'.
-minimum must be >= -from and -maximum must be <= -to.
-tag is a string that allows you to provide one custom tag for the band(s).
- -bandplace ('underticks')
-
Controls the placements of the band(s) relative to the gauge tick marks. A value of 'overticks' raises the band(s) above the tick marks and obscures them.
- -bandstyle ('band')
-
Specifies the style of band. The default is an arc-like band. Alternately, a 'pieslice' style is available.
- -bandwidth (10)
-
Specifies the width of the band or the pieslice outline.
- -caption ('')
-
A title placed below the gauge.
- -captioncolor ('black')
-
The caption text color.
- -extent (-270)
-
Specifies the size of the angular range occupied by the arc. The arc's range extends for the specified number of degrees counter-clockwise from the starting angle given by the -start option. Degrees may be negative. If it is greater than 360 or less than -360, then degrees modulo 360 is used as the extent. For more details see the documentation on the arc item in the Canvas man page.
- -fill ('white')
-
The interior color of the gauge.
- -finetickcolor ('black')
-
Color of the fine tick marks.
- -finetickinterval (undef)
-
A positive integer specifying the smallest interval between gauge tick marks.
- -fineticklength (2)
-
Pixel length of fine tick marks.
- -finetickthickness (1)
-
Pixel width of fine tick marks.
- -from (0)
-
Gauge's lower value, which must be an integer >= 0. See the -to option for important additional details.
- -hubcolor ('#ef5bef5bef5b')
-
Color of hub.
- -huboutline ('#ef5bef5bef5b')
-
Color of hub outline.
- -hubplace ('overneedle')
-
The hub is normally placed over the base of the needle(s), but you may specify 'underneedle' if desired.
- -hubradius (5)
-
Radius of the hub.
- -majortickcolor ('black')
-
Color of the major tick marks.
- -majortickinterval (10)
-
A positive integer specifying the largest interval between gauge tick marks.
- -majorticklabelcolor ('black')
-
Major tick marks can be labelled with an integer value of this color.
- -majorticklabelfont ('Helvetica-12')
-
A standard Tk font specification.
- -majorticklabelformat ('%d')
-
A standard C language (s)printf format specification.
- -majorticklabelpad (10)
-
Padding distance between the major tick label and the gauge's circumference.
- -majorticklabelplace ('inside')
-
Major tick label values are normally placed inside the gauge's circumference. Specify 'outside' to place them outside the circumference.
- -majorticklabelscale (1)
-
This is a multiplier that converts a gauge value to a major tick label value.
- -majorticklabelskip (undef)
-
This must be an array reference - the array elements enumerate major tick label values that should NOT be displayed. These are unscaled values.
- -majorticklength (10)
-
Pixel length of major tick marks.
- -majortickthickness (1)
-
Pixel width of major tick marks.
- -margin (10)
-
A margin surrounding all four sides of the gauge, measured in pixels.
- -minortickcolor ('black')
-
Color of the minor tick marks.
- -minortickinterval (undef)
-
A positive integer specifying the middle interval between gauge tick marks.
- -minorticklength (5)
-
Pixel length of minor tick marks.
- -minortickthickness (1)
-
Pixel width of minor tick marks.
- -needles ( [ { %needle_defaults } ] )
-
This is the gauge's needle(s) descriptor. A needle points to a specific gauge value, from -from to -to, by rotating around the hub of the gauge. The value of -needles must be an array reference, with each element of the array a hash reference having key/value pairs laying out the details of one needle. You can see samples of the -needles option in the EXAMPLES section. Here are the -needles options and their default values:
{ -arrowshape => [ 12, 23, 6 ], -color => 'black', -command => undef, -format => '%d', -radius => 96, -showvalue => 0, -tag => '', -title => '', -titlecolor => 'black', -titlefont =>'Helvetica-12', -titleplace => 'south', -variable => \my $var, -width => 5, }-arrowshape describes the shape of a needle's arrow - you can model various arrow shapes by running the widget Canvas demonstration An editor for arrowheads on Canvas lines.
-color is the needle's color.
-command is a Perl/Tk callback that's invoked whenever the needle's -variable changes. The callback should return a true or false value: the needle is only moved if the callback returns true.
-format is a standard C langauge (s)printf format specification used if -showvalue => 1 to display the needle's current value.
-radius is the needle's radius.
-showvalue, if true, displays the needle's current value at its tip, just outside the gauge's circumference.
-tag is a string that allows you to provide one custom tag for the needle.
-title is the needle's title.
-titlecolor is the needle's title color.
-titleplace specifies where the title is displayed relative to the hub, either 'north' or 'south'.
-variable is a reference to the variable that holds the needle's current value. When the variable is written the needle moves, subject to the return value from the needle's -command callback.
-width is the needle's width.
- -needlepad (0)
-
The padding between the tip of a gauge's longest needle and the major tick labels.
- -outline ('black')
-
The gauge's outline color.
- -outlinewidth (2)
-
The pixel width of the gauge outline.
- -start (225)
-
Specifies the beginning of the angular range occupied by the gauge's arc. The value is given in units of degrees measured counterclockwise from the 3-o'clock position; it may be either positive or negative.
- -style ('chord')
-
A gauge is a Canvas arc item, so the -style option specifies the overall appearance of the widget. Beside the default 'chord', other possible values are 'pieslice' and 'arc'. See the Canvas documentation for more details.
- -to (100)
-
The -to option seems obvious enough: it's the gauge's final value, and must be a positive integer > than -from. But this option is more complex, as it's intimately related to the fine, minor and major tick mark intervals, the major tick mark label scale value, and to the overall efficiency of the gauge.
For efficiency you want to make the difference between -to and -from as small as possible. So, looping from 1 to 80 is fine, but a loop from 1 to 8,000 will be very slow and impact the startup time of your application.
Now comes the hard part: specifying -from and -to to play nicely with your tick marks, of which there are three species: major, minor and fine. Essentially, since -from and -to must be positive integers, and the major, minor and fine tick intervals must be positive integers, your job is to find the integral Lowest Common Denominator (iLCD) amongst them all, and to set -majorticklabelscale accordingly.
For instance, suppose you want to make a tachometer to display RPM from zero to 8,000. Do not chose -from => 0 and -to -> 8000! Slow city. If your major tick interval unit is RPM/1000, choose 1 .. 8 instead. Well, maybe.
Now suppose you require a minor tick every 500 RPM. Since any tick interval must be a positive integer, make -to 80, the major tick interval 10, and the minor tick interval 5.
Now suppose your PHB requires a third fine tick interval every 250 RPM. Since any tick interval must be a positive integer, make -to 800, the major tick interval 100, the minor tick interval 50, and the new, fine tick interval, 25. Finally, set the major tick label scale value to 0.01 so the displayed units are 0 .. 8. Whew.
But wait, that's not the iLCD - we can divide everything by 5. So make -to 160, the major tick interval 20, the minor tick interval 10, and the new fine tick interval, 5. Finally, set the major tick label scale value to 0.05. Double whew!
More simply:
my $iLCD = 50; # integral Lowest Common Denominator -finetickinterval => 250 / $iLCD -from => 0 -majortickinterval => 1000 / $iLCD -majorticklabelscale => $iLCD / 1000 -minortickinterval => 500 / $iLCDAnd to scale an actual RPM value: $rpm = 1800 / $iLCD. See the EXAMPLES section.
METHODS
A Tk::Gauge widget is derived from a Tk::Canvas widget and thus has all the standard Canvas methods, plus these:
- centerpoint
-
Returns a list of two integers that are the X and Y Canvas coordinates of the center of the gauge.
- maxradius
-
Returns the radius of the gauge, which is the length of the longest needle plus the needle padding.
- radialpoint
-
Returns a list of two integers that are the X and Y Canvas coordinates of a point that is relative to a gauge's centerpoint and defined by a radius and value from -from to -to.
ADVERTISED WIDGETS
Component subwidgets can be accessed via the Subwidget method. A Tk::Gauge widget is derived from a Tk::Canvas widget and thus has no subwidgets.
ADVERTISED CANVAS TAGS
Tk::Gauge components are simply Canvas items, which are given tags as noted below.
- bands
-
Tag for each band, an arc item. - caption
-
Tag for the caption, a text item. - finetick
-
Tag for each fine tick mark, a line item. - gauge
-
Tag for the gauge, an arc item. - hub
-
Tag for the hub, an oval item. - majortick
-
Tag for each major tick mark, a line item. - minortick
-
Tag for each minor tick mark, a line item. - needle
-
Tag for each needle, a line item. - needlevalue
-
Tag for a needle's value when B<-showvalue> => 1, a text item. - ticklabel
-
Tag for each major tick label, a text item. - title
-
Tag for a needle's title, a text item.
EXAMPLES
1) A 12 hour clock.
my( $hour, $minute );
my $clock = $mw->Gauge(
-extent => -359.9, # 360 loses outline
-from => 0,
-huboutline => 'black',
-majortickinterval => 5,
-majorticklabelscale => 12.0 / 60.0,
-majorticklabelskip => [ 0 ],
-minortickinterval => 1,
-needles => [
{
-radius => 100,
-variable => \$minute,
},
{
-radius => 60,
-variable => \$hour,
},
] ,
-start => 90,
-to => 60,
)->pack;
2) A 24 hour clock.
my( $hour, $minute );
my $clock = $mw->Gauge(
-background => 'bisque',
-extent => -359.9, # 360 loses outline
-fill => 'red',
-from => 0,
-hubcolor => 'gray',
-huboutline => 'black',
-majortickcolor => 'bisque',
-majortickinterval => 5,
-majorticklabelcolor => 'bisque',
-majorticklabelformat => '%02d',
-majorticklabelscale => 24 / 120,
-majorticklabelskip => [ 120 ],
-majorticklength => 15,
-majortickthickness => 3,
-margin => 65,
-minortickinterval => 2,
-minorticklength => 7,
-needles => [
{
-radius => 120,
-variable => \$minute,
-width => 2,
},
{
-color => 'bisque',
-radius => 80,
-variable => \$hour,
},
] ,
-needlepad => 10,
-start => 90,
-to => 120,
)->pack;
# Add the minute ticks and their labels.
my( $center_x, $center_y ) = $clock->centerpoint;
my $radius = $clock->maxradius;
foreach ( 1 .. 12 ) {
my( $x, $y ) = $clock->radialpoint( 120 / 12 * $_, $radius + 20 );
$clock->createText( $x, $y, -text => $_ * 5 );
}
3) A tachometer.
my $iLCD = 50; # integral Lowest Common Denominator
my $tachv;
my $tach = $mw->Gauge(
-start => 225, -extent => -270,
-background => 'black',
-bands => [
{
-arccolor => 'red',
-minimum => 6250 / $iLCD,
-maximum => 8000 / $iLCD,
-tags => 'redtach',
},
],
-bandplace => 'overticks',
-bandwidth => 12,
-fill => 'black',
-finetickinterval => 250 / $iLCD,
-fineticklength => 5,
-finetickcolor => 'white',
-from => 0,
-highlightthickness => 0,
-hubcolor => 'gray21',
-huboutline => 'gray21',
-hubplace => 'underneedle',
-hubradius => 20,
-majortickinterval => 1000 / $iLCD,
-majorticklength => 15,
-majortickcolor => 'white',
-majorticklabelcolor => 'white',
-majorticklabelscale => $iLCD / 1000,
-margin => 50,
-minortickinterval => 500 / $iLCD,
-minorticklength => 10,
-minortickcolor => 'white',
-needles => [
{
-radius => 120,
-color => 'orangered2',
-command => [ sub {
print "tach args=@_!\n";
1;
}, 1, 2 ],
-variable => \$tachv,
-width => 3,
-showvalue => 0,
-title => 'x 1000 r / min',
-titlecolor => 'white',
-titleplace => 'north',
-arrowshape => [ 6, 6, 0 ],
},
] ,
-needlepad => 15,
-to => 8000 / $iLCD,
);AUTHOR and COPYRIGHT
sol0@lehigh.edu
Copyright (C) 2004 - 2004, Stephen O. Lidie.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
KEYWORDS
Gauge, Canvas, mega-widget