Commands
RadRichTextBox exposes a full set of commands that provide an alternative to its API methods, exposed through its Commands property. For each of the Formatting API methods there is a respective command.
Binding Commands to UI Elements
In order to use the command with a UI Element that supports commanding, you have to bind the Command property of the element to the respective command of the RadRichTextBox.
To see a list of all the commands exposed by RadRichTextBox, visit this topic.
Here is an example with a RadToggleButtonControl.
Example 1: Binding a command
<telerik:RadToggleButton x:Name="BoldButton"
Content="Bold"
DataContext="{Binding Commands, ElementName=radRichTextBox}"
Command="{Binding ToggleBoldCommand}" />
<telerik:RadRichTextBox x:Name="radRichTextBox"
Height="500"
Width="500">
<telerik:RadDocument LayoutMode="Paged" />
</telerik:RadRichTextBox>
Now when the button is clicked, it will toggle the boldness of the current selection. The thing it won't do is to respond to the current state of the selection. For example, if the context of the caret is a bold text, the button in the UI won't get automatically toggled. In order to implement this behavior, you have to handle the ToggleStateChanged event of the ToggleBoldCommand following an approach similar to the one shown in Example 2.
Example 2: Update toggle button state using the ToggleStateChanged event of ToggleBoldCommand
public CommandsSample()
{
InitializeComponent();
this.radRichTextBox.Commands.ToggleBoldCommand.ToggleStateChanged += this.ToggleBoldCommand_ToggleStateChanged;
}
public void ToggleBoldCommand_ToggleStateChanged( object sender, StylePropertyChangedEventArgs<bool> e )
{
this.BoldButton.IsChecked = e.NewValue;
}
Public Sub New()
InitializeComponent()
Me.radRichTextBox.Commands.ToggleBoldCommand.ToggleStateChanged += Me.ToggleBoldCommand_ToggleStateChanged
End Sub
Public Sub ToggleBoldCommand_ToggleStateChanged(sender As Object, e As StylePropertyChangedEventArgs(Of Boolean))
Me.BoldButton.IsChecked = e.NewValue
End Sub
Now the button will respond to the current state of the selection.
You can also use the functionality provided by the RadRichTextBoxRibbonUI class in order to get the event handling out of the box.
The RadRichTextBoxRibbonUI provides you with a fully predefined UI for RadRichTextBox. To learn how to use it read this topic.
If you are building your UI manually, for example using a RadRibbonView control, you have to only bind the command to the RadRichTextBoxRibbonUI.RichTextCommand attached property of the desired RadRibbonView control. Here is an example with a RadRibbonToggleButton.
Example 3: Bind a command to a RadRibbonView control
<telerik:RadRibbonToggleButton x:Name="ItalicButton"
Content="Italic"
DataContext="{Binding Commands, ElementName=radRichTextBox}"
telerik:RadRichTextBoxRibbonUI.RichTextCommand="{Binding ToggleItalicCommand}" />
The RadRibbonToggleButton will get automatically toggled whenever the context of the caret is an italic text.
More about the specific buttons introduced with RadRibbonView you can find here.
Modifying Default Application Commands Bindings
By default, RadRichTextBox defines built-in mappings between ApplicationCommands and its Commands:
| Application Command | RadRichTextBox Command |
|---|---|
| ApplicationCommands.Cut | CutCommand |
| ApplicationCommands.Copy | CopyCommand |
| ApplicationCommands.Paste | PasteCommand |
| ApplicationCommands.Delete | DeleteCommand |
| ApplicationCommands.Find | ShowFindReplaceDialogCommand |
| ApplicationCommands.New | NewDocumentCommand |
| ApplicationCommands.Open | OpenDocumentCommand |
| ApplicationCommands.Save | SaveCommand |
| ApplicationCommands.SelectAll | SelectAllCommand |
| ApplicationCommands.Undo | UndoCommand |
| ApplicationCommands.Redo | RedoCommand |
| ApplicationCommands.Print | PrintCommand |
You can remove some of the bindings by using RadRichTextBox.RegisteredApplicationCommands collection.
Example 4: Remove ApplicationCommands bindings
this.radRichTextBox.RegisteredApplicationCommands.Remove(ApplicationCommands.Save);
Me.radRichTextBox.RegisteredApplicationCommands.Remove(ApplicationCommands.Save)
and re-add them (as long as they are among the default mappings list) at later time:
Example 5: Add ApplicationCommands bindings
this.radRichTextBox.RegisteredApplicationCommands.Add(ApplicationCommands.Save);
Me.radRichTextBox.RegisteredApplicationCommands.Add(ApplicationCommands.Save)
If you want to handle application commands on RadRichTextBox owner's level, you should suppress the default handling mechanism for the specified shortcut using RadRichTextBox.PreviewEditorKeyDown event:
Example 6: Suppress default action for application command
this.radRichTextBox.PreviewEditorKeyDown += (sender, e) =>
{
if (Keyboard.IsKeyDown(Key.LeftCtrl) && e.Key == Key.S)
{
e.SuppressDefaultAction = true;
}
};
Me.radRichTextBox.PreviewEditorKeyDown += Function(sender, e) Do
If Keyboard.IsKeyDown(Key.LeftCtrl) AndAlso e.Key = Key.S Then
e.SuppressDefaultAction = True
End If
End Function
Command-related Events
RadRichTextBox exposes two events that allow you interfere the process of executing a command.
Example 7: Subscribing to the events
this.radRichTextBox.CommandExecuting += RadRichTextBox_CommandExecuting;
this.radRichTextBox.CommandExecuted += RadRichTextBox_CommandExecuted;
this.radRichTextBox.CommandError += RadRichTextBox_CommandError;
AddHandler Me.radRichTextBox.CommandExecuting, AddressOf radRichTextBox_CommandExecuting
AddHandler Me.radRichTextBox.CommandExecuted, AddressOf RadRichTextBox_CommandExecuted
AddHandler Me.radRichTextBox.CommandError, AddressOf RadRichTextBox_CommandError
You can find a runnable example demonstrating how to use the CommandExecuting and CommandExecuted events to customize the behavior of a command in our SDK repository on GitHub.
CommandExecuting
The CommandExecuting event fires just before the execution of a command. You can use it to stop the command or modify its behavior/parameter. The parameters the event enables you to use are of type CommandExecutingEventArgs and can give you information about the command the event is fired for and its parameter.
An example usage of this event is when you need to modify the content that is pasted into the document. In this case, you can easily obtain the content in the clipboard and change it according to your needs just before executing the PasteCommand.
Example 8: Handling CommandExecuting
void radRichTextBox_CommandExecuting(object sender, Telerik.Windows.Documents.RichTextBoxCommands.CommandExecutingEventArgs e)
{
if (e.Command is PasteCommand)
{
// Process the text
}
}
Private Sub radRichTextBox_CommandExecuting(sender As Object, e As Telerik.Windows.Documents.RichTextBoxCommands.CommandExecutingEventArgs)
If (TypeOf (e.Command) Is PasteCommand) Then
'Process the text
End If
End Sub
Example 9: Canceling CommandExecuting
void radRichTextBox_CommandExecuting1(object sender, Telerik.Windows.Documents.RichTextBoxCommands.CommandExecutingEventArgs e)
{
if (e.Command is PasteCommand)
{
e.Cancel = true;
}
}
Private Sub RadRichTextBox_CommandExecuting1(sender As Object, e As Telerik.Windows.Documents.RichTextBoxCommands.CommandExecutingEventArgs)
If (TypeOf (e.Command) Is PasteCommand) Then
e.Cancel = True
End If
End Sub
You can combine the code from Examples 8 and 9 so you can stop the default execution of a command and perform your own logic.
CommandExecuted
The CommandExecuted event fires after the execution of a command. You can use it to stop the command or modify its behavior/parameter. The parameters the event enables you to use are of type CommandExecutedEventArgs and can give you information about the command the event is fired for. It is useful when you need to add an additional logic that should be executed after a particular command.
Example 10 demonstrates how you can modify each image after its insertion into the document to ensure it is not wider than the maximum width defined.
Example 10: Using CommandExecuted
private void RadRichTextBox_CommandExecuted(object sender, CommandExecutedEventArgs e)
{
if (e.Command is InsertPictureCommand)
{
// After inserting an image, ensure that its width is not more than 200px.
double maxWidth = 200;
foreach (var image in this.radRichTextBox.Document.EnumerateChildrenOfType<ImageInline>())
{
double ratio = image.Height / image.Width;
this.radRichTextBox.ChangeImageSize(image, new Size(maxWidth, maxWidth * ratio));
}
}
}
Private Sub RadRichTextBox_CommandExecuted(sender As Object, e As CommandExecutedEventArgs)
If (TypeOf (e.Command) Is InsertPictureCommand) Then
'After inserting an image, ensure that its width Is Not more than 200px.
Dim maxWidth As Double = 200
For Each image In Me.radRichTextBox.Document.EnumerateChildrenOfType(Of ImageInline)
Dim ratio = image.Height / image.Width
Me.radRichTextBox.ChangeImageSize(image, New Size(maxWidth, maxWidth * ratio))
Next
End If
End Sub
CommandError
This event fires when a command fails to execute its operation. It is useful to handle issues that might occur and collect more information about them. The parameters of this event give you information about the error and enable you to set it as handled.
Example 11: Using CommandError
private void RadRichTextBox_CommandError(object sender, CommandErrorEventArgs e)
{
// Log the error
e.Handled = true;
}
Private Sub RadRichTextBox_CommandError(sender As Object, e As CommandErrorEventArgs)
'Log the error
e.Handled = True
End Sub