David Ferrance > GD-Dashboard > GD::Dashboard

Download:
GD-Dashboard-0.04.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.04   Source  

NAME ^

GD::Dashboard - Perl module to create JPEG graphics of meters and dials

SYNOPSIS ^

   my $dash = new GD::Dashboard();

   my $g1 = new GD::Dashboard::Gauge(
                      MIN=>0,
                      MAX=>$empcnt,
                      VAL=>$nopwp_cnt,
                      NA1=>3.14/2+0.85,
                      NA2=>3.14/2-0.85,
                      NX=>51,NY=>77,NLEN=>50                      
            );

   $dash->add_meter('RPM', $g1);
   $dash->write_jpeg('dash.jpg');

The Dashboard module aims at providing users with a quick and easy way to create dashboard or cockpit like JPGs to display key information.

Dashboard supports the following instruments:

  * Gauges with needles
  * Bar type gauges
  * Warning Lights

Dashboard is built on top of GD.pm, Licoln Stein's interface to the GD library.

Classes ^

The dashboard module contains several classes. These classes typically represent either a dashboard or an instrument on the dashboard. The Dashboard object serves as a collection for the instruments.

Dashboard

The Dashboard object serves as the collection object that contains the various instruments in the display. You can add instruments to the dashboard, access instruments through it, or tell it to draw itself.

   my $dash = new Dashboard();
   $dash->add_meter('RPM', $g1);
   $dash->add_meter('Speedo', $g2);
   $dash->write_jpeg('dash.jpg');

add_meter(name, meter)

Adds a meter to the dash. Create the meter using one of the new() constructors first. You can add Gauges, HorizontalBars, and WarningLights. The name is used by the get_meter() function if you need to access the meter later.

get_meter()

Gets a meter by name. When adding a meter, you must give it a name. You can then use get_meter to get the meter object. This is useful when you want to change a setting later, such as the meter's value.

jpeg()

Returns a JPG as a scalar value.

write_jpeg(fname)

Draws the dashboard to a jpg file given by fname.

png()

Returns a PNG as a scalar value.

write_png(fname)

Draws the dashboard to a PNG file given by fname.

Dashboard::Gauge

This class describes a typical dashboard gauge; that is, an instrument that has a needle that rotates. The needle may rotate clockwise or counterclockwise. This gauge is similar to a car speedometer or and airspeed indicator.

new()

Most gauge configuration is done in the constructor. Here is a sample for the gauge included with this package (m1.jpg):

   my $g1 = new GD::Dashboard::Gauge(FNAME=>base_path().'\icons\m1.jpg',
                      MIN=>0,
                      MAX=>$empcnt,
                      VAL=>$nopwp_cnt,
                      NA1=>3.14/2+0.85,
                      NA2=>3.14/2-0.85,
                      NX=>51,NY=>77,NLEN=>50                      
            );

Dashboard::HorizontalBar

This class describes an LED bargraph display of the type often found in a graphical equalizer or, on some cars, the oil condition indicator. It may be all one color, or it may use different colors in different ranges.

The graph goes from left to right and consists of a number of bars, meant to represent LEDs. Bars can be identical or you can configure different bars, for example to have the last couple of bars be red instead of green.

   my $m1 = new GD::Dashboard::HorizontalBar(
                  NX => 235,
                  NY => 348,
                  SPACING => 1
                  );
   $m1->add_bars(20,base_path().'\icons\barlight_on.jpg','\icons\barlight_off.jpg');
   $dash->add_meter('m1',$m1);

new()

add_bars(count, fname, fnameoff)

Call this for each different group of bars you would like to add. Count is the number of bars. Fname is the path to a JPG that represents the bars in their ON state. Fnameoff is an optional filename to a JPG that represents the bar in the off state (these are often just built into the dashboard background, however).

set_reading(val)

Sets the number of bars that are illuminated. So if you have 20 bars defined, 'val' should be between 0 and 20 inclusive.

Dashboard::WarningLight

This behaves like a warning light on a car dashboard. It can be turned on or off. When VAL is 0, this gauge has basically no effect. When VAL is 1, it draws another graphic on the dashboard (this would typically be the warning light on graphic). Consequently, the dashboard graphic should contain the warning light in its "off" state.

new()

Most configuration of the warning light is done via the constructor.

set_reading(val)

Sets the VAL parameter. This can be 0 (warning light off) or 1 (warning light on).

NOTES ^

This is the first release. There are a few things on my mind for 0.02. First, PNG support would be easy to add in. I don't use it so I haven't added it (yet). Email if you want it. Second, all of the meters are probably going to derive from a base class. Haven't had time to change it yet.

Eventually I should pay more attention to the needle drawing in the Gauge class. If your art is really good, the needles bring it down :(

I'm sure the docs could be better.

AUTHOR ^

David Ferrance (dave@ferrance.com)

LICENSE ^

Dashboard: A module for creating dashboard graphics.

Copyright (C) 2002 David Ferrance (dave@ferrance.com). All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

Sample graphics provided by rabia@rabia.com. This module isn't worth much without a good graphics person to provide you with sweet dashboard layouts.

syntax highlighting: