Text::Align(3)

okay so this is the Text::Align(3) page from the User Contributed Perl Documentation, and the actual module it's hyping up is GD::Text::Align — yes bestie, two names, one whole vibe 💅✨

🌸 NAME 🌸

GD::Text::Align — Draw aligned strings

✨ SYNOPSIS ✨

Here's the starter pack, copied exactly:

  use GD;
  use GD::Text::Align;

  my $gd = GD::Image->new(800,600);
  # allocate colours, do other things.

  my $align = GD::Text::Align->new($gd
    valign => 'top',
    halign => 'right',
  );
  $align->set_font('arial', 12);
  $align->set_text('some string');
  @bb = $align->bounding_box(200, 400, PI/3);
  # you can do things based on the bounding box here
  $align->draw(200, 400, PI/3);

🦋 DESCRIPTION 🦋

GD::Text::Align gives you an object that draws a string aligned to a coordinate, at an angle. That's the whole serve.

For builtin fonts, only two angles are valid: 0 and PI/2. Any other angle gets converted to one of those two. no cap, those are the only valid builtin-font angles.

💖 METHODS 💖

Quick heads-up: this class inherits everything from GD::Text. Down here I'm only covering the methods and attributes that aren't already covered there, or that have a different interface or behaviour. The directly inherited ones include set_text and set_font.

🎀 GD::Text::Align->new($gd_object, attrib => value, ...) 🎀

Creates a new object. The first argument to new has to be a valid GD::Image object. The other arguments get passed on to the set method.

🎀 $align->set(attrib => value, ...) 🎀

Sets an attribute. Valid attributes are the ones discussed in GD::Text, plus:

• valign, halign — vertical and horizontal alignment of the string. See also set_valign and set_halign.
• colour, color — synonyms. This is the colour used to draw the string. It should be the index of the colour in the GD::Image object's palette. The default value is the last colour in the GD object's palette at the time of the creation of $align.

🎀 $align->get(attribute) 🎀

Gets the value of an attribute. Valid attributes are all the attributes mentioned in GD::Text, the attributes mentioned under the set method, and:

• x, y and angle — the x and y coordinate and the angle to be used. You can only do this after a call to the draw or bounding_box methods. Note that these coordinates are not necessarily the same ones that were passed in. Instead, they are the coordinates from where the GD methods will start drawing. I doubt that this is very useful to anyone.

Note: while you can set the colour with both 'color' and 'colour', you can only get it as 'colour'. Sorry, but such is life in Australia. 🇦🇺💀

🎀 $align->set_valign(value) 🎀

Sets the vertical alignment of the string to one of 'top', 'center', 'base' or 'bottom'. For builtin fonts, the last two are the same. The value 'base' denotes the baseline of a TrueType font.

Returns true on success, false on failure.

🎀 $align->set_halign(value) 🎀

Sets the horizontal alignment of the string to one of 'left', 'center', or 'right'.

Returns true on success, false on failure.

🎀 $align->set_align(valign, halign) 🎀

Sets the vertical and horizontal alignment. It's just here for convenience. See also set_valign and set_halign.

Returns true on success, false on failure.

🎀 $align->draw(x, y, angle) 🎀

Draws the string at coordinates x, y, at an angle angle in radians. The x and y coordinate become the pivot around which the string rotates.

Note that for the builtin GD fonts, the only two valid angles are 0 and PI/2.

Returns the bounding box of the drawn string (see bounding_box()).

🎀 $align->bounding_box(x, y, angle) 🎀

Returns the bounding box of the string to draw. This returns an eight-element list (exactly like the GD::Image->stringTTF method):

  (x1,y1) lower left corner
  (x2,y2) lower right corner
  (x3,y3) upper right corner
  (x4,y4) upper left corner

Note that upper, lower, left and right are relative to the string, not to the canvas.

The bounding box can be used to make decisions about whether to move the string or change the font size before you actually draw the string.

🌈 NOTES 🌈

Stay on the interface, bestie: as with all Modules for Perl, please stick to using the interface. If you try to fiddle too much with knowledge of the internals of this module, you may get burned. Those internals may change at any time. 😭

TrueType fonts only work with a version of GD > 1.20, and even then only if that GD was compiled with support for this. If you attempt to do it anyway, you will get errors. fr fr, the errors are not a vibe.

And for the following, terms like 'top', 'upper', 'left' and the like are all relative to the string to be drawn, not to the canvas.

🐛 BUGS 🐛

Any bugs inherited from GD::Text. sharing is caring, apparently.

👑 COPYRIGHT 👑

copyright 1999 Martien Verbruggen (mgjv@comdyn.com.au)

🫶 SEE ALSO 🫶

• GD
• GD::Text
• GD::Text::Wrap

---

that's the whole page, bestie — it's from perl v5.42.0, dated 2018-03-13, and yep, the footer says Text::Align(3) too. mwah 💖🎀🦋