Debian Codegraph @

closure-library/closure/goog/a11y/aria/announcer.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15
16 /**
17 * @fileoverview Announcer that allows messages to be spoken by assistive
18 * technologies.
19 */
20
21 goog.provide('goog.a11y.aria.Announcer');
22
23 goog.require('goog.Disposable');
24 goog.require('goog.Timer');
25 goog.require('goog.a11y.aria');
26 goog.require('goog.a11y.aria.LivePriority');
27 goog.require('goog.a11y.aria.State');
28 goog.require('goog.dom');
29 goog.require('goog.dom.TagName');
30 goog.require('goog.object');
31
32
33
34 /**
35 * Class that allows messages to be spoken by assistive technologies that the
36 * user may have active.
37 *
38 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper.
39 * @constructor
40 * @extends {goog.Disposable}
41 * @final
42 */
43 goog.a11y.aria.Announcer = function(opt_domHelper) {
44 goog.a11y.aria.Announcer.base(this, 'constructor');
45
46 /**
47 * @type {goog.dom.DomHelper}
48 * @private
49 */
50 this.domHelper_ = opt_domHelper || goog.dom.getDomHelper();
51
52 /**
53 * Map of priority to live region elements to use for communicating updates.
54 * Elements are created on demand.
55 * @type {Object<goog.a11y.aria.LivePriority, !Element>}
56 * @private
57 */
58 this.liveRegions_ = {};
59 };
60 goog.inherits(goog.a11y.aria.Announcer, goog.Disposable);
61
62
63 /** @override */
64 goog.a11y.aria.Announcer.prototype.disposeInternal = function() {
65 goog.object.forEach(
66 this.liveRegions_, this.domHelper_.removeNode, this.domHelper_);
67 this.liveRegions_ = null;
68 this.domHelper_ = null;
69 goog.a11y.aria.Announcer.base(this, 'disposeInternal');
70 };
71
72
73 /**
74 * Announce a message to be read by any assistive technologies the user may
75 * have active.
76 * @param {string} message The message to announce to screen readers.
77 * @param {goog.a11y.aria.LivePriority=} opt_priority The priority of the
78 * message. Defaults to POLITE.
79 */
80 goog.a11y.aria.Announcer.prototype.say = function(message, opt_priority) {
81 var priority = opt_priority || goog.a11y.aria.LivePriority.POLITE;
82 var liveRegion = this.getLiveRegion_(priority);
83 // Resets text content to force a DOM mutation (so that the setTextContent
84 // post-timeout function will be noticed by the screen reader). This is to
85 // avoid the problem of when the same message is "said" twice, which doesn't
86 // trigger a DOM mutation.
87 goog.dom.setTextContent(liveRegion, '');
88 // Uses non-zero timer to make VoiceOver and NVDA work
89 goog.Timer.callOnce(function() {
90 goog.dom.setTextContent(liveRegion, message);
91 }, 1);
92 };
93
94
95 /**
96 * Returns an aria-live region that can be used to communicate announcements.
97 * @param {!goog.a11y.aria.LivePriority} priority The required priority.
98 * @return {!Element} A live region of the requested priority.
99 * @private
100 */
101 goog.a11y.aria.Announcer.prototype.getLiveRegion_ = function(priority) {
102 var liveRegion = this.liveRegions_[priority];
103 if (liveRegion) {
104 // Make sure the live region is not aria-hidden.
105 goog.a11y.aria.removeState(liveRegion, goog.a11y.aria.State.HIDDEN);
106 return liveRegion;
107 }
108
109 liveRegion = this.domHelper_.createElement(goog.dom.TagName.DIV);
110 // Note that IE has a habit of declaring things that aren't display:none as
111 // invisible to third-party tools like JAWs, so we can't just use height:0.
112 liveRegion.style.position = 'absolute';
113 liveRegion.style.top = '-1000px';
114 liveRegion.style.height = '1px';
115 liveRegion.style.overflow = 'hidden';
116 goog.a11y.aria.setState(liveRegion, goog.a11y.aria.State.LIVE, priority);
117 goog.a11y.aria.setState(liveRegion, goog.a11y.aria.State.ATOMIC, 'true');
118 this.domHelper_.getDocument().body.appendChild(liveRegion);
119 this.liveRegions_[priority] = liveRegion;
120 return liveRegion;
121 };