Skip to content

Commit

Permalink
FLUID-6177: Updating comments and typdefs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jobara
jobara committed Jul 16, 2018
1 parent fd6de9e commit 5a8a642
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 30 deletions.
39 changes: 26 additions & 13 deletions src/components/orator/js/Orator.js
View file
Expand Up @@ -190,12 +190,32 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
}
});

/**
* Used to toggle the state of a model value at a specified path. The new state will be the inverse of the current
* boolean value at the specified model path, or can be set explicitly by passing in a 'state' value. It's likely
* that this method will be used in conjunction with a click handler. In that case it's most likely that the state
* will be toggling the existing model value.
*
* @param {Component} that - the component
* @param {String|Array} path - the path, into the model, for the value to toggle
* @param {Boolean} state - (optional) explicit state to set the model value to
*/
fluid.orator.controller.toggleState = function (that, path, state) {
var newState = fluid.isValue(state) ? state : !fluid.get(that.model, path);
// the !! ensures that the newState is a boolean value.
that.applier.change(path, !!newState, "ADD", "toggleState");
};

/**
* Sets the view state of the toggle controller.
* True - play style added
* - aria-label set to the `pause` string
* False - play style removed
* - aria-label set to the `play` string
*
* @param {Component} that - the component
* @param {Boolean} state - the state to set the controller to
*/
fluid.orator.controller.setToggleView = function (that, state) {
var playToggle = that.locate("playToggle");
playToggle.toggleClass(that.options.styles.play, state);
Expand Down Expand Up @@ -452,7 +472,7 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
* Sets the parseQueue and related model values
*
* @param {Component} that - the component
* @param {DomWordMappings} parseQueue - An array of {DomWordMap} objects containing the position mappings from a parsed
* @param {{DomWordMap[]}} parseQueue - An array of {DomWordMap} objects containing the position mappings from a parsed
* {DomElement}.
*/
fluid.orator.domReader.setParseQueue = function (that, parseQueue) {
Expand Down Expand Up @@ -483,18 +503,10 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
* @typedef {Object} DomWordMap
*/

/**
* An array of {DomWordMap} objects detailing the words parsed from the a {DomElement}. This information can be used
* to map the synthesized speech to the location of each word in the DOM; which is useful for highlighting words as
* they are being read.
*
* @typedef {Array} DomWordMappings
*/

/**
* Combines the parsed text into a String.
*
* @param {DomWordMappings} parsed - An array of {DomWordMap} objects containing the position mappings from a parsed
* @param {{DomWordMap[]}} parsed - An array of {DomWordMap} objects containing the position mappings from a parsed
* {DomElement}.
*
* @return {String} - The parsed text combined into a String.
Expand Down Expand Up @@ -530,6 +542,7 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
*
* @param {Component} that - The component
* @param {Integer} boundary - The boundary value used to compare against the blockIndex of the parsed data points.
* If the boundary is undefined or out of bounds, `undefined` will be returned.
*
* @return {Integer|undefined} - Will return the index of the closest data point in the parseQueue. If the boundary
* cannot be located within the parseQueue, `undefined` is returned.
Expand Down Expand Up @@ -659,12 +672,12 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
};

/**
* Adds a {DomWordMap} to the 'parsed' {DomWordMappings} array, containing the position mappings for the parsed DOM
* Adds a {DomWordMap} to the 'parsed' {{DomWordMap[]}} array, containing the position mappings for the parsed DOM
* elements.
*
* See: DomWordMap TypeDef for a detailed description of its structure.
*
* @param {DomWordMappings} parsed - An array of {DomWordMap} objects containing the position mappings from a parsed
* @param {{DomWordMap[]}} parsed - An array of {DomWordMap} objects containing the position mappings from a parsed
* {DomElement}.
* @param {String} word - The word, parsed from the node, to be added
* @param {DomNode} childNode - The current textnode being operated on
Expand Down Expand Up @@ -697,7 +710,7 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
* @param {Integer} blockIndex - The `blockIndex` represents the index into the entire block of text being parsed.
* It defaults to 0 and is primarily used internally for recursive calls.
*
* @return {DomWordMappings} - An array of {DomWordMap} objects containing the position mappings parsed from `elm`.
* @return {{DomWordMap[]}} - An array of {DomWordMap} objects containing the position mappings parsed from `elm`.
*/
fluid.orator.domReader.parser.parse = function (that, elm, blockIndex) {
var parsed = [];
Expand Down
34 changes: 17 additions & 17 deletions src/components/textToSpeech/js/TextToSpeech.js
View file
Expand Up @@ -295,22 +295,30 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
}
};

/**
* Options to configure the SpeechSynthesis Utterance with.
* See: https://w3c.github.io/speech-api/speechapi.html#utterance-attributes
* {
* text: "", // the text to Synthesize
* lang: "", // the language of the synthesized text
* voice: {} // a WebSpeechSynthesis object; if not set, will use the default one provided by the browser
* volume: 1, // a Floating point number between 0 and 1
* rate: 1, // a Floating point number from 0.1 to 10 although different synthesizers may have a smaller range
* pitch: 1, // a Floating point number from 0 to 2
* }
*
* @typedef {Object} UtteranceOpts
*/

/**
* Assembles the utterance options and fires onSpeechQueued which will kick off the creation of an utterance
* component. If "interrupt" is true, this utterance will replace any existing ones.
*
* @param {Component} that - the component
* @param {String} text - the text to be synthesized
* @param {Boolean} interrupt - used to indicate if this text should be queued or replace existing utterances
* @param {Object} options - options to configure the SpeechSynthesis utterance with. It is merged on top of the
* @param {UtteranceOpts} options - options to configure the SpeechSynthesis utterance with. It is merged on top of the
* utteranceOpts from the component's model.
* {
* lang: "", // the language of the synthesized text
* voice: {} // a WebSpeechSynthesis object; if not set, will use the default one provided by the browser
* volume: 1, // a Floating point number between 0 and 1
* rate: 1, // a Floating point number from 0.1 to 10 although different synthesizers may have a smaller range
* pitch: 1, // a Floating point number from 0 to 2
* }
*
* @return {Promise} - returns a promise that is resolved after the onSpeechQueued event has fired.
*/
Expand Down Expand Up @@ -402,15 +410,7 @@ var fluid_3_0_0 = fluid_3_0_0 || {};
*
* @param {Component} that - the component
* @param {Object} utteranceEventMap - a mapping from SpeechSynthesisUtterance events to component events.
* @param {Object} utteranceOpts - options to configure the SpeechSynthesis utterance with.
* {
* text: "", // the text to Synthesize
* lang: "", // the language of the synthesized text
* voice: {} // a WebSpeechSynthesis object; if not set, will use the default one provided by the browser
* volume: 1, // a Floating point number between 0 and 1
* rate: 1, // a Floating point number from 0.1 to 10 although different synthesizers may have a smaller range
* pitch: 1, // a Floating point number from 0 to 2
* }
* @param {UtteranceOpts} utteranceOpts - options to configure the SpeechSynthesis utterance with.
*
* @return {SpeechSynthesisUtterance} - returns the created SpeechSynthesisUtterance object
*/
Expand Down

0 comments on commit 5a8a642

Please sign in to comment.