Speech-enable custom controls (Browser)

You can provide custom implementations to speech-enable controls which Dragon Medical SpeechKit doesn't support natively.

When the NUSA_configure() function is called, Dragon Medical SpeechKit scans the HTML page for all supported edit controls (such as regular HTML form text fields) and for elements that have been tagged with a data-nusa-custom-control-type attribute. The text and selection ranges of the latter aren't accessed directly by Dragon Medical SpeechKit; instead, Dragon Medical SpeechKit calls functions provided by the integration as described below.

Prerequisites

You've initialized speech recognition for a web page.

Speech-enabling edit controls that are represented by a focusable HTML element

The following procedure is valid for custom edit controls that are represented by an HTML element for which JavaScript focus or click events are fired whenever the edit control is focused.

Example: An edit control is implemented as an ActiveX, Flash or Silverlight object, or as a JavaScript editor.

Proceed as follows:

In your NUSA_configure() function, register the custom control type and set its properties and methods as described in section Custom control interface.
On the HTML page, mark all edit control elements with the control type; for example: <object data-nusa-custom-control-type="MyCustomControl".

The attribute data-nusa-custom-control-type specifies the custom control type name as passed to the NUSA_registerCustomControlType(customControlTypeName) call.

For more information, see the Sample_CustomControl.html sample implementation delivered with the SDK package.

Note

You can register multiple custom control types if different kinds of edit controls have to be accessed.

Speech-enabling edit controls that can't be accessed directly by SpeechKit

The following procedure is valid for custom edit controls without a one-to-one association with an HTML element that can be assigned a data-nusa-custom-control-type attribute; for these edit controls, Dragon Medical SpeechKit doesn't receive any JavaScript focus or click events.

Example: Multiple edit controls are contained within a single ActiveX, Flash or Silverlight object, or a JavaScript editor dynamically creates the <div> elements on which it operates.

Tip

Edit controls that are contained in an iframe can be speech-enabled automatically by calling the NUSA_initialize() function. For more information and examples, see: Deferred initialization of Dragon Medical SpeechKit.

Dragon Medical SpeechKit must be informed which edit control has the input focus and must be able to set the focus to individual edit controls. Therefore, the integration must provide functions for getting and setting the focus.

Proceed as follows:

In your NUSA_configure() function, register the custom control type for the edit controls and a custom container type, and set the functions as described in sections Custom control interface and Custom container interface. Example: The custom control type is registered by the name MyCustomControl and the custom container type is registered by the name MyCustomContainer.
As the edit controls don't have a one-to-one association with HTML elements that could be assigned Dragon Medical SpeechKit attributes, you must add proxy elements to the HTML page:
- Add a proxy for the container:
```
<div id="MyCustomContainerInstance" data-nusa-custom-container-type="MyCustomContainer"></div>
```
  The data-nusa-custom-container-type attribute is set to the name the custom container was registered by.
- For each custom control you want to speech-enable, add a proxy element that refers to the container:
```
<div id="MyCustomControlInstance_1" data-nusa-custom-container-id="MyCustomContainerInstance" data-nusa-custom-control-type="MyCustomControl"></div>
...
<div id="MyCustomControlInstance_x" data-nusa-custom-container-id="MyCustomContainerInstance" data-nusa-custom-control-type="MyCustomControl"></div>
```
  The data-nusa-custom-container-id attribute is set to the ID of the container element and the data-nusa-custom-control-type attribute is set to the name the custom control was registered by.
The proxy elements are used as parameters on the custom control and container functions. Your implementation of these functions must map between these proxy elements and the actual edit controls.
Call the NUSA_customContainerFocussed() function whenever the focus is set to one of the edit controls in the container.

For more information, see the Sample_CustomFrameContainer.html sample implementation and the iframe Sample_CustomFrame.html delivered with the SDK package.

The custom control interface

Important information

None of the methods on the custom control interface must change the focus to the targeted edit control. Focus changes between edit controls must be handled separately from changes within edit controls (insertion point change, selection change, text change).

Edit controls must keep track of the last location of the selection or insertion point. For example, the insertion point is in the middle of an edit control and the focus is moved away from that edit control. If the focus is then set back to that edit control programmatically (for example, via a next field command), the insertion point should again be at the original location, in the middle of the edit control.

This information is especially relevant for programmatic selection changes. If, for example, setSelection() is called for an unfocused edit control, the focus must not be set to this edit control; only the new location of the insertion point must be stored. If later the focus changes to this control, the insertion point should be at the location previously stored.

Registering a custom control

To speech-enable your custom controls, you must register a custom control type, implement a set of functions for retrieving and setting text and selection ranges that are needed to interact with the speech recognition system, and identify the HTML elements that represent the corresponding custom controls on the page.

function NUSA_registerCustomControlType(customControlTypeName)

Registers a new custom control type.

customControlTypeName - a string used to identify the custom control type. This name must be used as the value of a data-nusa-custom-control-type attribute on elements representing an edit control of this type.

Return value: A CustomControl instance that has been associated with the given name.

To disable speech recognition for a custom control, remove the data-nusa-custom-control-type attribute and call NUSA_reinitializeVuiForm(). The data-nusa-enabled attribute can't be used for custom controls.

Custom control members

The following properties and methods must be set on the CustomControl instance returned by NUSA_registerCustomControlType().

Important

All properties and methods are mandatory.

Properties to be set:

newlineFormat

A string that represents a line break in the control's text.
paragraphFormat

A string that represents a paragraph break in the control's text.

These strings must match the characters that your edit control uses for a line break and a paragraph break. If your edit control doesn't support paragraphs, use two line breaks. For example, if newlineFormat = "\n":

paragraphFormat = "\n\n";

If your edit control supports single-line text fields only, omit these strings.

Methods to be implemented:

function replaceText(element, text, fromPos, length )

Replaces part of the text in the specified custom control.

element – the HTML element representing the custom control.

text – the new text as string.

fromPos – position of the first character to be replaced (the first character of text has fromPos '0').

length – number of characters to be replaced.

After a replaceText() call, the insertion point must be located at the same position in the text as before the call. This means that if replaceText() inserts or removes characters to the left of the current insertion point or selection, the location of the insertion point must be moved accordingly. If replaceText() modifies text to the right of the insertion point, the insertion point must not change. If replaceText() modifies characters at the insertion point, the insertion point must be set to the end of the modified region. Ideally, if replaceText() is called while the user is typing and modifying text to the left or right of the typing location, this won't interfere with the user's keyboard input. This is to ensure that speech recognition results can be inserted in the text asynchronously while the user is, for example, correcting a misrecognition at another location in the text.
function getText(element)

Retrieves the current text of the specified custom control.

element – the HTML element representing the custom control.

Return value: the current text as string.
function getSelectionText(element)

Retrieves the currently selected text of the specified custom control.

element – the HTML element representing the custom control.

Return value: the selected text as string.
function getSelection(element)

Retrieves the current selection range of the specified custom control.

element – the HTML element representing the custom control.

Return value: NUSA_selectionInfo object whose start and length properties specify the selected text range. For example:
```
var selInfo = new NUSA_selectionInfo();
selInfo.start = ...; selInfo.length = ...;
```
function setSelection(element, start, length)

Sets the selection in the specified custom control.

element – HTML element representing the custom control.

start – position of the first character to select.

length – length of the selection.

Custom control interface example

var customControlType = NUSA_registerCustomControlType("MyCustomControl");
customControlType.newlineFormat = "\n";
customControlType.paragraphFormat = "\v";
customControlType.replaceText = myCustomControl_replaceText;
customControlType.getText = myCustomControl_getText;
customControlType.getSelectionText = myCustomControl_getSelectionText;
customControlType.getSelection = myCustomControl_getSelection;
customControlType.setSelection = myCustomControl_setSelection;
function myCustomControl_replaceText(...) { ... }

The custom container interface

Registering a custom container

To implement focus handling for custom controls that can't be accessed directly by Dragon Medical SpeechKit, you must register a custom container type in addition to the custom control type and implement a set of functions for retrieving and setting the focus.

function NUSA_registerCustomContainerType(customContainerTypeName)

Registers a new custom container type.

customContainerTypeName - a string used to identify the custom container type. This name must be used as the value of a data-nusa-custom-container-type attribute on elements representing a container of this type.

Return value: a CustomContainer instance that has been associated with the given name.

Custom container members

The following methods must be set on the CustomContainer instance returned by NUSA_registerCustomContainerType().

The element parameters of these functions refer to the HTML elements that act as proxies for the actual edit controls and that have been tagged with the data-nusa-custom-control-type attribute; you must map between these proxy elements and the actual edit controls.

Important

All methods are mandatory.

The methods to be implemented:

function getFocussedElement(containerElement)

Returns the focused edit control in the specified containerElement.

containerElement – the HTML element tagged with the data-nusa-custom-container-type attribute.

Return value: the HTML element tagged with the data-nusa-custom-control-type attribute that acts as proxy for the currently focused edit control in the container.
function setFocussedElement(element)

Sets the focus to the specified edit control.

element – the HTML element tagged with the data-nusa-custom-control-type attribute that acts as proxy for the edit control to be focused.

Custom container interface example

var customContainerType = NUSA_registerCustomContainerType("MyCustomContainer");
customContainerType.getFocussedElement = myCustomContainer_getFocussedElement;
customContainerType.setFocussedElement = myCustomContainer_setFocussedElement;
function myCustomContainer_getFocussedElement(...) { ... }
function myCustomContainer_setFocussedElement(...) { ... }

Active focus change notification

In addition to allowing Dragon Medical SpeechKit to get and set the current focus, you must also notify Dragon Medical SpeechKit when the focus is set to an edit control, for example via mouse click.

function NUSA_customContainerFocussed(containerElement)

This function must be called whenever the focus is set to one of the edit controls in the container.

containerElement - the HTML element tagged with the data-nusa-custom-container-type attribute.

Custom container with HTML5 content-editable controls (Microsoft Internet Explorer)

If the custom control triggers a control with the HTML5 contenteditable attribute set in the background, the NUSA_cleanupContenEditable(contentEditableElement) function must be called before initializing speech recognition on your web page. It can be called in your NUSA_configure() function or, for deferred initialization, before calling NUSA_initialize(). If you add a new container dynamically, call the function before the NUSA_reinitializeVuiForm() function.

Microsoft Internet Explorer can't provide correct selection information if whitespace characters (enter and indent) are used in the HTML code within the contenteditable controls with preset content. If you use whitespace characters to keep your source code readable, call the NUSA_cleanupContenEditable(contentEditableElement) function to remove superfluous whitespaces.

Feedback

Was this page helpful?

Last updated on 2025-03-07