From 830951ad2d6ceebc36801f1e8e4e18618a1c5ce0 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 3 Oct 2023 09:29:40 -0500 Subject: [PATCH 1/4] Edit docs for typography attributes --- src/typography/attributes.js | 242 +++++++++++++++-------------------- 1 file changed, 102 insertions(+), 140 deletions(-) diff --git a/src/typography/attributes.js b/src/typography/attributes.js index 2f5204b3f1..52e6134452 100644 --- a/src/typography/attributes.js +++ b/src/typography/attributes.js @@ -9,29 +9,34 @@ import p5 from '../core/main'; /** - * Sets the current alignment for drawing text. Accepts two - * arguments: horizAlign (LEFT, CENTER, or RIGHT) and - * vertAlign (TOP, BOTTOM, CENTER, or BASELINE). + * Sets the way text is aligned when text() is called. * - * The horizAlign parameter is in reference to the x value - * of the text() function, while the vertAlign parameter - * is in reference to the y value. + * By default, calling `text('hi', 10, 20)` places the bottom-left corner of + * the text's bounding box at (10, 20). * - * So if you write textAlign(LEFT), you are aligning the left - * edge of your text to the x value you give in text(). - * If you write textAlign(RIGHT, TOP), you are aligning the right edge - * of your text to the x value and the top edge of the text - * to the y value. + * The first parameter, `horizAlign`, changes the way + * text() interprets x-coordinates. By default, the + * x-coordinate sets the left edge of the bounding box. `textAlign()` accepts + * the following values for `horizAlign`: `LEFT`, `CENTER`, or `RIGHT`. + * + * The second parameter, `vertAlign`, is optional. It changes the way + * text() interprets y-coordinates. By default, the + * y-coordinate sets the bottom edge of the bounding box. `textAlign()` + * accepts the following values for `vertAlign`: `TOP`, `BOTTOM`, `CENTER`, + * or `BASELINE`. * * @method textAlign * @param {Constant} horizAlign horizontal alignment, either LEFT, - * CENTER, or RIGHT + * CENTER, or RIGHT. * @param {Constant} [vertAlign] vertical alignment, either TOP, - * BOTTOM, CENTER, or BASELINE + * BOTTOM, CENTER, or BASELINE. * @chainable * @example *
* + * strokeWeight(0.5); + * line(50, 0, 50, 100); + * * textSize(16); * textAlign(RIGHT); * text('ABCD', 50, 30); @@ -39,35 +44,32 @@ import p5 from '../core/main'; * text('EFGH', 50, 50); * textAlign(LEFT); * text('IJKL', 50, 70); - * describe(`Letters ABCD displayed at top left, EFGH at center, and - * IJKL at bottom right.`); + * + * describe('The letters ABCD displayed at top-left, EFGH at center, and IJKL at bottom-right. A vertical line divides the canvas in half.'); * *
* *
* - * textSize(16); * strokeWeight(0.5); * * line(0, 12, width, 12); * textAlign(CENTER, TOP); - * text('TOP', 0, 12, width); + * text('TOP', 50, 12); * * line(0, 37, width, 37); * textAlign(CENTER, CENTER); - * text('CENTER', 0, 37, width); + * text('CENTER', 50, 37); * * line(0, 62, width, 62); * textAlign(CENTER, BASELINE); - * text('BASELINE', 0, 62, width); + * text('BASELINE', 50, 62); * * line(0, 97, width, 97); * textAlign(CENTER, BOTTOM); - * text('BOTTOM', 0, 97, width); + * text('BOTTOM', 50, 97); * - * describe(`The names of the four vertical alignments (TOP, CENTER, BASELINE, - * and BOTTOM) rendered each showing that alignment's placement relative to a - * horizontal line.`); + * describe('The words "TOP", "CENTER", "BASELINE", and "BOTTOM" each drawn relative to a horizontal line. Their positions demonstrate different vertical alignments.'); * *
*/ @@ -81,30 +83,27 @@ p5.prototype.textAlign = function(horizAlign, vertAlign) { }; /** - * Sets/gets the spacing, in pixels, between lines of text. This setting will be - * used in all subsequent calls to the text() function. + * Sets the spacing between lines of text when + * text() is called. Spacing is measured in pixels. + * + * Calling `textLeading()` without an arugment returns the current spacing. * * @method textLeading - * @param {Number} leading the size in pixels for spacing between lines + * @param {Number} leading spacing between lines of text in units of pixels. * @chainable * * @example *
* - * let lines = 'L1\nL2\nL3'; // "\n" is a "new line" character - * textSize(12); + * // "\n" starts a new line of text. + * let lines = 'one\ntwo'; * - * textLeading(10); * text(lines, 10, 25); * - * textLeading(20); - * text(lines, 40, 25); - * * textLeading(30); * text(lines, 70, 25); * - * describe(`A set of L1, L2, and L3, displayed vertically 3 times. - * Spacing increases for each set.`); + * describe('The words "one" and "two" written on separate lines twice. The words on the left have less vertical spacing than the words on the right.'); * *
*/ @@ -118,11 +117,13 @@ p5.prototype.textLeading = function(theLeading) { }; /** - * Sets/gets the current font size. This size will be used in all subsequent - * calls to the text() function. Font size is measured in pixels. + * Sets the font size when + * text() is called. Font size is measured in pixels. + * + * Calling `textSize()` without an arugment returns the current size. * * @method textSize - * @param {Number} theSize the size of the letters in units of pixels + * @param {Number} size size of the letters in units of pixels * @chainable * * @example @@ -135,9 +136,7 @@ p5.prototype.textLeading = function(theLeading) { * textSize(16); * text('Font Size 16', 10, 90); * - * describe(`'Font Size 12' displayed small, - * 'Font Size 14' medium, and - * 'Font Size 16' large`); + * describe('The text "Font Size 12" drawn small, "Font Size 14" drawn medium, and "Font Size 16" drawn large.'); * * */ @@ -151,31 +150,33 @@ p5.prototype.textSize = function(theSize) { }; /** - * Sets/gets the style of the text for system fonts to NORMAL, ITALIC, BOLD or BOLDITALIC. - * Note: this may be is overridden by CSS styling. For non-system fonts - * (opentype, truetype, etc.) please load styled fonts instead. + * Sets the style for system fonts when + * text() is called. `textStyle()` accepts the + * following values: `NORMAL`, `ITALIC`, `BOLD` or `BOLDITALIC`. + * + * `textStyle()` may be overridden by CSS styling. This function doesn't + * affect fonts loaded with loadFont(). * * @method textStyle - * @param {Constant} theStyle styling for text, either NORMAL, + * @param {Constant} style styling for text, either NORMAL, * ITALIC, BOLD or BOLDITALIC * @chainable * @example *
* - * strokeWeight(0); * textSize(12); + * textAlign(CENTER); + * * textStyle(NORMAL); - * text('Font Style Normal', 10, 15); + * text('Normal', 50, 15); * textStyle(ITALIC); - * text('Font Style Italic', 10, 40); + * text('Italic', 50, 40); * textStyle(BOLD); - * text('Font Style Bold', 10, 65); + * text('Bold', 50, 65); * textStyle(BOLDITALIC); - * text('Font Style Bold Italic', 10, 90); - * describe(`The words “Font Style Normal” displayed normally, - * “Font Style Italic” in italic, - * “Font Style Bold” in bold, and - * “Font Style Bold Italic” in bold italics.`); + * text('Bold Italic', 50, 90); + * + * describe('The words "Normal" displayed normally, "Italic" in italic, "Bold" in bold, and "Bold Italic" in bold italics.'); * *
*/ @@ -189,41 +190,35 @@ p5.prototype.textStyle = function(theStyle) { }; /** - * Calculates and returns the width of any character or the maximum width of any paragrph. + * Returns the maximum width of a string of text drawn when + * text() is called. * * @method textWidth - * @param {String} theText the String of characters to measure - * @return {Number} the calculated width + * @param {String} str string of text to measure. + * @return {Number} width measured in units of pixels. * @example *
* * textSize(28); + * let str = 'hi'; + * let w = textWidth(str); + * text(str, 35, 55); + * line(35, 55, 35 + w, 55); * - * let aChar = 'P'; - * let cWidth = textWidth(aChar); - * text(aChar, 0, 40); - * line(cWidth, 0, cWidth, 50); - * - * let aString = 'p5.js'; - * let sWidth = textWidth(aString); - * text(aString, 0, 85); - * line(sWidth, 50, sWidth, 100); - * - * describe('Letter P and p5.js are displayed with vertical lines at end.'); + * describe('The text "hi" underlined.'); * *
* - * *
* * textSize(28); + * // "\n" starts a new line. + * let str = 'yo\nyo'; + * let w = textWidth(str); + * text(str, 10, 40); + * line(10, 40, 10 + w, 40); * - * let aChar = 'text\nWidth'; - * let cWidth = textWidth(aChar); - * text(aChar, 0, 40); - * line(cWidth, 0, cWidth, 100); - * - * describe('Text text and Width() are displayed with vertical lines at end of Width().'); + * describe('The word "yo" written twice on separate lines. The words are divided by a horizontal line.'); * *
*/ @@ -254,23 +249,19 @@ p5.prototype.textWidth = function (...args) { * Returns the ascent of the current font at its current size. The ascent * represents the distance, in pixels, of the tallest character above * the baseline. + * * @method textAscent - * @return {Number} + * @return {Number} ascent measured in units of pixels. * @example *
* - * let base = height * 0.75; - * let scalar = 0.8; // Different for each font - * - * textSize(32); // Set initial text size - * let asc = textAscent() * scalar; // Calc ascent - * line(0, base - asc, width, base - asc); - * text('dp', 0, base); // Draw text on baseline - * - * textSize(64); // Increase text size - * asc = textAscent() * scalar; // Recalc ascent - * line(40, base - asc, width, base - asc); - * text('dp', 40, base); // Draw text on baseline + * textSize(28); + * strokeWeight(0.5); + * text('Hi', 50, 50); + * let a = textAscent(); + * line(48, 50, 48, 50 - a); + * + * describe('The word "Hi" written in black on a gray background. A thin vertical line measures its ascent.'); * *
*/ @@ -283,23 +274,19 @@ p5.prototype.textAscent = function(...args) { * Returns the descent of the current font at its current size. The descent * represents the distance, in pixels, of the character with the longest * descender below the baseline. + * * @method textDescent - * @return {Number} + * @return {Number} descent measured in units of pixels. * @example *
* - * let base = height * 0.75; - * let scalar = 0.8; // Different for each font - * - * textSize(32); // Set initial text size - * let desc = textDescent() * scalar; // Calc descent - * line(0, base + desc, width, base + desc); - * text('dp', 0, base); // Draw text on baseline - * - * textSize(64); // Increase text size - * desc = textDescent() * scalar; // Recalc descent - * line(40, base + desc, width, base + desc); - * text('dp', 40, base); // Draw text on baseline + * textSize(28); + * strokeWeight(0.5); + * text('qypgj', 20, 50); + * let d = textDescent(); + * line(18, 50, 18, 50 + d); + * + * describe('The text "qypgj" written in black on a gray background. A thin vertical line measures its descent.'); * *
*/ @@ -316,17 +303,25 @@ p5.prototype._updateTextMetrics = function() { }; /** - * Specifies how lines of text are wrapped within a text box. This requires a max-width set on the text area, specified in text() as parameter `x2`. + * Sets the style for wrapping text when + * text() is called. `textWrap()` accepts the + * following values: + * + * `WORD` starts new lines of text at spaces. If a string of text doesn't + * have spaces, it may overflow the text box and the canvas. This is the + * default style. * - * WORD wrap style only breaks lines at spaces. A single string without spaces that exceeds the boundaries of the canvas or text area is not truncated, and will overflow the desired area, disappearing at the canvas edge. + * `CHAR` starts new lines as needed to stay within the text box. * - * CHAR wrap style breaks lines wherever needed to stay within the text box. + * `textWrap()` only works when the maximum width is set for a text box. For + * example, calling `text('Have a wonderful day', 0, 10, 100)` sets the + * maximum width to 100 pixels. * - * WORD is the default wrap style, and both styles will still break lines at any line breaks (`\n`) specified in the original text. The text area max-height parameter (`y2`) also still applies to wrapped text in both styles, lines of text that do not fit within the text area will not be drawn to the screen. + * Calling `textWrap()` without an argument returns the current style. * * @method textWrap - * @param {Constant} wrapStyle text wrapping style, either WORD or CHAR - * @return {String} wrapStyle + * @param {Constant} style text wrapping style, either WORD or CHAR. + * @return {String} style * @example *
* @@ -335,6 +330,7 @@ p5.prototype._updateTextMetrics = function() { * text('Have a wonderful day', 0, 10, 100); * *
+ * *
* * textSize(20); @@ -342,40 +338,6 @@ p5.prototype._updateTextMetrics = function() { * text('Have a wonderful day', 0, 10, 100); * *
- *
- * - * textSize(20); - * textWrap(CHAR); - * text('祝你有美好的一天', 0, 10, 100); - * - *
- *
- * - * const scream = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAA'; - * textSize(20); - * textWrap(WORD); - * text(scream, 0, 0, 100); - * fill(0, 0, 0, 75); - * text(scream, 0, 20, 100); - * fill(0, 0, 0, 50); - * text(scream, 0, 40, 100); - * fill(0, 0, 0, 25); - * text(scream, 0, 60, 100); - * strokeWeight(2); - * ellipseMode(CENTER); - * fill(255); - * ellipse(15, 50, 15, 15); - * fill(0); - * ellipse(11, 47, 1, 1); - * ellipse(19, 47, 1, 1); - * ellipse(15, 52, 5, 5); - * line(15, 60, 15, 70); - * line(15, 65, 5, 55); - * line(15, 65, 25, 55); - * line(15, 70, 10, 80); - * line(15, 70, 20, 80); - * - *
*/ p5.prototype.textWrap = function(wrapStyle) { if (wrapStyle !== 'WORD' && wrapStyle !== 'CHAR') { From 511ed0c26a4f9da10cf6d281d599563d46164534 Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Mon, 16 Oct 2023 18:56:48 -0500 Subject: [PATCH 2/4] Revise docs for typography attributes --- src/typography/attributes.js | 76 ++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 13 deletions(-) diff --git a/src/typography/attributes.js b/src/typography/attributes.js index 52e6134452..a7874c6e50 100644 --- a/src/typography/attributes.js +++ b/src/typography/attributes.js @@ -86,7 +86,7 @@ p5.prototype.textAlign = function(horizAlign, vertAlign) { * Sets the spacing between lines of text when * text() is called. Spacing is measured in pixels. * - * Calling `textLeading()` without an arugment returns the current spacing. + * Calling `textLeading()` without an argument returns the current spacing. * * @method textLeading * @param {Number} leading spacing between lines of text in units of pixels. @@ -255,13 +255,34 @@ p5.prototype.textWidth = function (...args) { * @example *
* - * textSize(28); - * strokeWeight(0.5); - * text('Hi', 50, 50); - * let a = textAscent(); - * line(48, 50, 48, 50 - a); + * let font; + * + * function preload() { + * font = loadFont('assets/inconsolata.otf'); + * } + * + * function setup() { + * background(200); + * + * textFont(font); + * // Different for each font. + * let scalar = 0.8; + * + * let base = 75; + * strokeWeight(0.5); * - * describe('The word "Hi" written in black on a gray background. A thin vertical line measures its ascent.'); + * textSize(24); + * let a = textAscent() * scalar; + * line(0, base - a, 25, base - a); + * text('dp', 0, base); + * + * textSize(48); + * a = textAscent() * scalar; + * line(50, base - a, 100, base - a); + * text('dp', 50, base); + * + * describe('The letters "dp" written twice in different sizes. Each version has a horizontal line above it that touches the top of the "d".'); + * } * *
*/ @@ -280,13 +301,34 @@ p5.prototype.textAscent = function(...args) { * @example *
* - * textSize(28); - * strokeWeight(0.5); - * text('qypgj', 20, 50); - * let d = textDescent(); - * line(18, 50, 18, 50 + d); + * let font; + * + * function preload() { + * font = loadFont('assets/inconsolata.otf'); + * } + * + * function setup() { + * background(200); * - * describe('The text "qypgj" written in black on a gray background. A thin vertical line measures its descent.'); + * textFont(font); + * // Different for each font. + * let scalar = 0.9; + * + * let base = 75; + * strokeWeight(0.5); + * + * textSize(24); + * let d = textDescent() * scalar; + * line(0, base + d, 25, base + d); + * text('dp', 0, base); + * + * textSize(48); + * d = textDescent() * scalar; + * line(50, base + d, 100, base + d); + * text('dp', 50, base); + * + * describe('The letters "dp" written twice in different sizes. Each version has a horizontal line underneath it that touches the bottom of the "p".'); + * } * *
*/ @@ -338,6 +380,14 @@ p5.prototype._updateTextMetrics = function() { * text('Have a wonderful day', 0, 10, 100); * * + * + *
+ * + * textSize(20); + * textWrap(CHAR); + * text('祝你有美好的一天', 0, 10, 100); + * + *
*/ p5.prototype.textWrap = function(wrapStyle) { if (wrapStyle !== 'WORD' && wrapStyle !== 'CHAR') { From c4d875ca9d83112183d541b0f5f13696bdbfc8ab Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 24 Oct 2023 21:02:04 -0500 Subject: [PATCH 3/4] Revise docs for typography attributes --- src/typography/attributes.js | 90 ++++++++++++++++++++++-------------- 1 file changed, 56 insertions(+), 34 deletions(-) diff --git a/src/typography/attributes.js b/src/typography/attributes.js index a7874c6e50..c0b3731bfa 100644 --- a/src/typography/attributes.js +++ b/src/typography/attributes.js @@ -199,26 +199,36 @@ p5.prototype.textStyle = function(theStyle) { * @example *
* - * textSize(28); - * let str = 'hi'; - * let w = textWidth(str); - * text(str, 35, 55); - * line(35, 55, 35 + w, 55); + * function setup() { + * background(200); + * + * textSize(28); + * strokeWeight(0.5); + * let s = 'yoyo'; + * let w = textWidth(s); + * text(s, 22, 55); + * line(22, 55, 22 + w, 55); * - * describe('The text "hi" underlined.'); + * describe('The word "yoyo" underlined.'); + * } * *
* *
* - * textSize(28); - * // "\n" starts a new line. - * let str = 'yo\nyo'; - * let w = textWidth(str); - * text(str, 10, 40); - * line(10, 40, 10 + w, 40); - * - * describe('The word "yo" written twice on separate lines. The words are divided by a horizontal line.'); + * function setup() { + * background(200); + * + * textSize(28); + * strokeWeight(0.5); + * // "\n" starts a new line. + * let s = 'yo\nyo'; + * let w = textWidth(s); + * text(s, 22, 55); + * line(22, 55, 22 + w, 55); + * + * describe('The word "yo" written twice on separate lines. The words are divided by a horizontal line.'); + * } * *
*/ @@ -263,25 +273,31 @@ p5.prototype.textWidth = function (...args) { * * function setup() { * background(200); - * * textFont(font); + * * // Different for each font. - * let scalar = 0.8; + * let fontScale = 0.8; * - * let base = 75; + * let baseY = 75; * strokeWeight(0.5); * + * // Draw small text. * textSize(24); - * let a = textAscent() * scalar; - * line(0, base - a, 25, base - a); - * text('dp', 0, base); + * text('dp', 0, baseY); + * // Draw baseline and ascent. + * let a = textAscent() * fontScale; + * line(0, baseY, 23, baseY); + * line(23, baseY - a, 23, baseY); * + * // Draw large text. * textSize(48); - * a = textAscent() * scalar; - * line(50, base - a, 100, base - a); - * text('dp', 50, base); + * text('dp', 45, baseY); + * // Draw baseline and ascent. + * a = textAscent() * fontScale; + * line(45, baseY, 91, baseY); + * line(91, baseY - a, 91, baseY); * - * describe('The letters "dp" written twice in different sizes. Each version has a horizontal line above it that touches the top of the "d".'); + * describe('The letters "dp" written twice in different sizes. Each version has a horizontal baseline. A vertical line extends upward from each baseline to the top of the "d".'); * } * * @@ -309,25 +325,31 @@ p5.prototype.textAscent = function(...args) { * * function setup() { * background(200); - * * textFont(font); + * * // Different for each font. - * let scalar = 0.9; + * let fontScale = 0.9; * - * let base = 75; + * let baseY = 75; * strokeWeight(0.5); * + * // Draw small text. * textSize(24); - * let d = textDescent() * scalar; - * line(0, base + d, 25, base + d); - * text('dp', 0, base); + * text('dp', 0, baseY); + * // Draw baseline and descent. + * let d = textDescent() * fontScale; + * line(0, baseY, 23, baseY); + * line(23, baseY, 23, baseY + d); * + * // Draw large text. * textSize(48); - * d = textDescent() * scalar; - * line(50, base + d, 100, base + d); - * text('dp', 50, base); + * text('dp', 45, baseY); + * // Draw baseline and descent. + * d = textDescent() * fontScale; + * line(45, baseY, 91, baseY); + * line(91, baseY, 91, baseY + d); * - * describe('The letters "dp" written twice in different sizes. Each version has a horizontal line underneath it that touches the bottom of the "p".'); + * describe('The letters "dp" written twice in different sizes. Each version has a horizontal baseline. A vertical line extends downward from each baseline to the bottom of the "p".'); * } * * From 89413fe227d5434a0646bb17786bc0e4906a835c Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 24 Oct 2023 21:15:12 -0500 Subject: [PATCH 4/4] Update examples for typography attributes --- src/typography/attributes.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/typography/attributes.js b/src/typography/attributes.js index c0b3731bfa..9cd54050c4 100644 --- a/src/typography/attributes.js +++ b/src/typography/attributes.js @@ -227,7 +227,7 @@ p5.prototype.textStyle = function(theStyle) { * text(s, 22, 55); * line(22, 55, 22 + w, 55); * - * describe('The word "yo" written twice on separate lines. The words are divided by a horizontal line.'); + * describe('The word "yo" written twice, one copy beneath the other. The words are divided by a horizontal line.'); * } * *