.\" Automatically generated by Pod::Man 4.09 (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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Bio::Graphics::Glyph 3pm" .TH Bio::Graphics::Glyph 3pm "2018-09-21" "perl v5.26.2" "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" Bio::Graphics::Glyph \- Base class for Bio::Graphics::Glyph objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" See Bio::Graphics::Panel. .SH "DESCRIPTION" .IX Header "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. .PP 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. .SH "METHODS" .IX Header "METHODS" This section describes the class and object methods for Bio::Graphics::Glyph. .SS "\s-1CONSTRUCTORS\s0" .IX Subsection "CONSTRUCTORS" Bio::Graphics::Glyph objects are constructed automatically by an Bio::Graphics::Glyph::Factory, and are not usually created by end-developer code. .ie n .IP "$glyph = Bio::Graphics::Glyph\->new(\-feature=>$feature,\-factory=>$factory)" 4 .el .IP "\f(CW$glyph\fR = Bio::Graphics::Glyph\->new(\-feature=>$feature,\-factory=>$factory)" 4 .IX Item "$glyph = Bio::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory)" Given a sequence feature, creates an Bio::Graphics::Glyph object to display it. The \fB\-feature\fR argument points to the Bio:SeqFeatureI object to display, and \fB\-factory\fR 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. .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 Bio::Graphics::Glyph::Factory associated with this object. This cannot be changed once it is set. .ie n .IP "$panel = $glyph\->panel" 4 .el .IP "\f(CW$panel\fR = \f(CW$glyph\fR\->panel" 4 .IX Item "$panel = $glyph->panel" Get the Bio::Graphics::Panel 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. .ie n .IP "$feature = $glyph\->\fIparent_feature()\fR" 4 .el .IP "\f(CW$feature\fR = \f(CW$glyph\fR\->\fIparent_feature()\fR" 4 .IX Item "$feature = $glyph->parent_feature()" Within callbacks only, the \fIparent_feature()\fR method returns the parent of the current feature, if there is one. Called with a numeric argument, ascends the parentage tree: \fIparent_feature\fR\|(1) will return the parent, \fIparent_feature\fR\|(2) will return the grandparent, etc. If there is no parent, returns undef. .ie n .IP "$feature = $glyph\->add_feature(@features)" 4 .el .IP "\f(CW$feature\fR = \f(CW$glyph\fR\->add_feature(@features)" 4 .IX Item "$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 Bio::Graphics::Panel\->\fIadd_track()\fR. .Sp If the Bio::Graphics::Panel was initialized with \fB\-feature_limit\fR set to a non-zero value, then calls to a track glyph's \fIadd_feature()\fR method will maintain a count of features added to the track. Once the feature count exceeds the value set in \-feature_limit, additional features will displace existing ones in a way that effects a uniform sampling of the total feature set. This is useful to protect against excessively large tracks. The total number of features added can be retrieved by calling the glyph's \fIfeature_count()\fR method. .ie n .IP "$feature = $glyph\->add_group(@features)" 4 .el .IP "\f(CW$feature\fR = \f(CW$glyph\fR\->add_group(@features)" 4 .IX Item "$feature = $glyph->add_group(@features)" This is similar to \fIadd_feature()\fR, but the list of features is treated as a group and can be configured as a set. .ie n .IP "$glyph\->finished" 4 .el .IP "\f(CW$glyph\fR\->finished" 4 .IX Item "$glyph->finished" When you are finished with a glyph, you can call its \fIfinished()\fR method in order to break cycles that would otherwise cause memory leaks. \&\fIfinished()\fR is typically only used by the Panel object. .ie n .IP "$subglyph = $glyph\->make_subglyph($level,@sub_features)" 4 .el .IP "\f(CW$subglyph\fR = \f(CW$glyph\fR\->make_subglyph($level,@sub_features)" 4 .IX Item "$subglyph = $glyph->make_subglyph($level,@sub_features)" This method is called to create subglyphs from a list of subfeatures. The \f(CW$level\fR indicates the current level of the glyph (top-level glyphs are level 0, subglyphs are level 1, etc). .Sp Ordinarily this method simply calls \&\f(CW$self\fR\->factory\->make_subglyph($level,@sub_features). Override it in subclasses to create subglyphs of a particular type. For example: .Sp .Vb 6 \& sub make_subglyph { \& my $self = shift; \& my $level = shift; \& my $factory = $self\->factory; \& $factory\->make_glyph($factory,\*(Aqarrow\*(Aq,@_); \& } .Ve .ie n .IP "$count = $glyph\->\fIfeature_count()\fR" 4 .el .IP "\f(CW$count\fR = \f(CW$glyph\fR\->\fIfeature_count()\fR" 4 .IX Item "$count = $glyph->feature_count()" Return the number of features added to this glyph via \fIadd_feature()\fR. .ie n .IP "$flag = $glyph\->\fIfeatures_clipped()\fR" 4 .el .IP "\f(CW$flag\fR = \f(CW$glyph\fR\->\fIfeatures_clipped()\fR" 4 .IX Item "$flag = $glyph->features_clipped()" If the panel was initialized with \-feature_limit set to a non-zero value, then calls to \fIadd_features()\fR will limit the number of glyphs to the indicated value. If this value was exceeded, then \&\fIfeatures_clipped()\fR will return true. .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 "$fontcolor = $glyph\->font2color" 4 .el .IP "\f(CW$fontcolor\fR = \f(CW$glyph\fR\->font2color" 4 .IX Item "$fontcolor = $glyph->font2color" .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, alternative font, and fill colors for the glyph in the form of a GD::Image color index. .ie n .IP "$color = $glyph\->tkcolor" 4 .el .IP "\f(CW$color\fR = \f(CW$glyph\fR\->tkcolor" 4 .IX Item "$color = $glyph->tkcolor" This method returns a color to be used to flood-fill the entire glyph before drawing (currently used by the \*(L"track\*(R" glyph). .ie n .IP "($left,$top,$right,$bottom) = $glyph\->bounds($dx,$dy)" 4 .el .IP "($left,$top,$right,$bottom) = \f(CW$glyph\fR\->bounds($dx,$dy)" 4 .IX Item "($left,$top,$right,$bottom) = $glyph->bounds($dx,$dy)" Given the topleft coordinates of the glyph, return the bounding box of its contents, exclusive of padding. This is typically called by the \&\fIdraw()\fR and \fIdraw_component()\fR methods to recover the position of the glyph. .ie n .IP "($left,$top,$right,$bottom) = $glyph\->calculate_boundaries($dx,$dy)" 4 .el .IP "($left,$top,$right,$bottom) = \f(CW$glyph\fR\->calculate_boundaries($dx,$dy)" 4 .IX Item "($left,$top,$right,$bottom) = $glyph->calculate_boundaries($dx,$dy)" An alias for \fIbounds()\fR, used by some glyphs for compatibility with older versions of this module. .ie n .IP "$width = $glyph\->width([$newwidth])" 4 .el .IP "\f(CW$width\fR = \f(CW$glyph\fR\->width([$newwidth])" 4 .IX Item "$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. .ie n .IP "$width = $glyph\->layout_width" 4 .el .IP "\f(CW$width\fR = \f(CW$glyph\fR\->layout_width" 4 .IX Item "$width = $glyph->layout_width" Returns the width of the glyph including left and right padding. .ie n .IP "$width = $glyph\->height" 4 .el .IP "\f(CW$width\fR = \f(CW$glyph\fR\->height" 4 .IX Item "$width = $glyph->height" Returns the height of the glyph, not including the top or bottom padding. This is calculated from the \*(L"height\*(R" option and cannot be changed. .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($option_name)" 4 .el .IP "\f(CW$index\fR = \f(CW$glyph\fR\->color($option_name)" 4 .IX Item "$index = $glyph->color($option_name)" Given an option name that corresponds to a color (e.g. 'fgcolor') look up the option and translate it into a \s-1GD\s0 color index. .ie n .IP "$index = $glyph\->translate_color($color)" 4 .el .IP "\f(CW$index\fR = \f(CW$glyph\fR\->translate_color($color)" 4 .IX Item "$index = $glyph->translate_color($color)" Given a symbolic or #RRGGBB\-form color name, returns its \s-1GD\s0 index. .ie n .IP "$level = $glyph\->level" 4 .el .IP "\f(CW$level\fR = \f(CW$glyph\fR\->level" 4 .IX Item "$level = $glyph->level" The \*(L"level\*(R" 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. .ie n .IP "@parts = $glyph\->parts" 4 .el .IP "\f(CW@parts\fR = \f(CW$glyph\fR\->parts" 4 .IX Item "@parts = $glyph->parts" For glyphs that can contain subparts (e.g. the segments glyph), this method will return the list of subglyphs it contains. Subglyphs are created automatically by the \fInew()\fR method and are created subject to the maximum recursion depth specified by the \fImaxdepth()\fR method and/or the \-maxdepth option. .PP Setting an option: .ie n .IP "$glyph\->configure(\-name=>$value)" 4 .el .IP "\f(CW$glyph\fR\->configure(\-name=>$value)" 4 .IX Item "$glyph->configure(-name=>$value)" You may change a glyph option after it is created using \fIset_option()\fR. This is most commonly used to configure track glyphs. .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 Bio::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. .ie n .IP "$glyph\->\fImaxdepth()\fR" 4 .el .IP "\f(CW$glyph\fR\->\fImaxdepth()\fR" 4 .IX Item "$glyph->maxdepth()" This returns the maximum number of levels of feature subparts that the glyph will recurse through. For example, returning 0 indicates that the glyph will only draw the top-level feature. Returning 1 indicates that it will only draw the top-level feature and one level of subfeatures. Returning 2 will descend down two levels. Overriding this method will speed up rendering by avoiding creating of a bunch of subglyphs that will never be drawn. .Sp The default behavior is to return undef (unlimited levels of descent) unless the \-maxdepth option is passed, in which case this number is returned. .Sp Note that Bio::Graphics::Glyph::generic overrides \fImaxdepth()\fR to return 0, meaning no descent into subparts will be performed. .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 list of base position, given in base pair units, into pixels, using the current scale and glyph position. This method will accept a single base position or an array. .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. .ie n .IP "$glyph\->exceeds_depth" 4 .el .IP "\f(CW$glyph\fR\->exceeds_depth" 4 .IX Item "$glyph->exceeds_depth" Returns true if descending into another level of subfeatures will exceed the value returned by \fImaxdepth()\fR. .SS "\s-1OPTIONS\s0" .IX Subsection "OPTIONS" The following options are standard among all Glyphs. See individual glyph pages for more options. .PP Also try out the glyph_help.pl script, which attempts to document each glyph's shared and specific options and provides an interface for graphically inspecting the effect of different options. .PP .Vb 2 \& Option Description Default \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \& \& \-fgcolor Foreground color black \& \& \-bgcolor Background color turquoise \& \& \-fillcolor Synonym for \-bgcolor \& \& \-linewidth Line width 1 \& \& \-height Height of glyph 10 \& \& \-font Glyph font gdSmallFont \& \& \-connector Connector type undef (false) \& \& \-connector_color \& Connector color black \& \& \-strand_arrow Whether to indicate undef (false) \& strandedness \& \& \-stranded Whether to indicate undef (false) \& strandedness \& (same as above)) \& \& \-label Whether to draw a label undef (false) \& \& \-description Whether to draw a description undef (false) \& \& \-no_subparts Set to true to prevent undef (false) \& drawing of the subparts \& of a feature. \& \& \-ignore_sub_part Give the types/methods of undef \& subparts to ignore (as a \& space delimited list). \& \& \-maxdepth Specifies the maximum number undef (unlimited) \& child\-generations to decend \& when getting subfeatures \& \& \-sort_order Specify layout sort order "default" \& \& \-always_sort Sort even when bumping is off undef (false) \& \& \-bump_limit Maximum number of levels to bump undef (unlimited) \& \& \-hilite Highlight color undef (no color) \& \& \-link, \-title, \-target \& These options are used when creating imagemaps \& for display on the web. See L. .Ve .PP For glyphs that consist of multiple segments, the \fB\-connector\fR option controls what's drawn between the segments. The default is undef (no connector). Options include: .PP .Vb 8 \& "hat" an upward\-angling conector \& "solid" a straight horizontal connector \& "quill" a decorated line with small arrows indicating strandedness \& (like the UCSC Genome Browser uses) \& "dashed" a horizontal dashed line. \& "crossed" a straight horizontal connector with an "X" on it \& (Can be used when segments are not yet validated \& by some internal experiments...) .Ve .PP The \fB\-connector_color\fR option controls the color of the connector, if any. .PP The label is printed above the glyph. You may pass an anonymous subroutine to \fB\-label\fR, in which case the subroutine will be invoked with the feature as its single argument and is expected to return the string to use as the label. If you provide the numeric value \*(L"1\*(R" to \&\fB\-label\fR, the label will be read off the feature's \fIseqname()\fR, \fIinfo()\fR and \fIprimary_tag()\fR methods will be called until a suitable name is found. To create a label with the text \*(L"1\*(R", pass the string \*(L"1 \*(R". (A 1 followed by a space). .PP The description is printed below the glyph. You may pass an anonymous subroutine to \fB\-description\fR, in which case the subroutine will be invoked with the feature as its single argument and is expected to return the string to use as the description. If you provide the numeric value \*(L"1\*(R" to \fB\-description\fR, the description will be read off the feature's \fIsource_tag()\fR method. To create a description with the text \*(L"1\*(R", pass the string \*(L"1 \*(R". (A 1 followed by a space). .PP In the case of \s-1ACEDB\s0 Ace::Sequence feature objects, the feature's \&\fIinfo()\fR, \fIBrief_identification()\fR and \fILocus()\fR methods will be called to create a suitable description. .PP The \fB\-strand_arrow\fR option, if true, requests that the glyph indicate which strand it is on, usually by drawing an arrowhead. Not all glyphs will respond to this request. For historical reasons, \&\fB\-stranded\fR is a synonym for this option. Multisegmented features will draw an arrowhead on each component unless you specify a value of \&\*(L"ends\*(R" to \-strand_arrow, in which case only the rightmost component (for + strand features) or the leftmost component (for \- strand features) will have arrowheads. .PP \&\fBsort_order\fR: By default, features are drawn with a layout based only on the position of the feature, assuring a maximal \*(L"packing\*(R" of the glyphs when bumped. In some cases, however, it makes sense to display the glyphs sorted by score or some other comparison, e.g. such that more \&\*(L"important\*(R" features are nearer the top of the display, stacked above less important features. The \-sort_order option allows a few different built-in values for changing the default sort order (which is by \*(L"left\*(R" position): \*(L"low_score\*(R" (or \*(L"high_score\*(R") will cause features to be sorted from lowest to highest score (or vice versa). \&\*(L"left\*(R" (or \*(L"default\*(R") and \*(L"right\*(R" values will cause features to be sorted by their position in the sequence. \*(L"longest\*(R" (or \*(L"shortest\*(R") will cause the longest (or shortest) features to be sorted first, and \&\*(L"strand\*(R" will cause the features to be sorted by strand: \*(L"+1\*(R" (forward) then \*(L"0\*(R" (unknown, or \s-1NA\s0) then \*(L"\-1\*(R" (reverse). Finally, \&\*(L"name\*(R" will sort by the display_name of the features. .PP In all cases, the \*(L"left\*(R" position will be used to break any ties. To break ties using another field, options may be strung together using a \&\*(L"|\*(R" character; e.g. \*(L"strand|low_score|right\*(R" would cause the features to be sorted first by strand, then score (lowest to highest), then by \&\*(L"right\*(R" position in the sequence. .PP Finally, a subroutine coderef with a $$ prototype can be provided. It will receive two \fBglyph\fR as arguments and should return \-1, 0 or 1 (see Perl's \fIsort()\fR function for more information). For example, to sort a set of database search hits by bits (stored in the features' \&\*(L"score\*(R" fields), scaled by the log of the alignment length (with \&\*(L"start\*(R" position breaking any ties): .PP .Vb 10 \& sort_order = sub ($$) { \& my ($glyph1,$glyph2) = @_; \& my $a = $glyph1\->feature; \& my $b = $glyph2\->feature; \& ( $b\->score/log($b\->length) \& <=> \& $a\->score/log($a\->length) ) \& || \& ( $a\->start <=> $b\->start ) \& } .Ve .PP It is important to remember to use the $$ prototype as shown in the example. Otherwise Bio::Graphics will quit with an exception. The arguments are subclasses of Bio::Graphics::Glyph, not the features themselves. While glyphs implement some, but not all, of the feature methods, to be safe call the two glyphs' \fIfeature()\fR methods in order to convert them into the actual features. .PP The '\-always_sort' option, if true, will sort features even if bumping is turned off. This is useful if you would like overlapping features to stack in a particular order. Features towards the end of the list will overlay those towards the beginning of the sort order. .PP The \fB\-hilite\fR option draws a colored box behind each feature using the indicated color. Typically you will pass it a code ref that returns a color name. For example: .PP .Vb 2 \& \-hilite => sub { my $name = shift\->display_name; \& return \*(Aqyellow\*(Aq if $name =~ /XYZ/ } .Ve .PP The \fB\-no_subparts\fR option will prevent the glyph from searching its feature for subfeatures. This may enhance performance if you know in advance that none of your features contain subfeatures. .SH "SUBCLASSING Bio::Graphics::Glyph" .IX Header "SUBCLASSING Bio::Graphics::Glyph" By convention, subclasses are all lower-case. Begin each subclass with a preamble like this one: .PP .Vb 1 \& package Bio::Graphics::Glyph::crossbox; \& \& use strict; \& use base qw(Bio::Graphics::Glyph); .Ve .PP Then override the methods you need to. Typically, just the \fIdraw()\fR method will need to be overridden. However, if you need additional room in the glyph, you may override \fIcalculate_height()\fR, \&\fIcalculate_left()\fR and \fIcalculate_right()\fR. Do not directly override \&\fIheight()\fR, \fIleft()\fR and \fIright()\fR, as their purpose is to cache the values returned by their calculating cousins in order to avoid time-consuming recalculation. .PP A simple \fIdraw()\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 \fIdraw()\fR method to generate the filled box and label. We then call \fIcalculate_boundaries()\fR to return the coordinates of the glyph, disregarding any extra space taken by labels. We call \fIfgcolor()\fR to return the desired foreground color, and then call \f(CW$gd\fR\->\fIline()\fR twice to generate the criss-cross. .PP For more complex \fIdraw()\fR methods, see Bio::Graphics::Glyph::transcript and Bio::Graphics::Glyph::segments. .PP Please avoid using a specific image class (via \*(L"use \s-1GD\*(R"\s0 for example) within your glyph package. Instead, rely on the image package passed to the \fIdraw()\fR method. This approach allows for future expansion of supported image classes without requiring glyph redesign. If you need access to the specific image classes such as Polygon, Image, or Font, generate them like such: .PP .Vb 3 \& sub draw { \& my $self = shift; \& my $image_class = shift; \& \& my $polygon_package = $self\->polygon_package\->new() \& ... \& } .Ve .SH "BUGS" .IX Header "BUGS" Please report them. .SH "SEE ALSO" .IX Header "SEE ALSO" Bio::DB::GFF::Feature, Ace::Sequence, Bio::Graphics::Panel, Bio::Graphics::Track, Bio::Graphics::Glyph::Factory, Bio::Graphics::Glyph::alignment, Bio::Graphics::Glyph::anchored_arrow, Bio::Graphics::Glyph::arrow, Bio::Graphics::Glyph::box, Bio::Graphics::Glyph::broken_line, Bio::Graphics::Glyph::cds, Bio::Graphics::Glyph::christmas_arrow, Bio::Graphics::Glyph::crossbox, Bio::Graphics::Glyph::dashed_line, Bio::Graphics::Glyph::diamond, Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::dot, Bio::Graphics::Glyph::dumbbell, Bio::Graphics::Glyph::ellipse, Bio::Graphics::Glyph::ex, Bio::Graphics::Glyph::extending_arrow, Bio::Graphics::Glyph::flag, Bio::Graphics::Glyph::gene, Bio::Graphics::Glyph::generic, Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::group, Bio::Graphics::Glyph::heterogeneous_segments, Bio::Graphics::Glyph::image, Bio::Graphics::Glyph::lightning, Bio::Graphics::Glyph::line, Bio::Graphics::Glyph::merge_parts, Bio::Graphics::Glyph::merged_alignment, Bio::Graphics::Glyph::minmax, Bio::Graphics::Glyph::oval, Bio::Graphics::Glyph::pentagram, Bio::Graphics::Glyph::pinsertion, Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::processed_transcript, Bio::Graphics::Glyph::protein, Bio::Graphics::Glyph::ragged_ends, Bio::Graphics::Glyph::redgreen_box, Bio::Graphics::Glyph::redgreen_segment, Bio::Graphics::Glyph::repeating_shape, Bio::Graphics::Glyph::rndrect, Bio::Graphics::Glyph::ruler_arrow, Bio::Graphics::Glyph::saw_teeth, Bio::Graphics::Glyph::segmented_keyglyph, Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::so_transcript, Bio::Graphics::Glyph::span, Bio::Graphics::Glyph::splice_site, Bio::Graphics::Glyph::stackedplot, Bio::Graphics::Glyph::ternary_plot, Bio::Graphics::Glyph::text_in_box, Bio::Graphics::Glyph::three_letters, Bio::Graphics::Glyph::tic_tac_toe, Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::track, Bio::Graphics::Glyph::transcript, Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::translation, Bio::Graphics::Glyph::triangle, Bio::Graphics::Glyph::two_bolts, Bio::Graphics::Glyph::wave, Bio::Graphics::Glyph::weighted_arrow, Bio::Graphics::Glyph::whiskerplot, Bio::Graphics::Glyph::xyplot .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.