--- name: "Ace::Graphics::Glyph" section: "3pm" platform: "linux" package: "libace-perl" version: "1.92-12+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Ace::Graphics::Glyph" --- # Ace::Graphics::Glyph(3pm) Base class for Ace::Graphics::Glyph objects ## 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 \. 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.