DictationTargets

Description

DictationTargets finds the text field to dictate into from anywhere on the page: the focused field, else the first visible one that takes text. Use it for a push-to-talk button, a keyboard shortcut or a voice command that types into whatever field the user is in, without holding references to the fields.

Every TextBox, TextArea and OmniBox is an IDictationTarget, wherever it was built, and registers itself on construction. Nothing needs to be declared. Each target stores itself in a hidden field of its root element and marks the element with data-tss-dictation, so a query is one querySelectorAll over what is on the page now. A field removed from the page is not found.

The words come from the field's own source, else Dictation.Provider, else the browser's speech recognition. The browser path needs a microphone and a browser that exposes a speech recognition API, and the user has to grant microphone permission. A field with no source and no browser support cannot dictate: CanDictate is false and BeginDictation() does nothing.

Usage

DictationTargets.Current() returns the focused target, else the first visible one that is editable, or null when there is none. Call BeginDictation() on it.

A button takes focus when it is clicked, so Focused() would then find the button's page rather than the field. Stop the mousedown on the button so the field keeps focus. The sample below uses a scripted speech source in place of a microphone, so it runs in any browser.

Push-to-talk button

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            // Stands in for a speech service: delivers a few words, one every 250 ms.
            Action ScriptedSpeech(DictationSession session)
            {
                var words  = new[] { "this", "was", "dictated", "into", "the", "current", "field" };
                var heard  = 0;
                var handle = 0.0;

                Action step = null;
                step = () =>
                {
                    heard++;
                    session.SetTranscript(string.Join(" ", words.Take(heard)), heard == words.Length);
                    if (heard == words.Length) session.End();
                    else handle = window.setTimeout(_ => step(), 250);
                };

                handle = window.setTimeout(_ => step(), 250);
                return () => window.clearTimeout(handle);
            }

            var note = TextBox().SetPlaceholder("Click here, then press Talk").DictationSource(ScriptedSpeech);

            var talk = Button("Talk").Primary().OnClick((_, __) => DictationTargets.Current()?.BeginDictation());
            talk.Render().addEventListener("mousedown", (Event e) => e.preventDefault());

            var component = Stack().W(360).Children(note, talk);

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Members

IDictationTarget:

DictationTargets (static):

The queries live on a static class rather than on the interface because the netstandard2.0 target does not allow static interface members.

API reference

public static class DictationTargets

public static void Register(HTMLElement element, IDictationTarget target)

public static IDictationTarget Of(HTMLElement element)

public static IReadOnlyList<HTMLElement> Elements()

public static IReadOnlyList<IDictationTarget> All()

public static IReadOnlyList<IDictationTarget> Visible()

public static IDictationTarget Focused()

public static IDictationTarget Current()

public const string ElementAttribute = "data-tss-dictation"

public interface IDictationTarget

string Text { get; set; }

bool IsEditable { get; }

bool CanDictate { get; }

bool IsDictating { get; }

void BeginDictation()

void EndDictation()

See also

• Text Box
• Text Area