From 5a416d9a9cb4b127918f66a385e24b9e8339923a Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Tue, 17 Oct 2023 19:33:55 -0500 Subject: [PATCH] Edit docs for accessibility --- src/accessibility/describe.js | 101 +++++++++++++-------------- src/accessibility/outputs.js | 125 ++++++++++++++++------------------ 2 files changed, 105 insertions(+), 121 deletions(-) diff --git a/src/accessibility/describe.js b/src/accessibility/describe.js index 716e64994f..76b65e0030 100644 --- a/src/accessibility/describe.js +++ b/src/accessibility/describe.js @@ -16,53 +16,45 @@ const labelTableId = '_labelTable'; //Label Table const labelTableElId = '_lte_'; //Label Table Element /** - * Creates a screen reader accessible description for the canvas. - * The first parameter should be a string with a description of the canvas. - * The second parameter is optional. If specified, it determines how the - * description is displayed. + * Creates a screen reader-accessible description for the canvas. * - * describe(text, LABEL) displays - * the description to all users as a - * tombstone or exhibit label/caption in a div - * adjacent to the canvas. You can style it as you wish in your CSS. + * The first parameter, `text`, is the description of the canvas. * - * describe(text, FALLBACK) makes the - * description accessible to screen-reader users only, in - * - * a sub DOM inside the canvas element. If a second parameter is not - * specified, by default, the description will only be available to - * screen-reader users. + * The second parameter, `display`, is optional. It determines how the + * description is displayed. If `LABEL` is passed, as in + * `describe('A description.', LABEL)`, the description will be visible in + * a div element next to the canvas. If `FALLBACK` is passed, as in + * `describe('A description.', FALLBACK)`, the description will only be + * visible to screen readers. This is the default mode. * * @method describe - * @param {String} text description of the canvas - * @param {Constant} [display] either LABEL or FALLBACK + * @param {String} text description of the canvas. + * @param {Constant} [display] either LABEL or FALLBACK. * * @example *
* - * describe('pink square with red heart in the bottom right corner'); * background('pink'); * fill('red'); * noStroke(); - * ellipse(67, 67, 20, 20); - * ellipse(83, 67, 20, 20); + * circle(67, 67, 20); + * circle(83, 67, 20); * triangle(91, 73, 75, 95, 59, 73); + * + * describe('A pink square with a red heart in the bottom-right corner.'); * *
* *
* - * let x = 0; * function draw() { - * if (x > 100) { - * x = 0; - * } - * background(220); + * background(200); + * + * let x = frameCount % 100; * fill(0, 255, 0); - * ellipse(x, 50, 40, 40); - * x = x + 0.1; - * describe('green circle at x pos ' + round(x) + ' moving to the right'); + * circle(x, 50, 40); + * + * describe('A green circle moves from left to right on a gray square. It restarts on the left edge after reaching the right edge.'); * } * *
@@ -112,45 +104,44 @@ p5.prototype.describe = function(text, display) { }; /** - * This function creates a screen-reader accessible - * description for elements —shapes or groups of shapes that create - * meaning together— in the canvas. The first paramater should - * be the name of the element. The second parameter should be a string - * with a description of the element. The third parameter is optional. - * If specified, it determines how the element description is displayed. + * Creates a screen reader-accessible description for elements in the canvas. + * Elements are shapes or groups of shapes that create meaning together. * - * describeElement(name, text, LABEL) - * displays the element description to all users as a - * - * tombstone or exhibit label/caption in a div - * adjacent to the canvas. You can style it as you wish in your CSS. + * The first parameter, `name`, is the name of the element. * - * describeElement(name, text, FALLBACK) - * makes the element description accessible to screen-reader users - * only, in - * a sub DOM inside the canvas element. If a second parameter is not - * specified, by default, the element description will only be available - * to screen-reader users. + * The second parameter, `text`, is the description of the element. + * + * The third parameter, `display`, is optional. It determines how the + * description is displayed. If `LABEL` is passed, as in + * `describe('A description.', LABEL)`, the description will be visible in + * a div element next to the canvas. Using `LABEL` creates unhelpful + * duplicates for screen readers. Only use `LABEL` during development. If + * `FALLBACK` is passed, as in `describe('A description.', FALLBACK)`, the + * description will only be visible to screen readers. This is the default + * mode. * * @method describeElement - * @param {String} name name of the element - * @param {String} text description of the element - * @param {Constant} [display] either LABEL or FALLBACK + * @param {String} name name of the element. + * @param {String} text description of the element. + * @param {Constant} [display] either LABEL or FALLBACK. * * @example *
* - * describe('Heart and yellow circle over pink background'); - * noStroke(); * background('pink'); - * describeElement('Circle', 'Yellow circle in the top left corner'); + * + * noStroke(); + * describeElement('Circle', 'A yellow circle in the top-left corner.'); * fill('yellow'); - * ellipse(25, 25, 40, 40); - * describeElement('Heart', 'red heart in the bottom right corner'); + * circle(25, 25, 40); + * + * describeElement('Heart', 'A red heart in the bottom-right corner.'); * fill('red'); - * ellipse(66.6, 66.6, 20, 20); - * ellipse(83.2, 66.6, 20, 20); + * circle(66.6, 66.6, 20); + * circle(83.2, 66.6, 20); * triangle(91.2, 72.6, 75, 95, 58.6, 72.6); + * + * describe('A red heart and yellow circle over a pink background.'); * *
*/ diff --git a/src/accessibility/outputs.js b/src/accessibility/outputs.js index 0c6f78fc83..f6da381ef0 100644 --- a/src/accessibility/outputs.js +++ b/src/accessibility/outputs.js @@ -8,58 +8,54 @@ import p5 from '../core/main'; /** - * textOutput() creates a screenreader - * accessible output that describes the shapes present on the canvas. - * The general description of the canvas includes canvas size, - * canvas color, and number of elements in the canvas - * (example: 'Your output is a, 400 by 400 pixels, lavender blue - * canvas containing the following 4 shapes:'). This description - * is followed by a list of shapes where the color, position, and area - * of each shape are described (example: "orange ellipse at top left - * covering 1% of the canvas"). Each element can be selected to get - * more details. A table of elements is also provided. In this table, - * shape, color, location, coordinates and area are described - * (example: "orange ellipse location=top left area=2"). + * Creates a screen reader-accessible description for shapes on the canvas. * - * textOutput() and textOutput(FALLBACK) - * make the output available in - * a sub DOM inside the canvas element which is accessible to screen readers. - * textOutput(LABEL) creates an - * additional div with the output adjacent to the canvas, this is useful - * for non-screen reader users that might want to display the output outside - * of the canvas' sub DOM as they code. However, using LABEL will create - * unnecessary redundancy for screen reader users. We recommend using LABEL - * only as part of the development process of a sketch and removing it before - * publishing or sharing with screen reader users. + * The general description includes the canvas size, canvas color, and number + * of shapes. For example, + * `Your output is a, 100 by 100 pixels, gray canvas containing the following 2 shapes:`. + * + * A list of shapes follows the general description. The list describes the + * color, location, and area of each shape. For example, + * `a red circle at middle covering 3% of the canvas`. Each shape can be + * selected to get more details. + * + * A table of shapes is also provided. The table describes the shape, color, + * location, coordinates and area. For example, + * `red circle location = middle area = 3%`. + * + * The `display` parameter is optional. It determines how the description is + * displayed. If `LABEL` is passed, as in `textOutput(LABEL)`, the description + * will be visible in a div element next to the canvas. Using `LABEL` creates + * unhelpful duplicates for screen readers. Only use `LABEL` during + * development. If `FALLBACK` is passed, as in `textOutput(FALLBACK)`, the + * description will only be visible to screen readers. This is the default + * mode. * * @method textOutput - * @param {Constant} [display] either FALLBACK or LABEL + * @param {Constant} [display] either FALLBACK or LABEL. * * @example *
* * textOutput(); - * background(148, 196, 0); + * background(200); * fill(255, 0, 0); - * ellipse(20, 20, 20, 20); + * circle(20, 20, 20); * fill(0, 0, 255); - * rect(50, 50, 50, 50); + * square(50, 50, 50); * *
* - * *
* - * let x = 0; * function draw() { * textOutput(); - * background(148, 196, 0); + * background(200); + * let x = frameCount * 0.1; * fill(255, 0, 0); - * ellipse(x, 20, 20, 20); + * circle(x, 20, 20); * fill(0, 0, 255); - * rect(50, 50, 50, 50); - * ellipse(20, 20, 20, 20); - * x += 0.1; + * square(50, 50, 50); * } * *
@@ -86,59 +82,56 @@ p5.prototype.textOutput = function(display) { }; /** - * gridOutput() lays out the - * content of the canvas in the form of a grid (html table) based - * on the spatial location of each shape. A brief - * description of the canvas is available before the table output. - * This description includes: color of the background, size of the canvas, - * number of objects, and object types (example: "lavender blue canvas is - * 200 by 200 and contains 4 objects - 3 ellipses 1 rectangle"). The grid - * describes the content spatially, each element is placed on a cell of the - * table depending on its position. Within each cell an element the color - * and type of shape of that element are available (example: "orange ellipse"). - * These descriptions can be selected individually to get more details. - * A list of elements where shape, color, location, and area are described - * (example: "orange ellipse location=top left area=1%") is also available. + * Lays out the content of the canvas in a table element, which is a grid. + * Each shape's location in the grid corresponds to its location on the + * canvas. * - * gridOutput() and gridOutput(FALLBACK) - * make the output available in - * a sub DOM inside the canvas element which is accessible to screen readers. - * gridOutput(LABEL) creates an - * additional div with the output adjacent to the canvas, this is useful - * for non-screen reader users that might want to display the output outside - * of the canvas' sub DOM as they code. However, using LABEL will create - * unnecessary redundancy for screen reader users. We recommend using LABEL - * only as part of the development process of a sketch and removing it before - * publishing or sharing with screen reader users. + * A screen reader-accessible description appears before the grid. The + * general description includes the canvas size, canvas color, and number of + * shapes. For example, + * `gray canvas, 100 by 100 pixels, contains 2 shapes: 1 circle 1 square`. + * + * The grid cells describe the color and type of shape at that location. For + * example, `red circle`. These descriptions can be selected individually to + * get more details. + * + * A list of shapes follows the table. The list describes the color, type, + * location, and area of each shape. For example, + * `red circle, location = middle, area = 3 %`. + * + * The `display` parameter is optional. It determines how the description is + * displayed. If `LABEL` is passed, as in `gridOutput(LABEL)`, the description + * will be visible in a div element next to the canvas. Using `LABEL` creates + * unhelpful duplicates for screen readers. Only use `LABEL` during + * development. If `FALLBACK` is passed, as in `gridOutput(FALLBACK)`, the + * description will only be visible to screen readers. This is the default + * mode. * * @method gridOutput - * @param {Constant} [display] either FALLBACK or LABEL + * @param {Constant} [display] either FALLBACK or LABEL. * * @example *
* * gridOutput(); - * background(148, 196, 0); + * background(200); * fill(255, 0, 0); * ellipse(20, 20, 20, 20); * fill(0, 0, 255); - * rect(50, 50, 50, 50); + * square(50, 50, 50); * *
* - * *
* - * let x = 0; * function draw() { * gridOutput(); - * background(148, 196, 0); + * background(200); + * let x = frameCount * 0.1; * fill(255, 0, 0); - * ellipse(x, 20, 20, 20); + * circle(x, 20, 20); * fill(0, 0, 255); - * rect(50, 50, 50, 50); - * ellipse(20, 20, 20, 20); - * x += 0.1; + * square(50, 50, 50); * } * *