chrome/browser/resources/chromeos/chromevox/common/nav_description.js

   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 A simple container object for the description of a
   7  * navigation from one object to another.
   8  *
   9  */
  10
  11
  12 goog.provide('cvox.NavDescription');
  13
  14 goog.require('cvox.AbstractTts');
  15 goog.require('cvox.ChromeVox');
  16 goog.require('cvox.CursorSelection');
  17 goog.require('cvox.QueueMode');
  18
  19 /**
  20  * A class representing the description of navigation from one object to
  21  * another.
  22  * @param {{context: (undefined|string),
  23  *          text: (string),
  24  *          userValue: (undefined|string),
  25  *          annotation: (undefined|string),
  26  *          earcons: (undefined|Array<cvox.Earcon>),
  27  *          personality: (undefined|Object),
  28  *          hint: (undefined|string),
  29             category: (undefined|string)}} kwargs The arguments for this
  30  *  description.
  31  *  context The context, for example descriptions of objects
  32  *     that were crossed into, like "Toolbar" or "Menu Bar" or "List with
  33  *     5 items". This is all spoken with an annotation voice.
  34  *  text The text of the object itself, including text from
  35  *     titles, labels, etc.
  36  *  userValue The text that the user has entered.
  37  *  annotation The role and state of the object.
  38  *  earcons A list of the earcon ids to play along
  39  *     with the spoken description of this object.
  40  *  personality Optional TTS personality to use for the text.
  41  *  hint Optional Hint text (.e.g. aria-describedby).
  42  *  category Optional category (for speech queueing behavior).
  43  * @constructor
  44  */
  45 cvox.NavDescription = function(kwargs) {
  46   this.context = kwargs.context ? kwargs.context : '';
  47   this.text = kwargs.text ? kwargs.text : '';
  48   this.userValue = kwargs.userValue ? kwargs.userValue : '';
  49   this.annotation = kwargs.annotation ? kwargs.annotation : '';
  50   this.earcons = kwargs.earcons ? kwargs.earcons : [];
  51   this.personality = kwargs.personality;
  52   this.hint = kwargs.hint ? kwargs.hint : '';
  53   this.category = kwargs.category ? kwargs.category : null;
  54 };
  55
  56
  57 /**
  58  * @return {boolean} true if this description is empty.
  59  */
  60 cvox.NavDescription.prototype.isEmpty = function() {
  61   return (this.context.length == 0 &&
  62           this.earcons.length == 0 &&
  63           this.text.length == 0 &&
  64           this.userValue.length == 0 &&
  65           this.annotation.length == 0);
  66 };
  67
  68
  69 /**
  70  * @return {string} A string representation of this object.
  71  */
  72 cvox.NavDescription.prototype.toString = function() {
  73   return 'NavDescription(context="' + this.context + '" ' +
  74          ' text="' + this.text + '" ' +
  75          ' userValue="' + this.userValue + '" ' +
  76          ' annotation="' + this.annotation +
  77          (this.category ? '" category="' + this.category + '")' : '') +
  78          '")';
  79 };
  80
  81
  82 /**
  83  * Modifies the earcon to play along with the spoken description of the object.
  84  * @param {cvox.Earcon} earconId An earcon id to be pushed on to the list of
  85  * earcon ids to play along with the spoken description of this object.
  86  */
  87 cvox.NavDescription.prototype.pushEarcon = function(earconId) {
  88   this.earcons.push(earconId);
  89 };
  90
  91
  92 /**
  93  * Speak this nav description with the given queue mode.
  94  * @param {cvox.QueueMode=} queueMode The queue mode.
  95  * @param {function()=} opt_startCallback Function called when this
  96  *     starts speaking.
  97  * @param {function()=} opt_endCallback Function called when this ends speaking.
  98  */
  99 cvox.NavDescription.prototype.speak = function(
 100     queueMode, opt_startCallback, opt_endCallback) {
 101   /**
 102    * Return a deep copy of PERSONALITY_ANNOTATION for modifying.
 103    * @return {Object} The newly created properties object.
 104    */
 105   function makeAnnotationProps() {
 106     var properties = {};
 107     var src = cvox.AbstractTts.PERSONALITY_ANNOTATION;
 108     for (var key in src) {
 109       properties[key] = src[key];
 110     }
 111     return properties;
 112   }
 113
 114   var speakArgs = new Array();
 115   if (this.context) {
 116     speakArgs.push([this.context, queueMode, makeAnnotationProps()]);
 117     queueMode = cvox.QueueMode.QUEUE;
 118   }
 119
 120   speakArgs.push([this.text,
 121                   queueMode,
 122                   this.personality ? this.personality : {}]);
 123   queueMode = cvox.QueueMode.QUEUE;
 124
 125   if (this.userValue) {
 126     speakArgs.push([this.userValue, queueMode, {}]);
 127   }
 128
 129   if (this.annotation) {
 130     speakArgs.push([this.annotation, queueMode, makeAnnotationProps()]);
 131   }
 132
 133   if (this.hint) {
 134     speakArgs.push([this.hint, queueMode, makeAnnotationProps()]);
 135   }
 136
 137   var length = speakArgs.length;
 138   for (var i = 0; i < length; i++) {
 139     if (i == 0 && opt_startCallback) {
 140       speakArgs[i][2]['startCallback'] = opt_startCallback;
 141     }
 142     if (i == length - 1 && opt_endCallback) {
 143       speakArgs[i][2]['endCallback'] = opt_endCallback;
 144     }
 145     if (this.category) {
 146       speakArgs[i][2]['category'] = this.category;
 147     }
 148     cvox.ChromeVox.tts.speak.apply(cvox.ChromeVox.tts, speakArgs[i]);
 149   }
 150 };
 151
 152
 153 /**
 154  * Compares two NavDescriptions.
 155  * @param {cvox.NavDescription} that A NavDescription.
 156  * @return {boolean} True if equal.
 157  */
 158 cvox.NavDescription.prototype.equals = function(that) {
 159   return this.context == that.context &&
 160       this.text == that.text &&
 161       this.userValue == that.userValue &&
 162       this.annotation == that.annotation;
 163 };