.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Ace::Graphics::Glyph 3pm" .TH Ace::Graphics::Glyph 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Ace::Graphics::Glyph \- Base class for Ace::Graphics::Glyph objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" See Ace::Graphics::Panel. .SH "DESCRIPTION" .IX Header "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. .PP End developers will not ordinarily work directly with Ace::Graphics::Glyph, but may want to subclass it for customized displays. .SH "METHODS" .IX Header "METHODS" This section describes the class and object methods for Ace::Graphics::Glyph. .SS "\s-1CONSTRUCTORS\s0" .IX Subsection "CONSTRUCTORS" Ace::Graphics::Glyph objects are constructed automatically by an Ace::Graphics::GlyphFactory, and are not usually created by end-developer code. .ie n .IP "$glyph = Ace::Graphics::Glyph\->new(\-feature=>$feature,\-factory=>$factory)" 4 .el .IP "\f(CW$glyph\fR = Ace::Graphics::Glyph\->new(\-feature=>$feature,\-factory=>$factory)" 4 .IX Item "$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. .Sp A standard set of options are recognized. See \s-1OPTIONS\s0. .SS "\s-1OBJECT METHODS\s0" .IX Subsection "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. .PP Retrieving glyph context: .ie n .IP "$factory = $glyph\->factory" 4 .el .IP "\f(CW$factory\fR = \f(CW$glyph\fR\->factory" 4 .IX Item "$factory = $glyph->factory" Get the Ace::Graphics::GlyphFactory associated with this object. This cannot be changed once it is set. .ie n .IP "$feature = $glyph\->feature" 4 .el .IP "\f(CW$feature\fR = \f(CW$glyph\fR\->feature" 4 .IX Item "$feature = $glyph->feature" Get the sequence feature associated with this object. This cannot be changed once it is set. .PP Retrieving glyph options: .ie n .IP "$fgcolor = $glyph\->fgcolor" 4 .el .IP "\f(CW$fgcolor\fR = \f(CW$glyph\fR\->fgcolor" 4 .IX Item "$fgcolor = $glyph->fgcolor" .PD 0 .ie n .IP "$bgcolor = $glyph\->bgcolor" 4 .el .IP "\f(CW$bgcolor\fR = \f(CW$glyph\fR\->bgcolor" 4 .IX Item "$bgcolor = $glyph->bgcolor" .ie n .IP "$fontcolor = $glyph\->fontcolor" 4 .el .IP "\f(CW$fontcolor\fR = \f(CW$glyph\fR\->fontcolor" 4 .IX Item "$fontcolor = $glyph->fontcolor" .ie n .IP "$fillcolor = $glyph\->fillcolor" 4 .el .IP "\f(CW$fillcolor\fR = \f(CW$glyph\fR\->fillcolor" 4 .IX Item "$fillcolor = $glyph->fillcolor" .PD These methods return the configured foreground, background, font and fill colors for the glyph in the form of a GD::Image color index. .ie n .IP "$width = $glyph\->width" 4 .el .IP "\f(CW$width\fR = \f(CW$glyph\fR\->width" 4 .IX Item "$width = $glyph->width" Return the maximum width allowed for the glyph. Most glyphs will be smaller than this. .ie n .IP "$font = $glyph\->font" 4 .el .IP "\f(CW$font\fR = \f(CW$glyph\fR\->font" 4 .IX Item "$font = $glyph->font" Return the font for the glyph. .ie n .IP "$option = $glyph\->option($option)" 4 .el .IP "\f(CW$option\fR = \f(CW$glyph\fR\->option($option)" 4 .IX Item "$option = $glyph->option($option)" Return the value of the indicated option. .ie n .IP "$index = $glyph\->color($color)" 4 .el .IP "\f(CW$index\fR = \f(CW$glyph\fR\->color($color)" 4 .IX Item "$index = $glyph->color($color)" Given a symbolic or #RRGGBB\-form color name, returns its \s-1GD\s0 index. .PP Retrieving information about the sequence: .ie n .IP "$start = $glyph\->start" 4 .el .IP "\f(CW$start\fR = \f(CW$glyph\fR\->start" 4 .IX Item "$start = $glyph->start" .PD 0 .ie n .IP "$end = $glyph\->end" 4 .el .IP "\f(CW$end\fR = \f(CW$glyph\fR\->end" 4 .IX Item "$end = $glyph->end" .PD These methods return the start and end of the glyph in base pair units. .ie n .IP "$offset = $glyph\->offset" 4 .el .IP "\f(CW$offset\fR = \f(CW$glyph\fR\->offset" 4 .IX Item "$offset = $glyph->offset" Returns the offset of the segment (the base pair at the far left of the image). .ie n .IP "$length = $glyph\->length" 4 .el .IP "\f(CW$length\fR = \f(CW$glyph\fR\->length" 4 .IX Item "$length = $glyph->length" Returns the length of the sequence segment. .PP Retrieving formatting information: .ie n .IP "$top = $glyph\->top" 4 .el .IP "\f(CW$top\fR = \f(CW$glyph\fR\->top" 4 .IX Item "$top = $glyph->top" .PD 0 .ie n .IP "$left = $glyph\->left" 4 .el .IP "\f(CW$left\fR = \f(CW$glyph\fR\->left" 4 .IX Item "$left = $glyph->left" .ie n .IP "$bottom = $glyph\->bottom" 4 .el .IP "\f(CW$bottom\fR = \f(CW$glyph\fR\->bottom" 4 .IX Item "$bottom = $glyph->bottom" .ie n .IP "$right = $glyph\->right" 4 .el .IP "\f(CW$right\fR = \f(CW$glyph\fR\->right" 4 .IX Item "$right = $glyph->right" .PD These methods return the top, left, bottom and right of the glyph in pixel coordinates. .ie n .IP "$height = $glyph\->height" 4 .el .IP "\f(CW$height\fR = \f(CW$glyph\fR\->height" 4 .IX Item "$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. .ie n .IP "$scale = $glyph\->scale" 4 .el .IP "\f(CW$scale\fR = \f(CW$glyph\fR\->scale" 4 .IX Item "$scale = $glyph->scale" Get the scale for the glyph in pixels/bp. .ie n .IP "$height = $glyph\->labelheight" 4 .el .IP "\f(CW$height\fR = \f(CW$glyph\fR\->labelheight" 4 .IX Item "$height = $glyph->labelheight" Return the height of the label, if any. .ie n .IP "$label = $glyph\->label" 4 .el .IP "\f(CW$label\fR = \f(CW$glyph\fR\->label" 4 .IX Item "$label = $glyph->label" Return a human-readable label for the glyph. .PP These methods are called by Ace::Graphics::Track during the layout process: .ie n .IP "$glyph\->move($dx,$dy)" 4 .el .IP "\f(CW$glyph\fR\->move($dx,$dy)" 4 .IX Item "$glyph->move($dx,$dy)" Move the glyph in pixel coordinates by the indicated delta-x and delta-y values. .ie n .IP "($x1,$y1,$x2,$y2) = $glyph\->box" 4 .el .IP "($x1,$y1,$x2,$y2) = \f(CW$glyph\fR\->box" 4 .IX Item "($x1,$y1,$x2,$y2) = $glyph->box" Return the current position of the glyph. .PP These methods are intended to be overridden in subclasses: .ie n .IP "$glyph\->calculate_height" 4 .el .IP "\f(CW$glyph\fR\->calculate_height" 4 .IX Item "$glyph->calculate_height" Calculate the height of the glyph. .ie n .IP "$glyph\->calculate_left" 4 .el .IP "\f(CW$glyph\fR\->calculate_left" 4 .IX Item "$glyph->calculate_left" Calculate the left side of the glyph. .ie n .IP "$glyph\->calculate_right" 4 .el .IP "\f(CW$glyph\fR\->calculate_right" 4 .IX Item "$glyph->calculate_right" Calculate the right side of the glyph. .ie n .IP "$glyph\->draw($gd,$left,$top)" 4 .el .IP "\f(CW$glyph\fR\->draw($gd,$left,$top)" 4 .IX Item "$glyph->draw($gd,$left,$top)" Optionally offset the glyph by the indicated amount and draw it onto the GD::Image object. .ie n .IP "$glyph\->draw_label($gd,$left,$top)" 4 .el .IP "\f(CW$glyph\fR\->draw_label($gd,$left,$top)" 4 .IX Item "$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 \f(CW$left\fR and \f(CW$right\fR. .PP These methods are useful utility routines: .ie n .IP "$pixels = $glyph\->map_pt($bases);" 4 .el .IP "\f(CW$pixels\fR = \f(CW$glyph\fR\->map_pt($bases);" 4 .IX Item "$pixels = $glyph->map_pt($bases);" Map the indicated base position, given in base pair units, into pixels, using the current scale and glyph position. .ie n .IP "$glyph\->filled_box($gd,$x1,$y1,$x2,$y2)" 4 .el .IP "\f(CW$glyph\fR\->filled_box($gd,$x1,$y1,$x2,$y2)" 4 .IX Item "$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 \f(CW$gd\fR, using the provided rectangle coordinates. .ie n .IP "$glyph\->filled_oval($gd,$x1,$y1,$x2,$y2)" 4 .el .IP "\f(CW$glyph\fR\->filled_oval($gd,$x1,$y1,$x2,$y2)" 4 .IX Item "$glyph->filled_oval($gd,$x1,$y1,$x2,$y2)" As above, but draws an oval inscribed on the rectangle. .SS "\s-1OPTIONS\s0" .IX Subsection "OPTIONS" The following options are standard among all Glyphs. See individual glyph pages for more options. .PP .Vb 2 \& 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 .Ve .PP 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. .SH "SUBCLASSING Ace::Graphics::Glyph" .IX Header "SUBCLASSING Ace::Graphics::Glyph" By convention, subclasses are all lower-case. Begin each subclass with a preamble like this one: .PP .Vb 1 \& package Ace::Graphics::Glyph::crossbox; \& \& use strict; \& use vars \*(Aq@ISA\*(Aq; \& @ISA = \*(AqAce::Graphics::Glyph\*(Aq; .Ve .PP Then override the methods you need to. Typically, just the \fBdraw()\fR method will need to be overridden. However, if you need additional room in the glyph, you may override \fBcalculate_height()\fR, \&\fBcalculate_left()\fR and \fBcalculate_right()\fR. Do not directly override \&\fBheight()\fR, \fBleft()\fR and \fBright()\fR, as their purpose is to cache the values returned by their calculating cousins in order to avoid time-consuming recalculation. .PP A simple \fBdraw()\fR method looks like this: .PP .Vb 4 \& 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); \& } .Ve .PP This subclass draws a simple box with two lines criss-crossed through it. We first call our inherited \fBdraw()\fR method to generate the filled box and label. We then call \fBcalculate_boundaries()\fR to return the coordinates of the glyph, disregarding any extra space taken by labels. We call \fBfgcolor()\fR to return the desired foreground color, and then call \f(CW$gd\fR\->\fBline()\fR twice to generate the criss-cross. .PP For more complex \fBdraw()\fR methods, see Ace::Graphics::Glyph::transcript and Ace::Graphics::Glyph::segments. .SH "BUGS" .IX Header "BUGS" Please report them. .SH "SEE ALSO" .IX Header "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, .SH "AUTHOR" .IX Header "AUTHOR" Lincoln Stein . .PP Copyright (c) 2001 Cold Spring Harbor Laboratory .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \s-1DISCLAIMER\s0.txt for disclaimers of warranty.