=head1 NAME

Finance::Shares::Lesson3 - Adding colour to charts

=head1 DESCRIPTION

The Finance::Shares suite graphs its results.  The marks on these are controlled by the
L<PostScript::Graph::Style> objects which are the subject of this lesson.  This script, called F<03color.pl> can
be found in the F<tutorial> directory of the Finance::Shares package.  Most of it should be familiar from
L<Finance::Shares::Lesson2>.

    #!/usr/bin/perl
    use strict;
    use warnings;
    use Getopt::Long;
    use Finance::Shares::Sample;
    use Finance::Shares::Chart;

    my $help;
    my $stock = 'MSFT';
    my $start = '2002-01-01';
    my $end   = '2002-01-31';
    my $dates = 'days';
    my $mode  = 'cache';
    my $usage = <<END;
    Usage:
	$0 [ options ]

    where options can be any (or none) of the following
	--stock=<code>		Stock code like 'BA.L'
	--dates=<dmw>		'days', 'weeks' or 'months'
	--start=<YYYY-MM-DD>    First date of sample
	  --end=<YYYY-MM-DD>    Last date of sample
	 --mode=<mode>		'cache', 'offline' or 'online'
    END

    GetOptions (
	'help'    => \$help,
	'stock=s' => \$stock,
	'dates=s' => \$dates,
	'start=s' => \$start,
	'end=s'   => \$end,
	'mode=s'  => \$mode,
    ) or $help = 1;
    print $usage and exit if $help;

    # Create MySQL object giving access to the data
    my $fss = new Finance::Shares::Sample(
	source => {
	    user     => 'test',
	    password => 'test',
	    database => 'test',
	},

	mode	     => $mode,
	symbol       => $stock,
	start_date   => $start,
	end_date     => $end,
    );

    # Create Chart object showing the data
    my $fsc = new Finance::Shares::Chart(
	sample	    => $fss,
	background  => 1,
	file	=> {
	    landscape => 1,
	},
	prices	=> {
	},
	volumes => {
	},
    );

    $fsc->output($stock);
    print "$stock quotes from $start to $end saved as $stock.ps\n";

This lesson focuses on the Finance::Shares::Chart constructor options.  You were introduced to the B<file> group
in lesson 2.  Here we have added another two groups, B<prices> and B<volumes>.  Most of the exercises involve
adding things there.

=over 4

=item 1.

Usually we want to focus on the prices, but those big black volume bars rather dominate the chart.  Add
a B<percent> key to both the B<prices> and B<volumes> option groups:

    prices {
	percent => 70,
    },

It would make sense for the volumes percentage to be 30.  Run the script and look at the chart.  Try setting them
both to 70.  What happens?

=item 2.

Lets add a little colour.  One of the top level Chart constructor options is B<background>, currently set to 1.
Decimals between 0.0 and 1.0 represent levels of grey with 0 being off and 1 as bright (white) as possible.  Any
colour can take a single decimal grey value, or an array of three decimals.  Change the background entry to read:

    background => [ 1, 1, 0.9 ],

=item 3.

The price and volume marks are controlled by a B<style> group.  These settings are passed directly to the
L<PostScript::Graph::Style> object that controls the appearance of the data.  Add this to the B<volumes> group and
see what it does.

    volumes => {
	style => {
	    color => [ 0.5, 0.8, 0.6 ],
	},
    },

Note that option names have international (US) English spellings.

=item 4.

Notice that the bars have a dark outline around them.  All marks controlled by a B<Style> have inner and outer
colours.  By default the outer edge is a contrasting colour to the background.  Try this:

    background => [ 0, 0.3, 0.3 ],

The outlines should now be pinkish, but probably a bit hard to see.  Add a B<width> setting to the volumes style
group:

     volumes => {
	style => {
	    color => [ 0.5, 0.8, 0.6 ],
            width => 8,

A bit over the top, but I hope you get the idea. 

=item 5.

Now let's bring this outline under control.  The outer edge is a contrasing colour by default, but it can be
removed (or rather set the same as the background) with the B<bgnd_outline> option:

    my $fsc = new Finance::Shares::Chart(
	sample	    => $fss,
	background  => [ 1, 1, 0.9 ],
	bgnd_outline=> 1,

Alternatively, the outer edge can be given it's own colour by setting it explicitly:

     volumes => {
	style => {
	    color => [ 0.5, 0.8, 0.6 ],
            width => 8,
	    bar	  => {
		outer_color => [ 0.8, 0, 0.4 ],
	    },
	},
    },

=item 6.

You should now be in a position to improve the appearance of the price marks.  Give them some width and colour to
begin with.

I hope you can see the usefulness of the background colour options, now.  A B<Style> can control three types of
marks.  As well as B<bar>, there are also sub-groups for B<line> and B<point>.  The B<prices> data is controlled
by the point sub-group.  See L<PostScript::Graph::Style> for the details, but another way to control the price marks
would be:

    prices => {
	style => {
	    point => {
		inner_width => 4,
		inner_color => [ 0.6, 0.9, 0 ],
		outer_width => 6,
		outer_color => [ 0, 0, 0.9 ],
	    },
	},
    },

Comparing the prices and volumes style groups, it is worth noting a few points.  B<color> and B<width> are just
convenience options.  The 'real' settings go on within the bar, line and point sub-groups.  

The 'outer width' is based on the line group which you haven't had a chance to experiment with yet.  There, the
background is drawn by putting a wider line behind a narrower one.  Naturally, for a bar (and some point shapes)
the background is an edge line - only have of which is visible.  This discrepency is really a bug and I<might> get
sorted out sometime.

=item 7.

There are a couple of options specific to the B<points> style sub-group.

B<size> is like width except it makes the whole shape larger or smaller.  Price marks are a little different in
that their size is controlled by the data, so it makes no sense to try that out here.

B<shape> is another matter.  The shapes available to price style points are B<stock2>, B<stock>, B<close2> and
B<close>.  Try them out to see the difference:

    prices => {
	style => {
	    point => {
		shape => 'close2',

Note that these shapes are B<ONLY> for B<price> points.  The shapes for other style points are documented in
L<PostScript::Graph::Style>.


=back

=cut

