HELP VEDBARCHART                                 John Williams, Mar 1996

    vedbarchart(name, header, values)

Draws a horizontal bar chart in a Ved buffer named name. The sizes and
colours of the bars are determined by the contents of the list values.
The argument header may be used to provide text to be inserted at the
top of the file, above the graph.

Note: If a file called name is already present in Ved, it will be
      cleared before the bar chart is drawn.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Bar Specifications
  2   Changing the Layout of the Bars
  3   Changing the Font in which Labels are Printed
  4   Inserting a Header above the Chart
  5   Ensuring the Chart fits the Ved window
  6   Example


-----------------------------------------------------------------------
1  Bar Specifications
-----------------------------------------------------------------------

Each element of the argument values specifies a bar in the chart. If the
element is an integer, it simply specifies the size of the bar (i.e. its
horizontal width in Ved columns).

The element may also be a list or vector of the form {size label paint}
where size is an integer, the width of the bar; label is a string, which
is printed at the right of the bar; and paint is a character, used to
paint the bar.

The third element paint is optional. If omitted it defaults to the value
of vedbarchart_paint, whose initial value is `\{7}\s`, i.e. a blue
space.

For example, the list of values:

    [{20 'Blue'} {15 'Red' `\{3}\s`}]

describes the following two bars:

                          Blue


                     Red



-----------------------------------------------------------------------
2  Changing the Layout of the Bars
-----------------------------------------------------------------------

The thickness of bars, and the number of blank lines between them, are
controlled by the variables vedbarchart_thickness and vedbarchart_gap
respectively. Their default values are 2 and 1, i.e. bars are two lines
thick and are separated by one blank line.


-----------------------------------------------------------------------
3  Changing the Font in which Labels are Printed
-----------------------------------------------------------------------

By default, labels are printed in bold. You can change this re-defining
the variable vedbarchart_label_attr. The new value should be suitable as
a value for vedcharinsert_attr. E.g. to make labels italic, do:

    `\{i}` -> vedbarchart_label_attr;

To ensure labels are printed in the standard font, do:

    0 -> vedbarchart_label_attr;


-----------------------------------------------------------------------
4  Inserting a Header above the Chart
-----------------------------------------------------------------------

The second argument to vedbarchart, header, specifies text to be
inserted at the top of the bar chart file, above the chart itself. If
header is a string, it is inserted directly at the top of the file.
Otherwise header may be a procedure, which is simply applied with no
arguments. In this case the procedure should return some strings which
will be inserted into the buffer. Finally header may be false, in which
case nothing is inserted.

In all cases the header is followed by vedbarchart_gap blank lines.


-----------------------------------------------------------------------
5  Ensuring the Chart fits the Ved window
-----------------------------------------------------------------------

As stated above, bar sizes given in the values argument to vedbarchart
simply specify the horizontal widths of the bars in Ved columns. This
means that bars whose size is greater than *vedscreenwidth will not be
fully visible, i.e. they will extend past the right-hand edge of the Ved
window.

You can ensure that a chart fits into the Ved window by calling the
procedure vedbarchart_scale on the list of values, like this:

    vedbarchart_scale(values) -> scaled_values;

This procedure finds the largest bar size in values, and also the
greatest label size. If the sum of these is greater than the width of
the Ved window, then all the bar sizes in values are reduced by a such
an amount that the largest bar exactly fills the visible Ved window.
Note that if the largest bar does fit into the Ved window, none of the
sizes in values are adjusted, and the result scaled_values is identical
to values.

Typically a call to vedbarchart_scale would be included in a call to
vedbarchart, i.e.

    vedbarchart(name, header, vedbarchart_scale(values));


-----------------------------------------------------------------------
6  Example
-----------------------------------------------------------------------

The following example produces a chart with four bars, each of a
different colour:

    vedbarchart(
      'example',
      '\{bu}Example Bar Chart',
      [{40 'Red' `\{3}\s`} {30 'Green' `\{5}\s`}
       {20 'Blue' `\{7}\s`} {10 'Black' `\{1}\s`}
        ]);


--- C.all/help/vedbarchart
--- Copyright University of Sussex 1996. All rights reserved.
