micycle1 / ptext

Precise text metrics & manipulation in Processing

🚧 This README (and library) is under construction 🚧

PText

PText bridges the gap between Processing's PFont and PShape classes, providing some much needed functionality when working with text in Processing.

PText extends PShape, meaning that is stores text in a vector format. With this, it offers methods to:

• Easily manipulate text dimensions
• Get a text's exact bounds (dimensions)
• Accurately get text's ascent and descent (unlike Processing's existing methods — see appendix)
• Manipulate text characteristics (such as shear and per-character rotation)
• Visualise per-character bounds, whitespace, and vertices

API

The PText API is catalogued below.

Text

• setText(text)
• setFont(fontNameString, fontSize)
• setFont(PFont)

Dimensions

• scale(both)
• scale(x, y)
• setScale(both)
• setScale(x, y)

Width

• setTextWidth(n)

• scaleWidth(n)
• getTextWidth()

Height

• setTextHeight(n)

• scaleHeight(n)
• getTextHeight()

Other Text Metrics

• getTextAscent()
• getTextDescent()
• getFontAscent()
• getFontDescent()
• getWhiteSpaceLeft()
• getWhiteSpaceRight()
• getCharWidth(character)
• getCharHeight(character)
• getCharWhitespace(character)

Text Manipulation

• setCharacterSpacing(n)

• setCharacterRotation(charIndex, angle)

  TODO image

• setShearX(maxShear)

  TODO image

Rendering

• shape(myPText, x, y)

  Use Processing's shape() method to draw the PText like a PShape (alignment will be LEFT, BASELINE).

• draw(x, y, alignX, alignY)

  Or call draw() on the PText object to specify a specific X and Y alignment (similar to textAlign()).

Debug

• debug()

Example

Resizing a PText shape using setTextWidth() and setTextHeight(), using debug() to show

import pText.PText;

PText text;

void setup() {
  
  size(1280, 720);
  smooth(4);

  text = new PText(this, "Bauhaus 93", 192);
  
  text.setText("hello");
  
  text.setFill(color(55, 255, 90));
  text.setStrokeWeight(1);

  text.setScale(1, 1);
  //shapeMode(CENTER);
  text.setTextWidth(width);
  text.setTextHeight(height);
  
    noFill(); // you must call global noFill() after any setText(), otherwise text can't be filled
}

void draw() {

  background(255);

  shape(text, mouseX, mouseY);
  //text.debug(mouseX, mouseY);
}

Appendix

Using the inbuilt functions textWidth(), textAscent(), and textDescent() are an easy way to get a good approximate result for the height and width of a string (of a given font), but they are not exact.

Why?

• textAscent() returns text height above the baseline based on the letter 'd'
• textDescent() returns text height below the baseline based on the letter 'p'.
• textWidth() includes glyph whitespace (aka padding; ideally we want to ignore this for the first and last characters)

textAscent() + textDescent() therefore measures the maximum height of a string in a given font and font size, and not the height of a specific string. In other words, if your text doesn't include both 'd' and 'p' characters, then using these methods to determine text height will overestimate the result.

TODO

• Scale whitespace (to increase/decrease spacing between letters, independent of font size)
• Display dimension labels (such as ascent & descent) in debug mode
• String ascent: return the max ascent of the string's current characters
• String descent: return the max descent of the string's current characters
• Allow multiple fonts within one PText at once?
• Support multiple lines / blocks of text