Ace::G...:Glyph(3pm)

📦
version 1.92 · 8 versions
, in ubuntu stonking

✨ Ace::Graphics::Glyph(3pm) — the perl docs, but make it make sense ✨

okay bestie, so this is a page from the User Contributed Perl Documentation collection, and it's about Ace::Graphics::Glyph, the literal base class for all the Ace::Graphics::Glyph objects out there. yes, the module and the package have the same name, that's just how it is, we don't question it 💅

🦋 NAME 🦋

Ace::Graphics::Glyph — the base class for Ace::Graphics::Glyph objects. it's giving "mother of all glyphs", and honestly? iconic. 👑

🌸 SYNOPSIS 🌸

Go look at Ace::Graphics::Panel for this one, bestie. no cap, that's where the action lives.

💖 DESCRIPTION 💖

So Ace::Graphics::Glyph is the base class for every single glyph object. And what even is a glyph, you ask? Each one is a lil wrapper around an Ace::Sequence::Feature object, it knows how to render itself onto an Ace::Graphics::Panel, and it's got a whole wardrobe of configuration variables. main character energy fr fr.

Now — important reality check — if you're an end developer, you will not ordinarily work directly with Ace::Graphics::Glyph. That's not the vibe. But you might want to subclass it if you're building customized displays, and in that case, welcome, this is your page. 🫶

💜 METHODS 💜

This whole section is the class and object methods for Ace::Graphics::Glyph. Buckle up, there's a lot, and every single one matters. ✨

🎀 CONSTRUCTORS 🎀

Ace::Graphics::Glyph objects get constructed automatically by an Ace::Graphics::GlyphFactory. They are not usually created by end-developer code. Let the factory do its thing, she's got it. 💅

  • $glyph = Ace::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory) — give this a sequence feature and it creates an Ace::Graphics::Glyph object to display that feature. The -feature argument points at the Ace::Sequence::Feature object you want displayed. And -factory indicates an Ace::Graphics::GlyphFactory object, which is where the glyph fetches all of its run-time configuration info from. It's a whole support system.

A standard set of options are recognized here. Go see OPTIONS, we cover them all below, promise. 😤

🌈 OBJECT METHODS 🌈

Once a glyph exists, it responds to a lowkey huge number of methods. This section groups them into related categories so you don't lose your mind. You're welcome. 🧚

💫 Retrieving glyph context:

  • $factory = $glyph->factory — get the Ace::Graphics::GlyphFactory associated with this object. This cannot be changed once it is set. Once it's locked in, it's locked in, periodt.
  • $feature = $glyph->feature — get the sequence feature associated with this object. Also cannot be changed once it is set. No takebacks. 🙈

💫 Retrieving glyph options:

  • $fgcolor = $glyph->fgcolor
  • $bgcolor = $glyph->bgcolor
  • $fontcolor = $glyph->fontcolor
  • $fillcolor = $glyph->fillcolor

These four return the configured foreground, background, font and fill colors for the glyph, delivered in the form of a GD::Image color index. aesthetic.

  • $width = $glyph->width — returns the maximum width allowed for the glyph. Heads up though: most glyphs will be smaller than this. It's a ceiling, not a promise.
  • $font = $glyph->font — returns the font for the glyph.
  • $option = $glyph->option($option) — returns the value of the option you named.
  • $index = $glyph->color($color) — hand it a symbolic color name or a #RRGGBB-form color name, and it hands back its GD index. 🎨

💫 Retrieving information about the sequence:

  • $start = $glyph->start
  • $end = $glyph->end

These return the start and end of the glyph, measured in base pair units.

  • $offset = $glyph->offset — returns the offset of the segment, which is the base pair sitting at the far left of the image. the origin point, the moment it all begins 🦋
  • $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 return the top, left, bottom and right of the glyph in pixel coordinates.

  • $height = $glyph->height — returns the height of the glyph. Fair warning: this may be somewhat larger or smaller than the height suggested by the GlyphFactory, depending on the type of glyph. It does what it wants. 💀
  • $scale = $glyph->scale — get the scale for the glyph in pixels/bp.
  • $height = $glyph->labelheight — return the height of the label, if there is any. (if!)
  • $label = $glyph->label — return a human-readable label for the glyph. for the girlies who need to read it 👑

💫 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. scoot 🛼
  • ($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 onto the GD::Image object given by $gd, using the provided rectangle coordinates, with the appropriate foreground and fill colors and pen width. 🟪
  • $glyph->filled_oval($gd,$x1,$y1,$x2,$y2) — same as above, except it draws an oval inscribed on the rectangle. cute lil oval. 🥚

🌟 OPTIONS 🌟

These options are standard among all Glyphs. (For more options, check the individual glyph pages — everybody's got their own extras.)

  • -fgcolor — Foreground color. Default: black.
  • -outlinecolor — Synonym for -fgcolor. Default: black.
  • -bgcolor — Background color. Default: white.
  • -fillcolor — Interior color of filled images. Default: turquoise.
  • -linewidth — Width of lines drawn by glyph. Default: 1.
  • -height — Height of glyph. Default: 10.
  • -font — Glyph font. Default: gdSmallFont.
  • -label — Whether to draw a label. Default: false.

And here's the spicy bit 🔥: you may pass an anonymous subroutine to -label, in which case that subroutine will be invoked with the feature as its single argument. The subroutine must return a string to render as the label. no returning undef, bestie, it will not slay.

🧚 SUBCLASSING Ace::Graphics::Glyph 🧚

By convention, subclasses are all lower-case. Every subclass starts with a preamble exactly like this one:

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

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

Then you override the methods you actually need to. Typically, just the draw() method needs overriding. But 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(). Their whole purpose is to cache the values returned by their calculating cousins so you avoid time-consuming recalculation. Override the calculators, not the cache. trust. 🙏

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);
 }

So what's happening here, bestie? This subclass draws a simple box with two lines criss-crossed through it. Step one: we call our inherited draw() method to generate the filled box and the label. Step two: we call calculate_boundaries() to get back the coordinates of the glyph, disregarding any extra space taken by labels. Step three: we call fgcolor() to return the desired foreground color. Step four, the finale: we call $gd->line() twice to generate the criss-cross. ate. 💅

Want more complex draw() methods to study? Go look at Ace::Graphics::Glyph::transcript and Ace::Graphics::Glyph::segments.

💀 BUGS 💀

Please report them. that's it. that's the whole section. she's concise. 🙈

🌈 SEE ALSO 🌈

Go read these, bestie, they're the whole friend group:

  • 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.

and that's the page, babes 🫶 this was perl v5.42.3, dated 2026-08-19, and it's the Ace::Graphics::Glyph(3pm) page from the User Contributed Perl Documentation. mwah. 💖✨🎀

📦 where this page comes from