Merge pull request #1220 from telerik/didi/speachtotext

add initial articles for speechtotext button.

Author: didiyordanova

_config.yml

@@ -500,6 +500,10 @@ navigation:
         position: 15
     ## End SlideView Sub-Folders
     ##End SlideView
+    ## SpeechToTextButton
+    controls/speechtotextbutton:
+        title: "SpeechToTextButton"
+    ## End SpeechToTextButton
     ## SpreadProcessing
     controls/spreadprocessing:
         title: "SpreadProcessing"
@@ -751,6 +755,7 @@ intro_columns:
         "Segmented Control": "segmentedcontrol-overview"
         "Button": "button-overview"
         "CheckBox": "checkbox-overview"
+        "SpeechToTextButton": "speechtotextbutton-overview"
         "TemplatedButton": "templatedbutton-overview"
         "ToggleButton": "togglebutton-overview"
 -

_contentTemplates/get-started.md

@@ -37,6 +37,7 @@ To visualize the Telerik controls, register them in the `MauiProgram.cs` file of
 	.UseTelerik()
 	<!-- Code omitted for brevity -->
 	```
+
 #end
 
 #add-telerik-component

controls/bottomsheet/getting-started.md

@@ -18,11 +18,11 @@ At the end, you will achieve the following result.
 
 Before adding the BottomSheet, you need to:
 
-1. [Set up your .NET MAUI application]({%slug maui-getting-started %}#step-1-set-up-your-net-maui-application).
+1. [Set up your .NET MAUI application]({%slug maui-getting-started%}#prerequisites).
 
-1. [Download Telerik UI for .NET MAUI]({% slug maui-getting-started %}#step-2-download-telerik-ui-for-net-maui).
+1. [Download Telerik UI for .NET MAUI]({% slug maui-getting-started%}#step-0-start-your-free-trial).
 
-1. [Install Telerik UI for .NET MAUI]({%slug maui-getting-started %}#step-3-install-telerik-ui-for-net-maui).
+1. [Install Telerik UI for .NET MAUI]({%slug maui-getting-started%}#step-3-add-the-telerik-nuGet-server).
 
 ## Define the Control
 

controls/speechtotextbutton/commands.md

@@ -0,0 +1,44 @@
+---
+title: Commands
+page_title: .NET MAUI SpeechToTextButton Documentation - Commands
+description: Use the exposed commands of the Telerik UI for .NET MAUI SpeechToTextButton
+position: 9
+tags: .net maui, telerik speech to text button for .net maui, ui for .net maui, microsoft .net maui
+slug: speechtotextbutton-commands
+---
+
+# .NET MAUI SpeechToTextButton Commands
+
+The .NET MAUI SpeechToTextButton provides commands that execute when specific actions occur, such as when speech is recognized or when an error occurs. This allows you to handle these events in a more MVVM-friendly way.
+
+The .NET MAUI SpeechToTextButton exposes the following commands:
+
+* `SpeechRecognizedCommand` (`ICommand`)—Specifies a command to execute when the speech recognition is successful and the recognized text is available. The command context is `SpeechToTextButtonSpeechRecognizedCommandContext`, which contains the recognized text—`FullText` and confidence score—`FullTextConfidenceScore`.
+* `ErrorOccurredCommand` (`ICommand`)—Specifies a command to execute when an error occurs during the speech recognition process. The command context is `SpeechToTextButtonErrorOccurredCommandContext`, which contains the error message—`Message` and the exception—`Exception`.
+
+## Example
+
+Here is an example using the `SpeechRecognizedCommand` and `ErrorOccurredCommand`:
+
+**1.** Define the `SpeechToTextButton` in XAML:
+
+<snippet id='speechtotext-commands' />
+
+**2.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+
+**3.** Define the `ViewModel` with `SpeechRecognizedCommand` and `ErrorOccurredCommand` definitions:
+
+<snippet id='speechtotext-commands-viewmodel' />
+
+> For a runnable example with the SpeechToTextButton Commands scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to the **SpeechToTextButton > Features** category.
+
+## See Also
+
+- [Set Visual States]({%slug speechtotextbutton-visual-states%})
+- [Events]({%slug speechtotextbutton-events%})
+- [Custom Recognizer]({%slug speechtotextbutton-custom-recognizer%})
+- [Style the SpeechToTextButton]({%slug speechtotextbutton-styling%})

controls/speechtotextbutton/configuration.md

@@ -0,0 +1,53 @@
+---
+title: Configuration
+page_title: .NET MAUI SpeechToTextButton Documentation - Configuration
+description: Learn how to define language, get the text from the speech to text recognizer when using the Telerik SpeechToTextButton for .NET MAUI.
+position: 5
+tags: .net maui, telerik speech to text button for .net maui, ui for .net maui, microsoft .net maui
+slug: speechtotextbutton-configuration
+---
+
+# .NET MAUI SpeechToTextButton Configuration
+
+The purpose of this help article is to show you the main configuration options of the control.
+
+## Getting Full Text from Speech Recognition
+
+The SpeechToTextButton allows you to retrieve the full text recognized by the speech recognition service. 
+This is done through the `FullText` property, which provides the complete transcription of the spoken input from the beginning of the current listening session.
+
+To get the full text, you can subscribe to the `SpeechRecognized` event, which is triggered when the speech recognition is successful.
+
+## Continuous Recognition
+
+The SpeechToTextButton supports continuous speech recognition, allowing it to listen for speech input without stopping after each recognition.
+
+You can disable the continuous recognition by setting the `IsContinuousRecognition` property to `false`. The default value is `true`, meaning that the button will listen for speech input continuously, until it is explicitly stopped or the user taps the button again.
+
+```XAML
+<telerik:RadSpeechToTextButton x:Name="speechContinuousButton"
+							   IsContinuousRecognition="False" />
+```
+
+## Language
+
+The SpeechToTextButton allows you to set the language for speech recognition. This is important for accurate transcription of spoken words into text. 
+
+You can set the language using the `LanguageTag` property, which accepts a string representing the language code (e.g., "en-US" for English, "fr-FR" for French).
+
+<snippet id='speechtotext-language-tag' />
+
+### Language Support
+
+The SpeechToTextButton supports a variety of languages for speech recognition. The available languages depend on the underlying platform and the speech recognition service used.
+
+Check the following articles for more information on supported languages: [SpeechToTextButton Language Support in .NET MAUI]({%slug speechtotextbutton-language-support%})
+
+
+> For a runnable example with the SpeechToTextButton Configuration scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to the **SpeechToTextButton > Features** category.
+
+## See Also
+
+- [Set Visual States]({%slug speechtotextbutton-visual-states%})
+- [Execute Commands]({%slug speechtotextbutton-commands%})
+- [Style the SpeechToTextButton]({%slug speechtotextbutton-styling%})

controls/speechtotextbutton/custom-recognizer.md

@@ -0,0 +1,46 @@
+---
+title: Custom Recognizer
+page_title: .NET MAUI SpeechToTextButton Documentation - Custom Recognizer
+description: Learn how to use a custom speech recognizer with the Telerik SpeechToTextButton for .NET MAUI.
+position: 6
+tags: .net maui, telerik speech to text button for .net maui, ui for .net maui, custom recognizer, microsoft .net maui
+slug: speechtotextbutton-custom-recognizer
+---
+
+# .NET MAUI SpeechToTextButton Custom Recognizer
+
+The .NET MAUI SpeechToTextButton allows you to use a custom speech recognizer by implementing the `IRadSpeechRecognizer` interface. This enables you to integrate third-party speech recognition services or customize the behavior of the speech recognition process.
+
+## Implementation Steps
+
+Follow these steps to implement a custom speech recognizer:
+
+**1.** Define the `SpeechToTextButton` in XAML:
+
+<snippet id='speechtotext-custom-recognizer' />
+
+**2.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+
+**3.** Create a class `MyCustomSpeechRecognizer` that implements the `IRadSpeechRecognizer` interface:
+
+<snippet id='speechtotext-mycustomrecognizer' />
+
+**4.** Set the `SpeechRecognizerCreator` property of the `RadSpeechToTextButton` to an instance of your custom recognizer:
+
+<snippet id='speechtotext-speech-recognizer-creator' />
+
+**5.** Handle the `SpeechRecognized` event to process the recognition results:
+
+<snippet id='speechtotext-events-speech-recognized' />
+
+> For a runnable example with the SpeechToTextButton Custom Recognizer scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to the **SpeechToTextButton > Features** category.
+
+## See Also
+
+- [Set Visual States]({%slug speechtotextbutton-visual-states%})
+- [Events]({%slug speechtotextbutton-events%})
+- [Style the SpeechToTextButton]({%slug speechtotextbutton-styling%})

controls/speechtotextbutton/events.md

@@ -0,0 +1,62 @@
+---
+title: Events
+page_title: .NET MAUI SpeechToTextButton Documentation - Events
+description: Learn about the events that the SpeechToTextButton for .NET MAUI exposes.
+position: 8
+tags: .net maui, telerik speech to text button for .net maui, ui for .net maui
+slug: speechtotextbutton-events
+---
+
+# .NET MAUI SpeechToTextButton Events
+
+The .NET MAUI SpeechToTextButton emits a set of events that allow you to configure the component's behavior in response to speech recognition.
+
+The .NET MAUI SpeechToTextButton exposes the following events:
+
+* `SpeechRecognized`—Raised when the speech recognition is successful and the recognized text is available. The `SpeechRecognized` event handler receives two parameters:
+	* The `sender` argument which is of type `object` but can be cast to `RadSpeechToTextButton`.
+	* A `SpeechRecognizerSpeechRecognizedEventArgs` argument which has a reference to the:
+		* `FullText` (`string`) property that contains the current full text recognized from the speech input from the beginning of the current listening session.
+		* `FullTextConfidenceScore` property that indicates the confidence level of the recognition. The value is between 0 and 1, indicating how confident the speech-to-text transcription is. If the value is -1, a confidence score could not be provided.
+
+* `ErrorOccurred`—Raised when an error occurs during the speech recognition process. The `ErrorOccurred` event handler receives two parameters:
+	* The `sender` argument which is of type `object` but can be cast to `RadSpeechToTextButton`.
+	* A `SpeechRecognizerErrorOccurredEventArgs` argument which has a reference to the:
+		* `Message` (`string`) property that contains the error message describing the issue that occurred during speech recognition.
+		* `Exception` (`System.Exception`) property that contains the exception associated with the speech recognizer error, if any.
+		* `Handled` (`bool`) property that determines whether the error has been handled. Set this to `true` to prevent the default error handling behavior.
+
+* `StateChanged`—Raised when the state of the speech recognizer changes. The `StateChanged` event handler receives two parameters:
+	* The `sender` argument which is of type `object` but can be cast to `RadSpeechToTextButton`.
+	* An `System.EventArgs`.
+
+## Example
+
+Here is an example using the `SpeechRecognized` and `ErrorOccurred` events:
+
+**1.** Define the `SpeechToTextButton` in XAML:
+
+<snippet id='speechtotext-events' />
+
+**2.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+
+**3.** Handle the `SpeechRecognized` event:
+
+<snippet id='speechtotext-events-speech-recognized' />
+
+**4.** Handle the `ErrorOccurred` event:
+
+<snippet id='speechtotext-events-error-occured' />
+
+> For a runnable example with the SpeechToTextButton Events scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to the **SpeechToTextButton > Features** category.
+
+## See Also
+
+- [Set Visual States]({%slug speechtotextbutton-visual-states%})
+- [Custom Recognizer]({%slug speechtotextbutton-custom-recognizer%})
+- [Execute Commands]({%slug speechtotextbutton-commands%})
+- [Style the SpeechToTextButton]({%slug speechtotextbutton-styling%})

controls/speechtotextbutton/getting-started.md

@@ -0,0 +1,108 @@
+---
+title: Getting Started
+page_title: .NET MAUI SpeechToTextButton Documentation - Getting Started
+description: Get started with the Telerik UI for .NET MAUI SpeechToTextButton control and add the control to your .NET MAUI project.
+position: 2
+slug: speechtotextbutton-getting-started
+---
+
+# Getting Started with the .NET MAUI SpeechToTextButton
+
+This guide provides the information you need to start using the Telerik UI for .NET MAUI SpeechToTextButton by adding the control to your project.
+
+At the end, you will achieve the following result.
+
+![.NET MAUI SpeechToTextButton Getting Started](images/speechtotextbutton-getting-started.png)
+
+## Prerequisites
+
+Before adding the SpeechToTextButton, you need to:
+
+1. [Set up your .NET MAUI application]({%slug maui-getting-started%}#prerequisites).
+
+1. [Download Telerik UI for .NET MAUI]({% slug maui-getting-started%}#step-0-start-your-free-trial).
+
+1. [Install Telerik UI for .NET MAUI]({%slug maui-getting-started%}#step-3-add-the-telerik-nuGet-server).
+
+## Required Permissions
+
+Before adding the contol, ensure that you have the required permissions set up in your project.
+
+### Android
+
+Add the following permissions to your `AndroidManifest.xml` file:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+```
+
+### iOS and MacCatalyst
+
+Add the `NSMicrophoneUsageDescription` and `NSSpeechRecognitionUsageDescription` permissions to your `Info.plist` file:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>The SpeechToTextButton requires access to microphone.</string>
+<key>NSSpeechRecognitionUsageDescription</key>
+<string>The SpeechToTextButton requires access to the Speech Recognition service.</string>
+```
+
+### WinUI
+
+There are limitations when using the SpeechToTextButton on WinUI. When clicking on the control, the `InvalidOperationException` occurs.
+
+To turn speech recognition on WinUI, review the [WinUI Support]({%slug speechtotextbutton-winui-support%}) article.
+
+## Define the Control
+
+**1.** When your .NET MAUI application is set up, you are ready to add a SpeechToTextButton control to your page:
+
+<snippet id='speechtotext-getting-started-xaml' />
+<snippet id='speechtotext-getting-started-csharp' />
+
+**2.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+```C#
+using Telerik.Maui.Controls;
+```
+
+**3.** Register the Telerik controls through the `Telerik.Maui.Controls.Compatibility.UseTelerik` extension method called inside the `CreateMauiApp` method of the `MauiProgram.cs` file of your project:
+
+```C#
+using Telerik.Maui.Controls.Compatibility;
+public static class MauiProgram
+{
+	public static MauiApp CreateMauiApp()
+	{
+		var builder = MauiApp.CreateBuilder();
+		builder
+			.UseTelerik()
+			.UseMauiApp<App>()
+			.ConfigureFonts(fonts =>
+			{
+				fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
+			});
+		return builder.Build();
+	}
+}           
+```
+
+> For a runnable example with the SpeechToTextButton Getting Started scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to the **SpeechToTextButton > Getting Started** category.
+
+## Additional Resources
+
+- [Configure the SpeechToTextButton]({%slug speechtotextbutton-configuration%})
+- [Set Visual States]({%slug speechtotextbutton-visual-states%})
+- [Events]({%slug speechtotextbutton-events%})
+- [Execute Commands]({%slug speechtotextbutton-commands%})
+- [Style the SpeechToTextButton]({%slug speechtotextbutton-styling%})
+
+## See Also
+
+- [.NET MAUI SpeechToTextButton Product Page](https://www.telerik.com/maui-ui/speechtotextbutton)
+- [.NET MAUI SpeechToTextButton Forum Page](https://www.telerik.com/forums/maui?tagId=1764)
+- [Telerik .NET MAUI Blogs](https://www.telerik.com/blogs/mobile-net-maui)
+- [Telerik .NET MAUI Roadmap](https://www.telerik.com/support/whats-new/maui-ui/roadmap)