From d2fc4da8d20c40734f2914e0718777802c547a48 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Mon, 2 Oct 2023 19:47:37 -0500 Subject: [PATCH 1/3] Edit docs for p5.Font --- src/typography/p5.Font.js | 174 ++++++++++++++++++++++++-------------- 1 file changed, 110 insertions(+), 64 deletions(-) diff --git a/src/typography/p5.Font.js b/src/typography/p5.Font.js index 21b5c64cd7..b5ee49e73d 100644 --- a/src/typography/p5.Font.js +++ b/src/typography/p5.Font.js @@ -11,10 +11,10 @@ import p5 from '../core/main'; import * as constants from '../core/constants'; /** - * Base class for font handling + * A class to describe fonts. * @class p5.Font * @constructor - * @param {p5} [pInst] pointer to p5 instance + * @param {p5} [pInst] pointer to p5 instance. */ p5.Font = class { constructor(p){ @@ -23,51 +23,102 @@ p5.Font = class { this.cache = {}; /** - * Underlying opentype font implementation + * Underlying + * opentype.js + * font object. * @property font */ this.font = undefined; } /** - * Returns a tight bounding box for the given text string using this - * font + * Returns the bounding box for a string of text written in this font. * - * @method textBounds - * @param {String} line a line of text - * @param {Number} x x-position - * @param {Number} y y-position - * @param {Number} [fontSize] font size to use (optional) Default is 12. - * @param {Object} [options] opentype options (optional) - * opentype fonts contains alignment and baseline options. - * Default is 'LEFT' and 'alphabetic' + * The first parameter, `str`, is a string of text. The second and third + * parameters, `x` and `y`, are the text's position. By default, they set the + * coordinates of the bounding box's bottom-left corner. See + * textAlign() for more ways to align text. * - * @return {Object} a rectangle object with properties: x, y, w, h + * The fourth parameter, `fontSize`, is optional. It sets the font size used to + * determine the bounding box. By default, `font.textBounds()` will use the + * current textSize(). + * + * @method textBounds + * @param {String} str string of text. + * @param {Number} x x-coordinate of the text. + * @param {Number} y y-coordinate of the text. + * @param {Number} [fontSize] font size. Defaults to the current + * textSize(). + * @return {Object} object describing the bounding box with + * properties x, y, w, and h. * * @example *
* * let font; - * let textString = 'Lorem ipsum dolor sit amet.'; + * * function preload() { - * font = loadFont('./assets/Regular.otf'); + * font = loadFont('assets/inconsolata.otf'); * } + * * function setup() { - * background(210); + * background(200); * - * let bbox = font.textBounds(textString, 10, 30, 12); - * fill(255); - * stroke(0); + * let bbox = font.textBounds('p5*js', 35, 53); * rect(bbox.x, bbox.y, bbox.w, bbox.h); - * fill(0); - * noStroke(); * * textFont(font); - * textSize(12); - * text(textString, 10, 30); + * text('p5*js', 35, 53); + * + * describe('The text "p5*js" written in black inside a white rectangle.'); + * } + * + *
+ * + *
+ * + * let font; + * + * function preload() { + * font = loadFont('assets/inconsolata.otf'); + * } + * + * function setup() { + * background(200); + * + * textFont(font); + * textSize(15); + * textAlign(CENTER, CENTER); + * + * let bbox = font.textBounds('p5*js', 50, 50); + * rect(bbox.x, bbox.y, bbox.w, bbox.h); + * + * text('p5*js', 50, 50); * - * describe(`Words “Lorem ipsum dol” go off canvas and - * contained by white bounding box`); + * describe('The text "p5*js" written in black inside a white rectangle.'); + * } + * + *
+ * + *
+ * + * let font; + * + * function preload() { + * font = loadFont('assets/inconsolata.otf'); + * } + * + * function setup() { + * background(200); + * + * let bbox = font.textBounds('p5*js', 31, 53, 15); + * rect(bbox.x, bbox.y, bbox.w, bbox.h); + * + * textFont(font); + * textSize(15); + * text('p5*js', 31, 53); + * + * describe('The text "p5*js" written in black inside a white rectangle.'); * } * *
@@ -174,59 +225,54 @@ p5.Font = class { } /** - * Computes an array of points following the path for specified text + * Returns an array of points outlining a string of text. * - * @method textToPoints - * @param {String} txt a line of text - * @param {Number} x x-position - * @param {Number} y y-position - * @param {Number} fontSize font size to use (optional) - * @param {Object} [options] an (optional) object that can contain: + * The first parameter, `str`, is a string of text. The second and third + * parameters, `x` and `y`, are the text's position. By default, they set the + * coordinates of the bounding box's bottom-left corner. See + * textAlign() for more ways to align text. * - *
sampleFactor - the ratio of path-length to number of samples - * (default=.1); higher values yield more points and are therefore - * more precise + * The fourth parameter, `fontSize`, is optional. It sets the text's font + * size. By default, `font.textToPoints()` will use the current + * textSize(). * - *
simplifyThreshold - if set to a non-zero value, collinear points will be - * be removed from the polygon; the value represents the threshold angle to use - * when determining whether two edges are collinear + * The fifth parameter, `options`, is also optional. `font.textToPoints()` + * expects an object with the following properties: * - * @return {Array} an array of points, each with x, y, alpha (the path angle) + * `sampleFactor` is the ratio of the text's path length to the number of + * samples. It defaults to 0.1. Higher values produce more points along the + * path and are more precise. + * + * `simplifyThreshold` removes collinear points if it's set to a number other + * than 0. The value represents the threshold angle to use when determining + * whether two edges are collinear. + * + * @method textToPoints + * @param {String} str string of text. + * @param {Number} x x-coordinate of the text. + * @param {Number} y y-coordinate of the text. + * @param {Number} [fontSize] font size. Defaults to the current + * textSize(). + * @param {Object} [options] object with sampleFactor and simplifyThreshold + * properties. + * @return {Array} array of point objects, each with x, y, and alpha (path angle) properties. * @example *
* * let font; + * * function preload() { * font = loadFont('assets/inconsolata.otf'); * } * - * let points; - * let bounds; * function setup() { - * createCanvas(100, 100); - * stroke(0); - * fill(255, 104, 204); - * - * points = font.textToPoints('p5', 0, 0, 10, { - * sampleFactor: 5, - * simplifyThreshold: 0 + * background(200); + * let points = font.textToPoints('p5*js', 6, 60, 35, { sampleFactor: 0.5 }); + * points.forEach(p => { + * point(p.x, p.y); * }); - * bounds = font.textBounds(' p5 ', 0, 0, 10); - * } * - * function draw() { - * background(255); - * beginShape(); - * translate(-bounds.x * width / bounds.w, -bounds.y * height / bounds.h); - * for (let i = 0; i < points.length; i++) { - * let p = points[i]; - * vertex( - * p.x * width / bounds.w + - * sin(20 * p.y / bounds.h + millis() / 1000) * width / 30, - * p.y * height / bounds.h - * ); - * } - * endShape(CLOSE); + * describe('A set of black dots outlining the text "p5*js" on a gray background.'); * } * *
From 872594f15bd77f84360c4c3f52b05322e785e8a1 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Mon, 16 Oct 2023 16:54:52 -0500 Subject: [PATCH 2/3] Add links to p5.Font reference --- src/typography/p5.Font.js | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/typography/p5.Font.js b/src/typography/p5.Font.js index b5ee49e73d..98ee4e98a4 100644 --- a/src/typography/p5.Font.js +++ b/src/typography/p5.Font.js @@ -32,7 +32,8 @@ p5.Font = class { } /** - * Returns the bounding box for a string of text written in this font. + * Returns the bounding box for a string of text written using this + * p5.Font. * * The first parameter, `str`, is a string of text. The second and third * parameters, `x` and `y`, are the text's position. By default, they set the @@ -225,7 +226,8 @@ p5.Font = class { } /** - * Returns an array of points outlining a string of text. + * Returns an array of points outlining a string of text written using this + * p5.Font. * * The first parameter, `str`, is a string of text. The second and third * parameters, `x` and `y`, are the text's position. By default, they set the From a28ad4e2914acbffa9ade1a1d861e438dbb48cc5 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 24 Oct 2023 14:43:20 -0500 Subject: [PATCH 3/3] Add example for p5.Font --- src/typography/p5.Font.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/typography/p5.Font.js b/src/typography/p5.Font.js index 98ee4e98a4..c827964a82 100644 --- a/src/typography/p5.Font.js +++ b/src/typography/p5.Font.js @@ -15,6 +15,26 @@ import * as constants from '../core/constants'; * @class p5.Font * @constructor * @param {p5} [pInst] pointer to p5 instance. + * @example + *
+ * + * let font; + * + * function preload() { + * // Creates a p5.Font object. + * font = loadFont('assets/inconsolata.otf'); + * } + * + * function setup() { + * fill('deeppink'); + * textFont(font); + * textSize(36); + * text('p5*js', 10, 50); + * + * describe('The text "p5*js" written in pink on a white background.'); + * } + * + *
*/ p5.Font = class { constructor(p){