@@ -16,57 +16,105 @@ const labelTableId = '_labelTable'; //Label Table
1616const labelTableElId = '_lte_' ; //Label Table Element
1717
1818/**
19- * Creates a screen reader accessible description for the canvas.
20- * The first parameter should be a string with a description of the canvas.
21- * The second parameter is optional. If specified, it determines how the
22- * description is displayed.
23- *
24- * <code class="language-javascript">describe(text, LABEL)</code> displays
25- * the description to all users as a <a
26- * href="https://en.wikipedia.org/wiki/Museum_label" target="_blank">
27- * tombstone or exhibit label/caption</a> in a div
28- * adjacent to the canvas. You can style it as you wish in your CSS.
29- *
30- * <code class="language-javascript">describe(text, FALLBACK)</code> makes the
31- * description accessible to screen-reader users only, in
32- * <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
33- * a sub DOM inside the canvas element</a>. If a second parameter is not
34- * specified, by default, the description will only be available to
35- * screen-reader users.
19+ * Creates a screen reader-accessible description for the canvas.
20+ *
21+ * The first parameter, `text`, is the description of the canvas.
22+ *
23+ * The second parameter, `display`, is optional. It determines how the
24+ * description is displayed. If `LABEL` is passed, as in
25+ * `describe('A description.', LABEL)`, the description will be visible in
26+ * a div element next to the canvas. If `FALLBACK` is passed, as in
27+ * `describe('A description.', FALLBACK)`, the description will only be
28+ * visible to screen readers. This is the default mode.
29+ *
30+ * Read
31+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
32+ * learn more about making sketches accessible.
3633 *
3734 * @method describe
38- * @param {String } text description of the canvas
39- * @param {Constant } [display] either LABEL or FALLBACK
35+ * @param {String } text description of the canvas.
36+ * @param {Constant } [display] either LABEL or FALLBACK.
4037 *
4138 * @example
4239 * <div>
4340 * <code>
44- * describe('pink square with red heart in the bottom right corner');
45- * background('pink');
46- * fill('red');
47- * noStroke();
48- * ellipse(67, 67, 20, 20);
49- * ellipse(83, 67, 20, 20);
50- * triangle(91, 73, 75, 95, 59, 73);
41+ * function setup() {
42+ * background('pink');
43+ *
44+ * // Draw a heart.
45+ * fill('red');
46+ * noStroke();
47+ * circle(67, 67, 20);
48+ * circle(83, 67, 20);
49+ * triangle(91, 73, 75, 95, 59, 73);
50+ *
51+ * // Add a general description of the canvas.
52+ * describe('A pink square with a red heart in the bottom-right corner.');
53+ * }
54+ * </code>
55+ * </div>
56+ *
57+ * <div>
58+ * <code>
59+ * function setup() {
60+ * background('pink');
61+ *
62+ * // Draw a heart.
63+ * fill('red');
64+ * noStroke();
65+ * circle(67, 67, 20);
66+ * circle(83, 67, 20);
67+ * triangle(91, 73, 75, 95, 59, 73);
68+ *
69+ * // Add a general description of the canvas
70+ * // and display it for debugging.
71+ * describe('A pink square with a red heart in the bottom-right corner.', LABEL);
72+ * }
5173 * </code>
5274 * </div>
5375 *
5476 * <div>
5577 * <code>
56- * let x = 0;
5778 * function draw() {
58- * if (x > 100) {
59- * x = 0;
60- * }
61- * background(220);
79+ * background(200);
80+ *
81+ * // The expression
82+ * // frameCount % 100
83+ * // causes x to increase from 0
84+ * // to 99, then restart from 0.
85+ * let x = frameCount % 100;
86+ *
87+ * // Draw the circle.
6288 * fill(0, 255, 0);
63- * ellipse(x, 50, 40, 40);
64- * x = x + 0.1;
65- * describe('green circle at x pos ' + round(x) + ' moving to the right');
89+ * circle(x, 50, 40);
90+ *
91+ * // Add a general description of the canvas.
92+ * describe(`A green circle at (${x}, 50) moves from left to right on a gray square.`);
6693 * }
6794 * </code>
6895 * </div>
6996 *
97+ * <div>
98+ * <code>
99+ * function draw() {
100+ * background(200);
101+ *
102+ * // The expression
103+ * // frameCount % 100
104+ * // causes x to increase from 0
105+ * // to 99, then restart from 0.
106+ * let x = frameCount % 100;
107+ *
108+ * // Draw the circle.
109+ * fill(0, 255, 0);
110+ * circle(x, 50, 40);
111+ *
112+ * // Add a general description of the canvas
113+ * // and display it for debugging.
114+ * describe(`A green circle at (${x}, 50) moves from left to right on a gray square.`, LABEL);
115+ * }
116+ * </code>
117+ * </div>
70118 */
71119
72120p5 . prototype . describe = function ( text , display ) {
@@ -112,45 +160,83 @@ p5.prototype.describe = function(text, display) {
112160} ;
113161
114162/**
115- * This function creates a screen-reader accessible
116- * description for elements — shapes or groups of shapes that create
117- * meaning together— in the canvas. The first paramater should
118- * be the name of the element. The second parameter should be a string
119- * with a description of the element. The third parameter is optional.
120- * If specified, it determines how the element description is displayed .
121- *
122- * <code class="language-javascript">describeElement(name, text, LABEL)</code>
123- * displays the element description to all users as a
124- * <a href="https://en.wikipedia.org/wiki/Museum_label" target="_blank">
125- * tombstone or exhibit label/caption</a> in a div
126- * adjacent to the canvas. You can style it as you wish in your CSS.
127- *
128- * <code class="language-javascript">describeElement(name, text, FALLBACK)</code>
129- * makes the element description accessible to screen-reader users
130- * only, in <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
131- * a sub DOM inside the canvas element</a>. If a second parameter is not
132- * specified, by default, the element description will only be available
133- * to screen-reader users .
163+ * Creates a screen reader- accessible description for elements in the canvas.
164+ * Elements are shapes or groups of shapes that create meaning together.
165+ *
166+ * The first parameter, `name`, is the name of the element.
167+ *
168+ * The second parameter, `text`, is the description of the element .
169+ *
170+ * The third parameter, `display`, is optional. It determines how the
171+ * description is displayed. If `LABEL` is passed, as in
172+ * `describe('A description.', LABEL)`, the description will be visible in
173+ * a div element next to the canvas. Using `LABEL` creates unhelpful
174+ * duplicates for screen readers. Only use `LABEL` during development. If
175+ * `FALLBACK` is passed, as in `describe('A description.', FALLBACK)`, the
176+ * description will only be visible to screen readers. This is the default
177+ * mode.
178+ *
179+ * Read
180+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
181+ * learn more about making sketches accessible .
134182 *
135183 * @method describeElement
136- * @param {String } name name of the element
137- * @param {String } text description of the element
138- * @param {Constant } [display] either LABEL or FALLBACK
184+ * @param {String } name name of the element.
185+ * @param {String } text description of the element.
186+ * @param {Constant } [display] either LABEL or FALLBACK.
139187 *
140188 * @example
141189 * <div>
142190 * <code>
143- * describe('Heart and yellow circle over pink background');
144- * noStroke();
145- * background('pink');
146- * describeElement('Circle', 'Yellow circle in the top left corner');
147- * fill('yellow');
148- * ellipse(25, 25, 40, 40);
149- * describeElement('Heart', 'red heart in the bottom right corner');
150- * fill('red');
151- * ellipse(66.6, 66.6, 20, 20);
152- * ellipse(83.2, 66.6, 20, 20);
153- * triangle(91.2, 72.6, 75, 95, 58.6, 72.6);
191+ * function setup() {
192+ * background('pink');
193+ *
194+ * // Describe the first element
195+ * // and draw it.
196+ * describeElement('Circle', 'A yellow circle in the top-left corner.');
197+ * noStroke();
198+ * fill('yellow');
199+ * circle(25, 25, 40);
200+ *
201+ * // Describe the second element
202+ * // and draw it.
203+ * describeElement('Heart', 'A red heart in the bottom-right corner.');
204+ * fill('red');
205+ * circle(66.6, 66.6, 20);
206+ * circle(83.2, 66.6, 20);
207+ * triangle(91.2, 72.6, 75, 95, 58.6, 72.6);
208+ *
209+ * // Add a general description of the canvas.
210+ * describe('A red heart and yellow circle over a pink background.');
211+ * }
212+ * </code>
213+ * </div>
214+ *
215+ * <div>
216+ * <code>
217+ * function setup() {
218+ * background('pink');
219+ *
220+ * // Describe the first element
221+ * // and draw it. Display the
222+ * // description for debugging.
223+ * describeElement('Circle', 'A yellow circle in the top-left corner.', LABEL);
224+ * noStroke();
225+ * fill('yellow');
226+ * circle(25, 25, 40);
227+ *
228+ * // Describe the second element
229+ * // and draw it. Display the
230+ * // description for debugging.
231+ * describeElement('Heart', 'A red heart in the bottom-right corner.', LABEL);
232+ * fill('red');
233+ * circle(66.6, 66.6, 20);
234+ * circle(83.2, 66.6, 20);
235+ * triangle(91.2, 72.6, 75, 95, 58.6, 72.6);
236+ *
237+ * // Add a general description of the canvas.
238+ * describe('A red heart and yellow circle over a pink background.');
239+ * }
154240 * </code>
155241 * </div>
156242 */
0 commit comments