| 1 | # | ||
| 2 | # This file is part of Tk-RotatingGauge | ||
| 3 | # | ||
| 4 | # This software is copyright (c) 2007 by Jerome Quelin. | ||
| 5 | # | ||
| 6 | # This is free software; you can redistribute it and/or modify it under | ||
| 7 | # the same terms as the Perl 5 programming language system itself. | ||
| 8 | # | ||
| 9 | use 5.008; | ||
| 10 | use warnings; | ||
| 11 | use strict; | ||
| 12 | |||
| 13 | package Tk::RotatingGauge; | ||
| 14 | our $VERSION = '1.100140'; | ||
| 15 | # ABSTRACT: a rotating gauge for tk | ||
| 16 | |||
| 17 | use POSIX qw{ floor }; | ||
| 18 | use Tk; | ||
| 19 | use Tk::Canvas; | ||
| 20 | |||
| 21 | use base qw{ Tk::Derived Tk::Canvas }; | ||
| 22 | Construct Tk::Widget 'RotatingGauge'; | ||
| 23 | |||
| 24 | |||
| 25 | # -- builders & initializers | ||
| 26 | |||
| 27 | |||
| 28 | |||
| 29 | # | ||
| 30 | # Populate - Tk internals | ||
| 31 | # | ||
| 32 | sub Populate { | ||
| 33 | my( $self, $args ) = @_; | ||
| 34 | |||
| 35 | # create the parent widget, specify our options. | ||
| 36 | $self->SUPER::Populate( $args ); | ||
| 37 | $self->ConfigSpecs( | ||
| 38 | -box => [ 'PASSIVE', undef, undef, 'black' ], | ||
| 39 | -from => [ 'PASSIVE', undef, undef, 0 ], | ||
| 40 | -indicator => [ 'PASSIVE', undef, undef, 'red' ], | ||
| 41 | -labels => [ 'PASSIVE', undef, undef, undef ], | ||
| 42 | -orient => [ 'PASSIVE', undef, undef, 'horiz' ], | ||
| 43 | -policy => [ 'PASSIVE', undef, undef, 'rotate' ], | ||
| 44 | -to => [ 'PASSIVE', undef, undef, 100 ], | ||
| 45 | -visible => [ 'PASSIVE', undef, undef, 20 ], | ||
| 46 | -value => [ 'METHOD', undef, undef, undef ], | ||
| 47 | ); | ||
| 48 | |||
| 49 | # store the initial value for after initialization. | ||
| 50 | my $val = exists $args->{-value} ? delete $args->{-value} : 50 ; | ||
| 51 | $self->{Configure}{-value} = $val; | ||
| 52 | |||
| 53 | # let's wait for canvas to be created before initializing the | ||
| 54 | # various canvas items that will compose the gauge. | ||
| 55 | $self->afterIdle( sub { $self->_draw_items } ); | ||
| 56 | } | ||
| 57 | |||
| 58 | |||
| 59 | # -- public methods | ||
| 60 | |||
| 61 | |||
| 62 | sub value { | ||
| 63 | my ($self, $value) = @_; | ||
| 64 | |||
| 65 | my $is_strict = $self->{Configure}{-policy} eq 'strict'; | ||
| 66 | my $from = $self->{Configure}{-from}; | ||
| 67 | my $to = $self->{Configure}{-to}; | ||
| 68 | |||
| 69 | # check out-of-bounds. | ||
| 70 | my $frac = $value - int($value); | ||
| 71 | $value = $is_strict ? $from : $value % ($to-$from) + $frac | ||
| 72 | if $value < $from; | ||
| 73 | $value = $is_strict ? $to : $value % ($to-$from) + $frac | ||
| 74 | if $value >= $to; | ||
| 75 | |||
| 76 | # move the canvas items around. | ||
| 77 | my $v = $self->{Configure}{-value}; | ||
| 78 | my $d = ($v - $value) * $self->{Configure}{-step}; | ||
| 79 | my @delta = $self->{Configure}{-is_horiz} ? ($d, 0) : (0, $d); | ||
| 80 | $self->move( 'grid', @delta ); | ||
| 81 | $self->{Configure}{-value} = $value; | ||
| 82 | } | ||
| 83 | |||
| 84 | |||
| 85 | # -- private methods | ||
| 86 | |||
| 87 | # | ||
| 88 | # $gauge->_draw_items; | ||
| 89 | # | ||
| 90 | # Initialization of the various items that will compose the gauge. | ||
| 91 | # | ||
| 92 | sub _draw_items { | ||
| 93 | my ($self) = @_; | ||
| 94 | |||
| 95 | # get & compute some values... | ||
| 96 | my $w = $self->{Configure}{-width}; | ||
| 97 | my $h = $self->{Configure}{-height}; | ||
| 98 | my $is_horiz = ( 'vertical' !~ /$self->{Configure}{-orient}/ ); | ||
| 99 | $self->{Configure}{-is_horiz} = $is_horiz; | ||
| 100 | |||
| 101 | my $labels = $self->{Configure}{-labels}; | ||
| 102 | my $from = $self->{Configure}{-from}; | ||
| 103 | my $to = $self->{Configure}{-to}; | ||
| 104 | my $visible = $self->{Configure}{-visible}; | ||
| 105 | my $step = ($is_horiz ? $w : $h) / $visible; | ||
| 106 | |||
| 107 | $self->{Configure}{-step} = $step; | ||
| 108 | |||
| 109 | |||
| 110 | # create the central line showing the value. | ||
| 111 | if ( $self->{Configure}{-indicator} ne 'none' ) { | ||
| 112 | my @coords = $is_horiz ? ($w/2 , 0, $w/2 ,$h) : (0, $h/2, $w, $h/2); | ||
| 113 | $self->createLine( @coords, -fill=>$self->{Configure}{-indicator}, -width=>2); | ||
| 114 | } | ||
| 115 | |||
| 116 | # create the top / bottom lines if needed. | ||
| 117 | if ( $self->{Configure}{-box} ne 'none' ) { | ||
| 118 | my @coords; | ||
| 119 | @coords = $is_horiz ? (1, 1, $w, 1) : (1, 1, 1, $h); | ||
| 120 | $self->createLine( @coords, -fill=>$self->{Configure}{-box} ); | ||
| 121 | @coords = $is_horiz ? (1, $h, $w, $h) : ($w, 1, $w, $h); | ||
| 122 | $self->createLine( @coords, -fill=>$self->{Configure}{-box} ); | ||
| 123 | } | ||
| 124 | |||
| 125 | # draw ticks $from .. $to. | ||
| 126 | foreach my $i ( $from .. $to-1 ) { | ||
| 127 | my @coords; | ||
| 128 | my $x = $i * $step; | ||
| 129 | my $text = defined $labels ? $labels->[$i] : $i; | ||
| 130 | @coords = $is_horiz ? ($x, 0, $x, $h) : (0, $x, $w, $x); | ||
| 131 | $self->createLine( @coords, -tags=>'grid' ); | ||
| 132 | @coords = $is_horiz ? ($x+$step/2, $h/2) : ($w/2, $x+$step/2); | ||
| 133 | $self->createText( @coords, -text=>$text, -tags=>'grid' ); | ||
| 134 | } | ||
| 135 | # draw $visible ticks before $from and after $to. | ||
| 136 | foreach my $i ( 0 .. $visible ) { | ||
| 137 | my @coords; | ||
| 138 | # before $from | ||
| 139 | my $x = -($i+1-$from) * $step; | ||
| 140 | my $text = defined $labels ? $labels->[$to-1-$i] : $to-1-$i; | ||
| 141 | @coords = $is_horiz ? ($x, 0, $x, $h) : (0, $x, $w, $x); | ||
| 142 | $self->createLine( @coords, -tags=>'grid' ); | ||
| 143 | @coords = $is_horiz ? ($x+$step/2, $h/2) : ($w/2, $x+$step/2); | ||
| 144 | $self->createText( @coords, -text=>$text, -tags=>'grid' ); | ||
| 145 | # after $to | ||
| 146 | $x = ($to+$i) * $step; | ||
| 147 | $text = defined $labels ? $labels->[$from+$i] : $from+$i; | ||
| 148 | @coords = $is_horiz ? ($x, 0, $x, $h) : (0, $x, $w, $x); | ||
| 149 | $self->createLine( @coords, -tags=>'grid' ); | ||
| 150 | @coords = $is_horiz ? ($x+$step/2, $h/2) : ($w/2, $x+$step/2); | ||
| 151 | $self->createText( @coords, -text=>$text, -tags=>'grid' ); | ||
| 152 | } | ||
| 153 | |||
| 154 | |||
| 155 | # move the gauge to its initial value. | ||
| 156 | my $v = $self->{Configure}{-value}; | ||
| 157 | my $d = ($visible/2-$v) * $step; | ||
| 158 | my @delta = $is_horiz ? ($d,0) : (0,$d); | ||
| 159 | $self->move( 'grid', @delta ); | ||
| 160 | } | ||
| 161 | |||
| 162 | |||
| 163 | 1; | ||
| 164 | |||
| 165 | |||
| 166 | =pod | ||
| 167 | |||
| 168 | =head1 NAME | ||
| 169 | |||
| 170 | Tk::RotatingGauge - a rotating gauge for tk | ||
| 171 | |||
| 172 | =head1 VERSION | ||
| 173 | |||
| 174 | version 1.100140 | ||
| 175 | |||
| 176 | =head1 SYNOPSIS | ||
| 177 | |||
| 178 | use Tk::RotatingGauge; | ||
| 179 | |||
| 180 | my $g = $parent->RotatingGauge( @options ); | ||
| 181 | $g->value(10.5); | ||
| 182 | |||
| 183 | =head1 DESCRIPTION | ||
| 184 | |||
| 185 | This perl module provides a new L<Tk> widget representing a gauge where | ||
| 186 | the current value always stays at the same place. Think about your old | ||
| 187 | mileage counters... | ||
| 188 | |||
| 189 | A rotating gauge item accepts the options described below. | ||
| 190 | |||
| 191 | =head1 ATTRIBUTES | ||
| 192 | |||
| 193 | =head2 -background | ||
| 194 | |||
| 195 | See L<Tk::options> for more information on this standard option. | ||
| 196 | |||
| 197 | =head2 -orient | ||
| 198 | |||
| 199 | See L<Tk::options> for more information on this standard option. | ||
| 200 | |||
| 201 | =head2 -box | ||
| 202 | |||
| 203 | Specifies the color of the lines boxing the gauge. If set to C<none>, | ||
| 204 | then no box will be drawn. Default to C<black>. | ||
| 205 | |||
| 206 | =head2 -from | ||
| 207 | |||
| 208 | A real value corresponding to the minimum end of the gauge. Default to | ||
| 209 | 0. | ||
| 210 | |||
| 211 | =head2 -height | ||
| 212 | |||
| 213 | Specifies a desired window height that the widget should request | ||
| 214 | from its geometry manager. | ||
| 215 | |||
| 216 | =head2 -indicator | ||
| 217 | |||
| 218 | Specifies the color of the central indicator. If set to C<none>, then no | ||
| 219 | central indicator will be drawn. Default to C<red>. | ||
| 220 | |||
| 221 | =head2 -policy | ||
| 222 | |||
| 223 | Define the rotating policy: if set to C<rotate> (default), then | ||
| 224 | out of bounds values will be mod-ed to fit in the wanted scale. If set | ||
| 225 | to C<strict>, values can't go lower than C<-from> or higher than C<to>. | ||
| 226 | |||
| 227 | =head2 -to | ||
| 228 | |||
| 229 | A real value corresponding to the maximum end of the gauge. Default to | ||
| 230 | 100. | ||
| 231 | |||
| 232 | =head2 -value | ||
| 233 | |||
| 234 | The initial value to be shown. Default to 50. | ||
| 235 | |||
| 236 | =head2 -visible | ||
| 237 | |||
| 238 | The number of values to be displayed. Default to 20. | ||
| 239 | |||
| 240 | =head2 -width | ||
| 241 | |||
| 242 | Specifies a desired window width that the widget should request | ||
| 243 | from its geometry manager. | ||
| 244 | |||
| 245 | =head1 METHODS | ||
| 246 | |||
| 247 | =head2 $gauge->value($val); | ||
| 248 | |||
| 249 | Sets the value that the gauge should indicate. | ||
| 250 | |||
| 251 | =for Pod::Coverage::TrustPod Populate | ||
| 252 | |||
| 253 | =head1 SEE ALSO | ||
| 254 | |||
| 255 | You can find more information on this module at: | ||
| 256 | |||
| 257 | =over 4 | ||
| 258 | |||
| 259 | =item * Search CPAN | ||
| 260 | |||
| 261 | L<http://search.cpan.org/dist/Tk-RotatingGauge> | ||
| 262 | |||
| 263 | =item * See open / report bugs | ||
| 264 | |||
| 265 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tk-RotatingGauge> | ||
| 266 | |||
| 267 | =item * Git repository | ||
| 268 | |||
| 269 | L<http://github.com/jquelin/tk-rotatinggauge> | ||
| 270 | |||
| 271 | =item * AnnoCPAN: Annotated CPAN documentation | ||
| 272 | |||
| 273 | L<http://annocpan.org/dist/Tk-RotatingGauge> | ||
| 274 | |||
| 275 | =item * CPAN Ratings | ||
| 276 | |||
| 277 | L<http://cpanratings.perl.org/d/Tk-RotatingGauge> | ||
| 278 | |||
| 279 | =back | ||
| 280 | |||
| 281 | =head1 AUTHOR | ||
| 282 | |||
| 283 | Jerome Quelin | ||
| 284 | |||
| 285 | =head1 COPYRIGHT AND LICENSE | ||
| 286 | |||
| 287 | This software is copyright (c) 2007 by Jerome Quelin. | ||
| 288 | |||
| 289 | This is free software; you can redistribute it and/or modify it under | ||
| 290 | the same terms as the Perl 5 programming language system itself. | ||
| 291 | |||
| 292 | =cut | ||
| 293 | |||
| 294 | |||
| 295 | __END__ |