Provided by: libace-perl_1.92-3_amd64 bug

NAME

       Ace::Graphics::Glyph - Base class for Ace::Graphics::Glyph objects

SYNOPSIS

       See Ace::Graphics::Panel.

DESCRIPTION

       Ace::Graphics::Glyph is the base class for all glyph objects.  Each glyph is a wrapper
       around an Ace::Sequence::Feature object, knows how to render itself on an
       Ace::Graphics::Panel, and has a variety of configuration variables.

       End developers will not ordinarily work directly with Ace::Graphics::Glyph, but may want
       to subclass it for customized displays.

METHODS

       This section describes the class and object methods for Ace::Graphics::Glyph.

   CONSTRUCTORS
       Ace::Graphics::Glyph objects are constructed automatically by an
       Ace::Graphics::GlyphFactory, and are not usually created by end-developer code.

       $glyph = Ace::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory)
           Given a sequence feature, creates an Ace::Graphics::Glyph object to display it.  The
           -feature argument points to the Ace::Sequence::Feature object to display.  -factory
           indicates an Ace::Graphics::GlyphFactory object from which the glyph will fetch all
           its run-time configuration information.

           A standard set of options are recognized.  See OPTIONS.

   OBJECT METHODS
       Once a glyph is created, it responds to a large number of methods.  In this section, these
       methods are grouped into related categories.

       Retrieving glyph context:

       $factory = $glyph->factory
           Get the Ace::Graphics::GlyphFactory associated with this object.  This cannot be
           changed once it is set.

       $feature = $glyph->feature
           Get the sequence feature associated with this object.  This cannot be changed once it
           is set.

       Retrieving glyph options:

       $fgcolor = $glyph->fgcolor
       $bgcolor = $glyph->bgcolor
       $fontcolor = $glyph->fontcolor
       $fillcolor = $glyph->fillcolor
           These methods return the configured foreground, background, font and fill colors for
           the glyph in the form of a GD::Image color index.

       $width = $glyph->width
           Return the maximum width allowed for the glyph.  Most glyphs will be smaller than
           this.

       $font = $glyph->font
           Return the font for the glyph.

       $option = $glyph->option($option)
           Return the value of the indicated option.

       $index = $glyph->color($color)
           Given a symbolic or #RRGGBB-form color name, returns its GD index.

       Retrieving information about the sequence:

       $start = $glyph->start
       $end   = $glyph->end
           These methods return the start and end of the glyph in base pair units.

       $offset = $glyph->offset
           Returns the offset of the segment (the base pair at the far left of the image).

       $length = $glyph->length
           Returns the length of the sequence segment.

       Retrieving formatting information:

       $top = $glyph->top
       $left = $glyph->left
       $bottom = $glyph->bottom
       $right = $glyph->right
           These methods return the top, left, bottom and right of the glyph in pixel
           coordinates.

       $height = $glyph->height
           Returns the height of the glyph.  This may be somewhat larger or smaller than the
           height suggested by the GlyphFactory, depending on the type of the glyph.

       $scale = $glyph->scale
           Get the scale for the glyph in pixels/bp.

       $height = $glyph->labelheight
           Return the height of the label, if any.

       $label = $glyph->label
           Return a human-readable label for the glyph.

       These methods are called by Ace::Graphics::Track during the layout process:

       $glyph->move($dx,$dy)
           Move the glyph in pixel coordinates by the indicated delta-x and delta-y values.

       ($x1,$y1,$x2,$y2) = $glyph->box
           Return the current position of the glyph.

       These methods are intended to be overridden in subclasses:

       $glyph->calculate_height
           Calculate the height of the glyph.

       $glyph->calculate_left
           Calculate the left side of the glyph.

       $glyph->calculate_right
           Calculate the right side of the glyph.

       $glyph->draw($gd,$left,$top)
           Optionally offset the glyph by the indicated amount and draw it onto the GD::Image
           object.

       $glyph->draw_label($gd,$left,$top)
           Draw the label for the glyph onto the provided GD::Image object, optionally offsetting
           by the amounts indicated in $left and $right.

       These methods are useful utility routines:

       $pixels = $glyph->map_pt($bases);
           Map the indicated base position, given in base pair units, into pixels, using the
           current scale and glyph position.

       $glyph->filled_box($gd,$x1,$y1,$x2,$y2)
           Draw a filled rectangle with the appropriate foreground and fill colors, and pen width
           onto the GD::Image object given by $gd, using the provided rectangle coordinates.

       $glyph->filled_oval($gd,$x1,$y1,$x2,$y2)
           As above, but draws an oval inscribed on the rectangle.

   OPTIONS
       The following options are standard among all Glyphs.  See individual glyph pages for more
       options.

         Option      Description               Default
         ------      -----------               -------

         -fgcolor    Foreground color          black

         -outlinecolor                         black
                     Synonym for -fgcolor

         -bgcolor    Background color          white

         -fillcolor  Interior color of filled  turquoise
                     images

         -linewidth  Width of lines drawn by   1
                           glyph

         -height     Height of glyph           10

         -font       Glyph font                gdSmallFont

         -label      Whether to draw a label   false

       You may pass an anonymous subroutine to -label, in which case the subroutine will be
       invoked with the feature as its single argument.  The subroutine must return a string to
       render as the label.

SUBCLASSING Ace::Graphics::Glyph

       By convention, subclasses are all lower-case.  Begin each subclass with a preamble like
       this one:

        package Ace::Graphics::Glyph::crossbox;

        use strict;
        use vars '@ISA';
        @ISA = 'Ace::Graphics::Glyph';

       Then override the methods you need to.  Typically, just the draw() method will need to be
       overridden.  However, if you need additional room in the glyph, you may override
       calculate_height(), calculate_left() and calculate_right().  Do not directly override
       height(), left() and right(), as their purpose is to cache the values returned by their
       calculating cousins in order to avoid time-consuming recalculation.

       A simple draw() method looks like this:

        sub draw {
         my $self = shift;
         $self->SUPER::draw(@_);
         my $gd = shift;

         # and draw a cross through the box
         my ($x1,$y1,$x2,$y2) = $self->calculate_boundaries(@_);
         my $fg = $self->fgcolor;
         $gd->line($x1,$y1,$x2,$y2,$fg);
         $gd->line($x1,$y2,$x2,$y1,$fg);
        }

       This subclass draws a simple box with two lines criss-crossed through it.  We first call
       our inherited draw() method to generate the filled box and label.  We then call
       calculate_boundaries() to return the coordinates of the glyph, disregarding any extra
       space taken by labels.  We call fgcolor() to return the desired foreground color, and then
       call $gd->line() twice to generate the criss-cross.

       For more complex draw() methods, see Ace::Graphics::Glyph::transcript and
       Ace::Graphics::Glyph::segments.

BUGS

       Please report them.

SEE ALSO

       Ace::Sequence, Ace::Sequence::Feature, Ace::Graphics::Panel, Ace::Graphics::Track,
       Ace::Graphics::Glyph::anchored_arrow, Ace::Graphics::Glyph::arrow,
       Ace::Graphics::Glyph::box, Ace::Graphics::Glyph::primers, Ace::Graphics::Glyph::segments,
       Ace::Graphics::Glyph::toomany, Ace::Graphics::Glyph::transcript,

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2001 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.