NAME

Image::Base::Prima::Drawable -- draw into Prima window, image, etc

SYNOPSIS

 use Image::Base::Prima::Drawable;
 my $X = Prima->new;
 my $image = Image::Base::Prima::Drawable->new
               (-X         => $X,
                -drawable  => $xid);
 $image->line (0,0, 99,99, '#FF00FF');
 $image->rectangle (10,10, 20,15, 'white');

CLASS HIERARCHY

Image::Base::Prima::Drawable is a subclass of Image::Base,

    Image::Base
      Image::Base::Prima::Drawable

DESCRIPTION

Image::Base::Prima::Drawable extends Image::Base to draw into Prima drawables.

Colours for drawing can be names known to the X server (usually from the file /etc/X11/rgb.txt) or 2-digit #RRGGBB or 4-digit #RRRRGGGGBBBB hex.

FUNCTIONS

$image = Image::Base::Prima::Drawable->new (key=>value,...)

Create and return a new image object. The Prima connection object and drawable XID (an integer) must be given.

    $image = Image::Base::Prima::Drawable->new
                 (-X        => $x11_protocol_obj,
                  -drawable => $xid_drawable,
                  -colormap => $xid_colormap);

$colour = $image->xy ($x, $y)

$image->xy ($x, $y, $colour)

Get or set the pixel at $x,$y.

Currently colours returned by a get are either a name used previously to draw, or a 4-digit hex #RRRRGGGGBBBB. If two colour names became the same pixel value because that was a close as could be represented then it's unspecified which is returned. For hex it's 4-digits because that's the range in the X protocol.

If the drawable is a window and it doesn't have backing store then fetching a pixel from an obscured region returns an unspecified colour, usually a garbage #RRRRGGGGBBBB value.

Fetching a pixel is an X server round-trip and will be very slow if attempting to read out a big region. It's possible to read a big region or the entire drawable in one go, but how to know if there's going to be lots of xy calls, and whether to re-fetch for possibly changed window contents?

$image->add_colours ($name, $name, ...)

Allocate colours in the colormap. Colour names are the same for the drawing functions.

    $image->add_colours ('red', 'green', '#FF00FF');

The drawing functions automatically add a colour if it doesn't already exist but add_colours can initialize the colormap with particular desired colours and it does so with a single server round-trip instead of separate individual ones.

If the -colormap set is the default colormap in one of the screens then colours "black" and "white" are taken from the screen info without querying the server.

ATTRIBUTES

-drawable (XID integer)

The target drawable.

-colormap (XID integer)

The colormap in which to allocate colours when drawing. It defaults to the default colormap of the screen containing the target drawable, though getting that screen costs a server round-trip the first time the colormap is required (for drawing or for a get).

The Image::Base::Prima::Window sub-class instead uses a window's installed colormap as the default.

Setting -colormap only affects where colours are allocated. If the drawable is a window then the colormap is not installed in the window's attributes.

-width (integer, read-only)

-height (integer, read-only)

Width and height are read-only. Values are obtained from GetGeometry when required, then cached. If you already know the size then including values in the new will record them ready for later get. The plain drawing operations don't need the size though.

    $image = Image::Base::Prima::Drawable->new
                 (-X        => $x11_protocol_obj,
                  -drawable => $id,
                  -width    => 200,      # record known values to save
                  -height   => 100,      # a server query
                  -colormap => $colormap);

SEE ALSO

Image::Base, Prima::Drawable