diff --git a/docs/DEVELOPER/release-notes/index.md b/docs/DEVELOPER/release-notes/index.md index 769c0edf..469dbde7 100644 --- a/docs/DEVELOPER/release-notes/index.md +++ b/docs/DEVELOPER/release-notes/index.md @@ -458,7 +458,7 @@ Below is a list of key developer-facing Roku OS 11.0 updates: * **[Option for Label and TextEditBox nodes to display the end of overflowing text](/docs/references/scenegraph/label-nodes/label.md#fields)** — The [**Label**](/docs/references/scenegraph/label-nodes/label.md#fields) and [**TextEditBox**](docs/references/scenegraph/widget-nodes/texteditbox.md) nodes now include a **leadingEllipsis** flag that enables developers to specify whether to show the end or beginning of text that overflows its available width. When this flag is set to true, the end of the text is shown. For example, "the quick brown fox jumps over the lazy dog" would be truncated to "...jumps over the lazy dog". When the flag is false, the start of the text is shown ("the quick brown fox jumps..."). -* [**Voice keyboard enhancements**](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/dynamic-keyboard-base.md#fields) — The SceneGraph [**DynamicKeyboardBase**](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/dynamic-keyboard-base.md#fields)) node class now includes a **hideTextBox** flag that enables developers to hide a voice keyboard's VoiceTextEditBox. +* [**Voice keyboard enhancements**](/docs/references/scenegraph/abstract-nodes/dynamic-keyboard-base.md#fields) — The SceneGraph [**DynamicKeyboardBase**](/docs/references/scenegraph/abstract-nodes/dynamic-keyboard-base.md#fields)) node class now includes a **hideTextBox** flag that enables developers to hide a voice keyboard's VoiceTextEditBox. #### BrightScript APIs @@ -640,7 +640,7 @@ Below is a list of key developer-facing Roku OS 10.0 updates: #### Architecture -* **[Dynamic voice-enabled keyboards](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/dynamic-keyboard-base.md)** — Developers can create keyboards, mini keyboards, and pin pads that can be controlled by voice. This helps speed up on-device sign-ups and sign-ins by enabling customers to speak their PIN codes when subscribing to apps and their passwords when logging in. A sample app demonstrating this feature is available [here](https://github.com/rokudev/dynamic-voice-enabled-keyboards). +* **[Dynamic voice-enabled keyboards](/docs/references/scenegraph/abstract-nodes/dynamic-keyboard-base.md)** — Developers can create keyboards, mini keyboards, and pin pads that can be controlled by voice. This helps speed up on-device sign-ups and sign-ins by enabling customers to speak their PIN codes when subscribing to apps and their passwords when logging in. A sample app demonstrating this feature is available [here](https://github.com/rokudev/dynamic-voice-enabled-keyboards). * **[Standard dialog framework](/docs/references/scenegraph/standard-dialog-framework-nodes/standard-dialog-framework-overview.md)** — Developers can use new pre-built modal pop-up dialogs and build custom ones. A sample app demonstrating this feature is available [here](https://github.com/rokudev/standard-dialog-framework). @@ -652,7 +652,7 @@ Below is a list of key developer-facing Roku OS 10.0 updates: Some fields used to set options on the Dynamic voice-enabled keyboards and the StandardDialog nodes always print their value as “invalid” in BrightScript. Equality comparisons of these field values will also not work correctly. Setting the value of these fields from either BrightScript or XML does work correctly. These fields include: - The **voiceEntryType** field of the [VoiceTextEditBox](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/voice-text-edit-box.md) node.
The **domain** field of the [DynamicKeyboardBase](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/dynamic-keyboard-base.md) node.
The **keyboardDomain** field of the [StandardKeyboardDialog](/docs/references/scenegraph/standard-dialog-framework-nodes/standard-keyboard-dialog.md) node.
The **bulletType** field of the [StdDlgBulletTextItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-bullet-text-item.md) node.
The **graphicAlign** field of the [StdDlgGraphicItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-graphic-item.md) node.
The **keyLayout** field of the [StdDlgKeyboardItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-keyboard-item.md) node.
The **namedTextStyle** field of the [StdDlgTextItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-text-item.md) node. + The **voiceEntryType** field of the [VoiceTextEditBox](/docs/references/scenegraph/dynamic-voice-keyboard-nodes/voice-text-edit-box.md) node.
The **domain** field of the [DynamicKeyboardBase](/docs/references/scenegraph/abstract-nodes/dynamic-keyboard-base.md) node.
The **keyboardDomain** field of the [StandardKeyboardDialog](/docs/references/scenegraph/standard-dialog-framework-nodes/standard-keyboard-dialog.md) node.
The **bulletType** field of the [StdDlgBulletTextItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-bullet-text-item.md) node.
The **graphicAlign** field of the [StdDlgGraphicItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-graphic-item.md) node.
The **keyLayout** field of the [StdDlgKeyboardItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-keyboard-item.md) node.
The **namedTextStyle** field of the [StdDlgTextItem](/docs/references/scenegraph/standard-dialog-framework-nodes/std-dlg-text-item.md) node. * **[Enhanced Visual Search Results for Roku Voice](/docs/developer-program/discovery/search/implementing-search.md#visual-search-results-for-roku-voice)** - When users ask for content while in an app, the Roku UI displays a partial overlay with content matching the search request. Content from within the active app is listed in the first row of the display if the active app participates in Roku Search. The rows below include matches from other apps. diff --git a/docs/REFERENCES/scenegraph/abstract-nodes/dynamic-keyboard-base.md b/docs/REFERENCES/scenegraph/abstract-nodes/dynamic-keyboard-base.md new file mode 100644 index 00000000..5f6e3abb --- /dev/null +++ b/docs/REFERENCES/scenegraph/abstract-nodes/dynamic-keyboard-base.md @@ -0,0 +1,114 @@ +--- +title: "DynamicKeyboardBase" +excerpt: 'The abstract base class for the DynamicKeyboard, DynamicPinPad, DynamicMiniKeyboard, and DynamicCustomKeyboard nodes' +deprecated: false +hidden: false +metadata: + title: 'DynamicKeyboardBase' + description: 'DynamicKeyboardBase is an abstract base class that combines a DynamicKeyGrid and a VoiceTextEditBox into a single node, providing text and voice entry support shared by all dynamic voice-enabled keyboard nodes.' + robots: index +next: + description: '' +--- +Extends [**Group**](doc:group) + +> Apps must use Roku voice keyboards for [email](doc:dynamic-keyboard), [PIN](doc:dynamic-pinpad), [password](doc:dynamic-keyboard) entry to pass [certification](doc:certification). + +The DynamicKeyboardBase is an abstract class that provides the functionality for dynamic voice-enabled keyboards. It combines [**DynamicKeyGrid**](doc:dynamic-key-grid) and [**VoiceTextEditBox**](doc:voice-text-edit-box) nodes to provide a single node that supports text entry in multiple languages and voice entry in English and Spanish. + +- The [**DynamicKeyGrid**](doc:dynamic-key-grid) provides keyboard functionality. The layout of the keyboard is based on a JSON-formatted Key Definition File. + + The classes derived from DynamicKeyboardBase (DynamicKeyboard, DynamicPinPad, and DynamicMiniKeyboard) have built-in Key Definition Files. For example, the DynamicKeyboard node uses a Key Definition File that matches the key layout of the [legacy Keyboard node](doc:keyboard). + + The [**DynamicCustomKeyboard** node](doc:dynamic-custom-keyboard) enables developers to define a custom Key Definition File in order to configure the key layout. In the Key Definition File, the developer specifies the keys in each section and row of the keyboard. The keys support the characters in the Basic Latin, Latin 1 Supplement, Latin Extended-A, and Latin Extended-B blocks. This provides support for most Western European languages, including English, French, German, Italian, Portuguese, and Spanish. + +- The [**VoiceTextEditBox**](doc:voice-text-edit-box) displays the text that has been entered or spoken. This node supports multiple voice entry modes for entering email addresses, passwords, street addresses, and PINs. This node currently supports voice entry in English and Spanish. + +> Developers should upgrade the [legacy keyboards](doc:keyboard) in their apps to dynamic voice-enabled keyboards in order to leverage the following benefits: +> +> - **Faster on-device sign-ups and sign-ins.** Enable customers to use voice entry to provide their information when subscribing to apps and logging in. +> +> - **Localized in-app search**: Enable customers to search for content in their native language. +> +> - **Localized customer information entry**: Enable customers to enter their personal information in their native language. + +## Fields + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDefaultAccess PermissionDescription
textstring""READ_WRITEContains the string of characters that has been entered. The text written to this field may also be displayed in the VoiceTextEditBox.
textEditBox[VoiceTextEditBox node](doc:voice-text-edit-box)The VoiceTextEditBox associated with the keyboardREADThe internal [VoiceTextEditBox node](doc:voice-text-edit-box) used by this DynamicKeyboardBase node.

Do not set this field to null or to a different VoiceTextEditBox node; this field should be used only to access the fields of this node's internal VoiceTextEditBox node.
hideTextBoxbooleanfalseREAD_WRITEHides the keyboard's internal VoiceTextEditBox, and renders the keyboard's DynamicKeyGrid at the top of the node.
keyGrid[DynamicKeyGrid node](doc:dynamic-key-grid)The DynamicKeyGrid associated with the keyboardREADThe internal [DynamicKeyGrid node](doc:dynamic-key-grid) used by this DynamicKeyboardBase node.

Do not set this field to null or to a different DynamicKeyGrid node; this field should be only used to access the fields of this node's internal DynamicKeyGrid node, such as the mode or horizWrapping fields.
domainstring"generic"READ_WRITE + The keyboard mode, which may be one of the following: +
    +
  • "email": letter-by-letter dictation for emails.
    • +
  • "numeric": letter-by-letter dictation for PIN codes, zip codes, and other numeric input.
    • +
  • "alphanumeric": letter-by-letter dictation for street addresses or other sequences of numbers and letters.
    • +
  • "generic": Full word input for search queries or other sequences of numbers, letters and symbols.
    • +
  • "password": letter-by-letter dictation for passwords.
    • +
+ The domain may be used to: +
    +
  • Set options for the speech recognition system.
    • +
  • Identify when a complete string has been entered (for example, an email address).
    • +
  • Specify whether the entered string is displayed as a single string or a discrete sequence of characters (for example, a PIN code).
    • +
  • Enable key suggestions (for example, a pop-up for the ampersand key (&) to provide common email choices).
    • +
+
+ +## UX recommendations + +1. Do not show hint text in the [VoiceTextEditBox](doc:voice-text-edit-box). +2. Display secondary text under the title. +3. Show the horizontal blinking cursor when the focus is on the [VoiceTextEditBox](doc:voice-text-edit-box) and vertical blinking cursor when the focus is on the keyboard buttons. + +![roku815px - email-keyboard](https://image.roku.com/ZHZscHItMTc2/email-keyboard.png) + +![roku815px - email-keyboard](https://image.roku.com/ZHZscHItMTc2/email-keyboard-2.png) + +## Sample app + +You can download and install a [sample app](https://github.com/rokudev/dynamic-voice-enabled-keyboards) that demonstrates how to create and configure dynamic voice-enabled keyboards. The sample app includes a voice-enabled keyboard, PIN pad, mini-keyboard, and custom keyboard (an address keyboard form). diff --git a/docs/REFERENCES/scenegraph/dynamic-voice-keyboard-nodes/index.md b/docs/REFERENCES/scenegraph/dynamic-voice-keyboard-nodes/index.md index 9740257e..eb968ffa 100644 --- a/docs/REFERENCES/scenegraph/dynamic-voice-keyboard-nodes/index.md +++ b/docs/REFERENCES/scenegraph/dynamic-voice-keyboard-nodes/index.md @@ -1,103 +1,51 @@ --- title: "Dynamic voice keyboard nodes" -excerpt: 'Abstract class for dynamic voice-enabled keyboard nodes' +excerpt: 'SceneGraph nodes for text and voice entry: DynamicKeyboard, DynamicPinPad, DynamicMiniKeyboard, DynamicCustomKeyboard, and the components that back them' deprecated: false hidden: false metadata: title: 'Dynamic voice keyboard nodes' - description: 'Documents the DynamicKeyboardBase abstract class, which combines DynamicKeyGrid and VoiceTextEditBox nodes for text and voice entry.' + description: 'Dynamic voice keyboard nodes provide text and voice entry in your SceneGraph apps, supporting email, PIN, password, and free-form input. This page covers the four keyboard variants and the underlying components they share.' robots: index next: description: '' --- +Dynamic voice keyboard nodes let you collect text from the user with both on-screen typing and voice entry. They support email addresses, PIN codes, passwords, and free-form text. +> Apps must use these keyboards for [email](doc:dynamic-keyboard), [PIN](doc:dynamic-pinpad), and [password](doc:dynamic-keyboard) entry to pass [certification](doc:certification). -Extends [**Group**](doc:group) +![DynamicKeyboard with voice prompt](https://image.roku.com/ZHZscHItMTc2/dynamic-keyboard-voice.jpg "DynamicKeyboard") -> Apps must use Roku voice keyboards for [email](doc:dynamic-keyboard), [PIN](doc:dynamic-pinpad), [password](doc:dynamic-keyboard) entry to pass [certification](doc:certification). +## Choosing a node -The DynamicKeyboardBase is an abstract class that provides the functionality for dynamic voice-enabled keyboards. It combines [**DynamicKeyGrid**](doc:dynamic-key-grid) and [**VoiceTextEditBox**](doc:voice-text-edit-box) nodes to provide a single node that supports text entry in multiple languages and voice entry in English and Spanish. +| Node | Use case | +| :--- | :--- | +| [DynamicKeyboard](doc:dynamic-keyboard) | A full alphanumeric keyboard for general text entry, email addresses, and passwords. | +| [DynamicPinPad](doc:dynamic-pinpad) | A numeric pin pad for PIN codes, zip codes, and similar short numeric input. | +| [DynamicMiniKeyboard](doc:dynamic-mini-keyboard) | A compact keyboard variant for tighter UI surfaces. | +| [DynamicCustomKeyboard](doc:dynamic-custom-keyboard) | A keyboard whose key layout you define in a custom Key Definition File. | -- The [**DynamicKeyGrid**](doc:dynamic-key-grid) provides keyboard functionality. The layout of the keyboard is based on a JSON-formatted Key Definition File. +The four keyboard nodes share these underlying components: - The classes derived from DynamicKeyboardBase (DynamicKeyboard, DynamicPinPad, and DynamicMiniKeyboard) have built-in Key Definition Files. For example, the DynamicKeyboard node uses a Key Definition File that matches the key layout of the [legacy Keyboard node](doc:keyboard). +| Component | Role | +| :--- | :--- | +| [DynamicKeyGrid](doc:dynamic-key-grid) | The grid of keys rendered inside each keyboard, laid out from a JSON Key Definition File. | +| [VoiceTextEditBox](doc:voice-text-edit-box) | The text-display box that shows the entered or spoken text above the key grid. | +| [Key Definition File](doc:key-definition-file) | The JSON file format that describes the keyboard layout used by DynamicKeyGrid. | - The [**DynamicCustomKeyboard** node](doc:dynamic-custom-keyboard) enables developers to define a custom Key Definition File in order to configure the key layout. In the Key Definition File, the developer specifies the keys in each section and row of the keyboard. The keys support the characters in the Basic Latin, Latin 1 Supplement, Latin Extended-A, and Latin Extended-B blocks. This provides support for most Western European languages, including English, French, German, Italian, Portuguese, and Spanish. +## Inheritance +DynamicKeyboard, DynamicPinPad, DynamicMiniKeyboard, and DynamicCustomKeyboard all extend [**DynamicKeyboardBase**](doc:dynamic-keyboard-base), an abstract base class that combines a DynamicKeyGrid and a VoiceTextEditBox into a single node. Most of the field reference for the four keyboard variants (`text`, `textEditBox`, `keyGrid`, `domain`, `hideTextBox`) is documented on the DynamicKeyboardBase page rather than repeated on each subclass. -- The [**VoiceTextEditBox**](doc:voice-text-edit-box) displays the text that has been entered or spoken. This node supports multiple voice entry modes for entering email addresses, passwords, street addresses, and PINs. This node currently supports voice entry in English and Spanish. +## Voice entry -> Developers should upgrade the [legacy keyboards](doc:keyboard) in their apps to dynamic voice-enabled keyboards in order to leverage the following benefits: -> -> - **Faster on-device sign-ups and sign-ins.** Enable customers to use voice entry to provide their information when subscribing to apps and logging in. -> -> - **Localized in-app search**: Enable customers to search for content in their native language. -> -> - **Localized customer information entry**: Enable customers to enter their personal information in their native language. +Voice entry currently supports English and Spanish. The `domain` field on DynamicKeyboardBase (and therefore on every subclass) controls the speech-recognition mode: `email`, `numeric`, `alphanumeric`, `generic`, or `password`. See the [DynamicKeyboardBase fields](doc:dynamic-keyboard-base#fields) for details. -## Fields +## Looking for something else? - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDefaultAccess PermissionDescription
textstring""READ_WRITEContains the string of characters that has been entered. The text written to this field may also be displayed in the VoiceTextEditBox.
textEditBox[VoiceTextEditBox node](doc:voice-text-edit-box)The VoiceTextEditBox associated with the keyboardREADThe internal [VoiceTextEditBox node](doc:voice-text-edit-box) used by this DynamicKeyboardBase node.

Do not set this field to null or to a different VoiceTextEditBox node; this field should be used only to access the fields of this node's internal VoiceTextEditBox node.
hideTextBoxbooleanfalseREAD_WRITEHides the keyboard's internal VoiceTextEditBox, and renders the keyboard's DynamicKeyGrid at the top of the node.
keyGrid[DynamicKeyGrid node](doc:dynamic-key-grid)The DynamicKeyGrid associated with the keyboardREADThe internal [DynamicKeyGrid node](doc:dynamic-key-grid) used by this DynamicKeyboardBase node.

Do not set this field to null or to a different DynamicKeyGrid node; this field should be only used to access the fields of this node's internal DynamicKeyGrid node, such as the mode or horizWrapping fields.
domainstring"generic"READ_WRITEThe keyboard mode, which may be one of the following:
  • "email": letter-by-letter dictation for emails.
  • "numeric": letter-by-letter dictation for PIN codes, zip codes, and other numeric input.
  • "alphanumeric": letter-by-letter dication for street addresses or other sequences of numbers and letters.
  • "generic": Full word input for search queries or other sequences of numbers, letters and symbols.
  • "password": letter-by-letter dication for passwords.

The domain may be used to:
  • Set options for the speech recognition system.
  • Identify when a complete string has been entered (for example, an email address).
  • Specify whether the entered string is displayed as a single string or a discrete sequence of characters (for example, a PIN code).
  • Enable key suggestions (for example, a pop-up for the ampersand key (&) to provide common email choices).
- - -## UX recommendations - -1. Do not show hint text in the [VoiceTextEditBox](doc:voice-text-edit-box). -2. Display secondary text under the title. -3. Show the horizontal blinking cursor when the focus is on the [VoiceTextEditBox](doc:voice-text-edit-box) and vertical blinking cursor when the focus is on the keyboard buttons. - -![roku815px - email-keyboard](https://image.roku.com/ZHZscHItMTc2/email-keyboard.png) - -![roku815px - email-keyboard](https://image.roku.com/ZHZscHItMTc2/email-keyboard-2.png) +* **Migrating from the legacy keyboards?** Replace [Keyboard](doc:keyboard), [PinPad](doc:minikeyboard), and similar legacy nodes with their dynamic voice-enabled counterparts above to gain voice entry and broader language support. +* **Building a dialog with an embedded keyboard or pin pad?** The [Standard dialog framework](doc:standard-dialog-framework-nodes) provides [StandardKeyboardDialog](doc:standard-keyboard-dialog) and [StandardPinPadDialog](doc:standard-pinpad-dialog), pre-built modal dialogs that wrap these keyboards with a title, buttons, and consistent chrome. ## Sample app -You can download and install a [sample app](https://github.com/rokudev/dynamic-voice-enabled-keyboards) that demonstrates how to create and configure dynamic voice-enabled keyboards. The sample app includes a voice-enabled keyboard, PIN pad, mini-keyboard, and custom keyboard (an address keyboard form). +A [voice-enabled keyboard sample app](https://github.com/rokudev/dynamic-voice-enabled-keyboards) demonstrates how to create and configure each of the four keyboard variants, including a custom address keyboard built from a Key Definition File.