NAME

Text::Graphics -- A text graphics rendering toolkit

DESCRIPTION

This is a toolkit for rendering plain text via an API like that used for graphics rendering in GUI toolkits. This package might be used when you want to do sophisticated rendering of plain text, e.g., for graphing, creating of complex forms for email and fax, and so on.

SYNOPSIS

use Text::Graphics;
my $text = "A text graphics rendering toolkit.\n";
my $page = Text::Graphics::Page->new( 20, 10);
my $panel0 = Text::Graphics::BorderedPanel->new( 20, 10);
my $panel1 =
 Text::Graphics::FilledBorderedTextPanel->new($text x 3, 25, 12);
$panel0->setBackground("#");
$panel1->setBackground(" ");
$page->add($panel0);
$page->add($panel1, 5, 2);
$page->render();

+-------------------+
|###################|
|####+--------------+
|####|A text graphic|
|####|rendering tool|
|####|text graphics |
|####|toolkit. A tex|
|####|graphics rende|
|####|toolkit.      |
|####|              |
+----+--------------+

User API

Text::Graphics::Page

Class to represent a page.

new (width, height)

Construct a new page with the specified width and height.

add (Panel, x_offset, y_offset)

Add a Panel at the specified offset.

render ( [ scalar_reference ] )

Render the page. If an argument is given, it is assumed to be a SCALAR REFERENCE, and rendering will be done to such reference. e.g., if you want to render to $buf, you might do

$w->render(\ $buf);

If no argument to render() is provided, then rendering is simply done to STDOUT using print.

Text::Graphics::Panel

Class to represent a panel.

new (width, height)

Construct a new panel with the specified width and height.

add (Panel, x_offset, y_offset)

Add a Panel at the specified offset. This child panel is contained within its parent and will not extend beyond the parents boundaries.

setBackground ( background )

Set the background on the panel to the specified char.

getSize ()

Get the size of a panel. This method is a hook for layout managers. E.g., If you set up a wrapped text panel with height 0, then call getSize(), then it will return the same width but the new "desired" height. (If you are interested in how to write a layout manager on top of this code, please contact me (SF) as I have done so but have not released it.)

setSize (width, height)

Set the size of a panel. This method is a hook for layout managers.

getOffset ()

get the offset of a panel. This method is a hook for layout managers.

setOffset (x_offset, y_offset)

set the offset of a panel. This method is a hook for layout managers.

Subclassing

Most of the work you might do with this module will be by subclassing panel. The idea is you make a new panel, like LinePanel, that has a constructor setting character to draw and the start and end coordinates for the line. Then, in the LinePanels _drawSelf(gc) routine, it calls on the gc to draw a line:

 package LinePanel;
 use vars qw (@ISA);
 @ISA = qw (Panel);

 sub new {
  my $this = {};
  bless $this, shift;
  $this->{char} = shift;
  $this->{startx} = shift;
  $this->{starty} = shift;
  $this->{endx} = shift;
  $this->{endy} = shift;
  return $this;
 }

 sub _drawSelf {
  my $this = shift;
  my $gc = shift;

  $gc->drawLine($this->{char},
                $this->{startx}, $this->{starty},
		$this->{endx}, $this->{endy});

 }

There are some other subclasses included, particularly those for text handling.

Actually the drawLine() method for the GraphicsContext is not included b/c I just do not need it, though I have a mostly working version if anyone is interested (it is not complicated =).

GraphicsContext does include the following methods, however:

drawBorder(x_offset, y_offset, width, height)

Draw a border with the specified coordinates.

fillRect(char, x_offset, y_offset, width, height)

Fill the specified rectangle with the specified character. Note that filling with " " is a good way to get an "opaque" panel.

drawString(string, x_offset, y_offset)

Draw the specified string at the specified offset. If you want to control the width then you probably want to look at FilledTextPanel.

AUTHORS

Stephen Farrell <stephen@farrell.org>
Jeremy Mayes