| // Copyright 2014 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| /** |
| * @fileoverview The ChromeVox User Event Detail object. |
| * |
| * This is the detail object for a CustomEvent that ChromeVox sends to the |
| * current node in the DOM when the user wants to perform a ChromeVox action |
| * that could potentially be handled better by the underlying web app. |
| * |
| * ChromeVox events are sent with status "PENDING" and an action that maps to |
| * the command list in ChromeVoxUserCommands. |
| * |
| * If a web app wishes to handle the action, it can perform the action then set |
| * the status of the event to either "SUCCESS" or "FAILURE". |
| * |
| * When the event bubbles back up to the document, ChromeVox will process it. |
| * If the status is "PENDING", ChromeVox will perform the action itself. |
| * If the status is "FAILURE", ChromeVox will speak the associated error message |
| * for that action. (For example: "No next heading.") |
| * If the status is "SUCCESS", then ChromeVox will check to see if an associated |
| * resultNode is added to the event. If this node exists, then ChromeVox will |
| * treat this node as the result of the action and sync/speak it as if it had |
| * gotten to this node through ChromeVox's default algorithm. If this field is |
| * left as null, then ChromeVox assumes that the web app has already handled |
| * speaking/syncing to the result and will do nothing more for this action. |
| * |
| */ |
| |
| goog.provide('cvox.UserEventDetail'); |
| |
| goog.require('cvox.ChromeVox'); |
| |
| |
| |
| /** |
| * Enables web apps to use its own algorithms to handle certain ChromeVox |
| * actions where the web app may be able to do a better job than the default |
| * ChromeVox algorithms because it has much more information about its own |
| * content and functionality. |
| * @constructor |
| * |
| * @param {Object<{command: (string), |
| * status: (undefined|string), |
| * resultNode: (undefined|Node), |
| * customCommand: (undefined|string) |
| * }>} detailObj |
| * command: The ChromeVox UserCommand to be performed. |
| * status: The status of the event. If the status is left at PENDING, ChromeVox |
| * will run its default algorithm for performing the action. Otherwise, it means |
| * the underlying web app has performed the action itself. If the status is set |
| * to FAILURE, ChromeVox will speak the default error message for this command |
| * to the user. |
| * resultNode: The result of the action if it has been performed and there is a |
| * result. If this is a valid node and the status is set to SUCCESS, ChromeVox |
| * will sync to this node and speak it. |
| * customCommand: The custom command to be performed. This is designed to allow |
| * web apps / other extensions to define custom actions that can be shown in |
| * ChromeVox (for example, inside the context menu) and then dispatched back to |
| * the page. |
| */ |
| cvox.UserEventDetail = function(detailObj) { |
| /** |
| * The category of command that should be performed. |
| * @type {string} |
| */ |
| this.category = ''; |
| |
| /** |
| * The user command that should be performed. |
| * @type {string} |
| */ |
| this.command = ''; |
| if (cvox.UserEventDetail.JUMP_COMMANDS.indexOf(detailObj.command) != -1) { |
| this.command = detailObj.command; |
| this.category = cvox.UserEventDetail.Category.JUMP; |
| } |
| |
| /** |
| * The custom command that should be performed. |
| * @type {string} |
| */ |
| this.customCommand = ''; |
| if (detailObj.customCommand) { |
| this.customCommand = detailObj.customCommand; |
| this.category = cvox.UserEventDetail.Category.CUSTOM; |
| } |
| |
| /** |
| * The status of the event. |
| * @type {string} |
| */ |
| this.status = cvox.UserEventDetail.Status.PENDING; |
| switch (detailObj.status) { |
| case cvox.UserEventDetail.Status.SUCCESS: |
| this.status = cvox.UserEventDetail.Status.SUCCESS; |
| break; |
| case cvox.UserEventDetail.Status.FAILURE: |
| this.status = cvox.UserEventDetail.Status.FAILURE; |
| break; |
| } |
| |
| /** |
| * The result of performing the command. |
| * |
| * @type {Node} |
| */ |
| this.resultNode = null; |
| if (detailObj.resultNode && |
| cvox.DomUtil.isAttachedToDocument(detailObj.resultNode)) { |
| this.resultNode = detailObj.resultNode; |
| } |
| }; |
| |
| /** |
| * Category of the user event. This is the event name that the web app should |
| * be listening for. |
| * @enum {string} |
| */ |
| cvox.UserEventDetail.Category = { |
| JUMP: 'ATJumpEvent', |
| CUSTOM: 'ATCustomEvent' |
| }; |
| |
| /** |
| * Status of the cvoxUserEvent. Events start off as PENDING. If the underlying |
| * web app has handled this event, it should set the event to either SUCCESS or |
| * FAILURE to prevent ChromeVox from trying to redo the same command. |
| * @enum {string} |
| */ |
| cvox.UserEventDetail.Status = { |
| PENDING: 'PENDING', |
| SUCCESS: 'SUCCESS', |
| FAILURE: 'FAILURE' |
| }; |
| |
| |
| /** |
| * List of commands that are dispatchable to the page. |
| * |
| * @type {Array} |
| */ |
| // TODO (clchen): Integrate this with command_store.js. |
| cvox.UserEventDetail.JUMP_COMMANDS = [ |
| 'nextCheckbox', 'previousCheckbox', 'nextRadio', 'previousRadio', |
| 'nextSlider', 'previousSlider', 'nextGraphic', 'previousGraphic', |
| 'nextButton', 'previousButton', 'nextComboBox', 'previousComboBox', |
| 'nextEditText', 'previousEditText', 'nextHeading', 'previousHeading', |
| 'nextHeading1', 'previousHeading1', 'nextHeading2', 'previousHeading2', |
| 'nextHeading3', 'previousHeading3', 'nextHeading4', 'previousHeading4', |
| 'nextHeading5', 'previousHeading5', 'nextHeading6', 'previousHeading6', |
| 'nextLink', 'previousLink', 'nextMath', 'previousMath', 'nextTable', |
| 'previousTable', 'nextList', 'previousList', 'nextListItem', |
| 'previousListItem', 'nextFormField', 'previousFormField', 'nextLandmark', |
| 'previousLandmark', 'nextSection', 'previousSection', 'nextControl', |
| 'previousControl' |
| ]; |
| |
| /** |
| * Creates a custom event object from the UserEventDetail. |
| * |
| * @return {!Event} A custom event object that can be dispatched to the page. |
| */ |
| cvox.UserEventDetail.prototype.createEventObject = function() { |
| // We use CustomEvent so that it will go all the way to the page and come back |
| // into the ChromeVox context correctly. |
| var evt = document.createEvent('CustomEvent'); |
| evt.initCustomEvent(this.category, true, true, this); |
| return evt; |
| }; |