NAME
Bio::Graphics::Glyph - Base class for Bio::Graphics::Glyph objects
SYNOPSIS
See Bio::Graphics::Panel.
DESCRIPTION
Bio::Graphics::Glyph is the base class for all glyph objects. Each glyph is a wrapper around an Bio:SeqFeatureI object, knows how to render itself on an Bio::Graphics::Panel, and has a variety of configuration variables.
End developers will not ordinarily work directly with Bio::Graphics::Glyph objects, but with Bio::Graphics::Glyph::generic and its subclasses. Similarly, most glyph developers will want to subclass from Bio::Graphics::Glyph::generic because the latter provides labeling and arrow-drawing facilities.
METHODS
This section describes the class and object methods for Bio::Graphics::Glyph.
CONSTRUCTORS
Bio::Graphics::Glyph objects are constructed automatically by an Bio::Graphics::Glyph::Factory, and are not usually created by end-developer code.
- $glyph = Bio::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory)
-
Given a sequence feature, creates an Bio::Graphics::Glyph object to display it. The -feature argument points to the Bio:SeqFeatureI object to display, and -factory indicates an Bio::Graphics::Glyph::Factory object from which the glyph will fetch all its run-time configuration information. Factories are created and manipulated by the Bio::Graphics::Panel object.
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 Bio::Graphics::Glyph::Factory associated with this object. This cannot be changed once it is set.
- $panel = $glyph->panel
-
Get the Bio::Graphics::Panel 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.
- $feature = $glyph->add_feature(@features)
-
Add the list of features to the glyph, creating subparts. This is most common done with the track glyph returned by Ace::Graphics::Panel->add_track().
- $feature = $glyph->add_group(@features)
-
This is similar to add_feature(), but the list of features is treated as a group and can be configured as a set.
Retrieving glyph options:
- $fgcolor = $glyph->fgcolor
- $bgcolor = $glyph->bgcolor
- $fontcolor = $glyph->fontcolor
- $fontcolor = $glyph->font2color
- $fillcolor = $glyph->fillcolor
-
These methods return the configured foreground, background, font, alternative font, and fill colors for the glyph in the form of a GD::Image color index.
- $color = $glyph->tkcolor
-
This method returns a color to be used to flood-fill the entire glyph before drawing (currently used by the "track" glyph).
- $width = $glyph->width([$newwidth])
-
Return the width of the glyph, not including left or right padding. This is ordinarily set internally based on the size of the feature and the scale of the panel.
- $width = $glyph->layout_width
-
Returns the width of the glyph including left and right padding.
- $width = $glyph->height
-
Returns the height of the glyph, not including the top or bottom padding. This is calculated from the "height" option and cannot be changed.
- $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.
- $level = $glyph->level
-
The "level" is the nesting level of the glyph. Groups are level -1, top level glyphs are level 0, subparts (e.g. exons) are level 1 and so forth.
Setting an option:
- $glyph->configure(-name=>$value)
-
You may change a glyph option after it is created using set_option(). This is most commonly used to configure track glyphs.
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 Bio::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 Synonym for -fgcolor
-bgcolor Background color turquoise
-fillcolor Synonym for -bgcolor
-linewidth Line width 1
-height Height of glyph 10
-font Glyph font gdSmallFont
-connector Connector type 0 (false)
-connector_color
Connector color black
-strand_arrow Whether to indicate 0 (false)
strandedness
-label Whether to draw a label 0 (false)
-description Whether to draw a description 0 (false)For glyphs that consist of multiple segments, the -connector option controls what's drawn between the segments. The default is 0 (no connector). Options include "hat", an upward-angling conector, "solid", a straight horizontal connector, and "dashed", for a horizontal dashed line. The -connector_color option controls the color of the connector, if any.
The label is printed above the glyph. 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. Otherwise, you may return the number "1", in which case the feature's info(), seqname() and primary_tag() methods will be called (in that order) until a suitable name is found.
The description is printed below the glyph. 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. Otherwise, you may return the number "1", in which case the feature's source_tag() method will be invoked.
In the case of ACEDB Ace::Sequence feature objects, the feature's info(), Brief_identification() and Locus() methods will be called to create a suitable description.
The -strand_arrow option, if true, requests that the glyph indicate which strand it is on, usually by drawing an arrowhead. Not all glyphs can respond appropriately to this request.
SUBCLASSING Bio::Graphics::Glyph
By convention, subclasses are all lower-case. Begin each subclass with a preamble like this one:
package Bio::Graphics::Glyph::crossbox;
use strict;
use vars '@ISA';
@ISA = 'Bio::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 Bio::Graphics::Glyph::transcript and Bio::Graphics::Glyph::segments.
BUGS
Please report them.
SEE ALSO
Bio::DB::GFF::Feature, Ace::Sequence, Bio::Graphics::Panel, Bio::Graphics::Track, Bio::Graphics::Glyph::anchored_arrow, Bio::Graphics::Glyph::arrow, Bio::Graphics::Glyph::box, Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::transcript, Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::wormbase_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.