user_event_detail.js revision cedac228d2dd51db4b79ea1e72c7f249408ee061 
1// Copyright 2014 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/**
6 * @fileoverview The ChromeVox User Event Detail object.
7 *
8 * This is the detail object for a CustomEvent that ChromeVox sends to the
9 * current node in the DOM when the user wants to perform a ChromeVox action
10 * that could potentially be handled better by the underlying web app.
11 *
12 * ChromeVox events are sent with status "PENDING" and an action that maps to
13 * the command list in ChromeVoxUserCommands.
14 *
15 * If a web app wishes to handle the action, it can perform the action then set
16 * the status of the event to either "SUCCESS" or "FAILURE".
17 *
18 * When the event bubbles back up to the document, ChromeVox will process it.
19 * If the status is "PENDING", ChromeVox will perform the action itself.
20 * If the status is "FAILURE", ChromeVox will speak the associated error message
21 * for that action. (For example: "No next heading.")
22 * If the status is "SUCCESS", then ChromeVox will check to see if an associated
23 * resultNode is added to the event. If this node exists, then ChromeVox will
24 * treat this node as the result of the action and sync/speak it as if it had
25 * gotten to this node through ChromeVox's default algorithm. If this field is
26 * left as null, then ChromeVox assumes that the web app has already handled
27 * speaking/syncing to the result and will do nothing more for this action.
28 *
29 */
30
31goog.provide('cvox.UserEventDetail');
32
33goog.require('cvox.ChromeVox');
34
35
36
37/**
38 * Enables web apps to use its own algorithms to handle certain ChromeVox
39 * actions where the web app may be able to do a better job than the default
40 * ChromeVox algorithms because it has much more information about its own
41 * content and functionality.
42 * @constructor
43 *
44 * @param {Object.<{command: (string),
45 *                         status: (undefined|string),
46 *                         resultNode: (undefined|Node),
47 *                         customCommand: (undefined|string)
48 *                         }>} detailObj
49 * command: The ChromeVox UserCommand to be performed.
50 * status: The status of the event. If the status is left at PENDING, ChromeVox
51 * will run its default algorithm for performing the action. Otherwise, it means
52 * the underlying web app has performed the action itself. If the status is set
53 * to FAILURE, ChromeVox will speak the default error message for this command
54 * to the user.
55 * resultNode: The result of the action if it has been performed and there is a
56 * result. If this is a valid node and the status is set to SUCCESS, ChromeVox
57 * will sync to this node and speak it.
58 * customCommand: The custom command to be performed. This is designed to allow
59 * web apps / other extensions to define custom actions that can be shown in
60 * ChromeVox (for example, inside the context menu) and then dispatched back to
61 * the page.
62 */
63cvox.UserEventDetail = function(detailObj) {
64  /**
65   * The category of command that should be performed.
66   * @type {string}
67   */
68  this.category = '';
69
70  /**
71   * The user command that should be performed.
72   * @type {string}
73   */
74  this.command = '';
75  if (cvox.UserEventDetail.JUMP_COMMANDS.indexOf(detailObj.command) != -1) {
76    this.command = detailObj.command;
77    this.category = cvox.UserEventDetail.Category.JUMP;
78  }
79
80  /**
81   * The custom command that should be performed.
82   * @type {string}
83   */
84  this.customCommand = '';
85  if (detailObj.customCommand) {
86    this.customCommand = detailObj.customCommand;
87    this.category = cvox.UserEventDetail.Category.CUSTOM;
88  }
89
90  /**
91   * The status of the event.
92   * @type {string}
93   */
94  this.status = cvox.UserEventDetail.Status.PENDING;
95  switch (detailObj.status) {
96    case cvox.UserEventDetail.Status.SUCCESS:
97      this.status = cvox.UserEventDetail.Status.SUCCESS;
98      break;
99    case cvox.UserEventDetail.Status.FAILURE:
100      this.status = cvox.UserEventDetail.Status.FAILURE;
101      break;
102  }
103
104  /**
105   * The result of performing the command.
106   *
107   * @type {Node}
108   */
109  this.resultNode = null;
110  if (detailObj.resultNode &&
111      cvox.DomUtil.isAttachedToDocument(detailObj.resultNode)) {
112    this.resultNode = detailObj.resultNode;
113  }
114};
115
116/**
117 * Category of the user event. This is the event name that the web app should
118 * be listening for.
119 * @enum {string}
120 */
121cvox.UserEventDetail.Category = {
122  JUMP: 'ATJumpEvent',
123  CUSTOM: 'ATCustomEvent'
124};
125
126/**
127 * Status of the cvoxUserEvent. Events start off as PENDING. If the underlying
128 * web app has handled this event, it should set the event to either SUCCESS or
129 * FAILURE to prevent ChromeVox from trying to redo the same command.
130 * @enum {string}
131 */
132cvox.UserEventDetail.Status = {
133  PENDING: 'PENDING',
134  SUCCESS: 'SUCCESS',
135  FAILURE: 'FAILURE'
136};
137
138
139/**
140 * List of commands that are dispatchable to the page.
141 *
142 * @type {Array}
143 */
144// TODO (clchen): Integrate this with command_store.js.
145cvox.UserEventDetail.JUMP_COMMANDS = [
146  'nextCheckbox', 'previousCheckbox', 'nextRadio', 'previousRadio',
147  'nextSlider', 'previousSlider', 'nextGraphic', 'previousGraphic',
148  'nextButton', 'previousButton', 'nextComboBox', 'previousComboBox',
149  'nextEditText', 'previousEditText', 'nextHeading', 'previousHeading',
150  'nextHeading1', 'previousHeading1', 'nextHeading2', 'previousHeading2',
151  'nextHeading3', 'previousHeading3', 'nextHeading4', 'previousHeading4',
152  'nextHeading5', 'previousHeading5', 'nextHeading6', 'previousHeading6',
153  'nextLink', 'previousLink', 'nextMath', 'previousMath', 'nextTable',
154  'previousTable', 'nextList', 'previousList', 'nextListItem',
155  'previousListItem', 'nextFormField', 'previousFormField', 'nextLandmark',
156  'previousLandmark', 'nextSection', 'previousSection', 'nextControl',
157  'previousControl'
158];
159
160/**
161 * Creates a custom event object from the UserEventDetail.
162 *
163 * @return {!Event} A custom event object that can be dispatched to the page.
164 */
165cvox.UserEventDetail.prototype.createEventObject = function() {
166  // We use CustomEvent so that it will go all the way to the page and come back
167  // into the ChromeVox context correctly.
168  var evt = document.createEvent('CustomEvent');
169  evt.initCustomEvent(this.category, true, true, this);
170  return evt;
171};
172