wpf-9108-controls-and-libraries-rich-text-editor-commands.md
The Rich Text Editor for WPF ships with a comprehensive set of commands that allows you to perform basic operations (format and edit text, create lists, add headers and footers, work with tables, etc.). All commands implemented in the Rich Text Editor control inherit from the Command object. Refer to a following topic for a full list of built-in commands: Command UI in Rich Text Editor for WPF
You can create a new object of the required Command descendant to create a new command. You can also call the RichEditControl.CreateCommand method and pass the required RichEditCommandId enumeration member as a parameter to create a command.
The Command class has the following methods used to execute the command action:
Command.ExecuteThe main method. Cannot be utilized when the command is disabled (use the Command.CanExecute() to determine whether the command can be executed).Command.ForceExecuteUse this method if the command is disabled or if you require to execute the command with a parameter (for example, navigate to a page by its number). The ICommandUIState.EditValue property allows you to specify a command parameter.
The following code calls the RichEditControl.CreateCommand method to create commands based on CapitalizeEachWordTextCase, ToggleFontBold, ChangeFontBackColor, and PrintPreview commands. Each command is executed by the ForceExecute method call. The Command.CreateDefaultCommandUIState() method returns the command UI state.
All commands are executed an once on a button click.
static void buttonCustomAction_ItemClick_Commands(object sender, ItemClickEventArgs e) {
RichEditControl richEdit = e.Item.Tag as RichEditControl;
richEdit.SelectAll();
RichEditCommand capCommand = richEdit.CreateCommand(RichEditCommandId.CapitalizeEachWordTextCase);
capCommand.ForceExecute(capCommand.CreateDefaultCommandUIState());
RichEditCommand boldCommand = richEdit.CreateCommand(RichEditCommandId.ToggleFontBold);
boldCommand.ForceExecute(boldCommand.CreateDefaultCommandUIState());
RichEditCommand changeFontColorCommand = richEdit.CreateCommand(RichEditCommandId.ChangeFontBackColor);
DevExpress.Utils.Commands.ICommandUIState state = changeFontColorCommand.CreateDefaultCommandUIState();
state.EditValue = Color.Yellow;
changeFontColorCommand.ForceExecute(state);
RichEditCommand previewCommand = richEdit.CreateCommand(RichEditCommandId.PrintPreview);
previewCommand.ForceExecute(previewCommand.CreateDefaultCommandUIState());
richEdit.DeselectAll();
}
Private Shared Sub buttonCustomAction_ItemClick_Commands(ByVal sender As Object, ByVal e As ItemClickEventArgs)
Dim richEdit As RichEditControl = TryCast(e.Item.Tag, RichEditControl)
richEdit.SelectAll()
Dim capCommand As RichEditCommand = richEdit.CreateCommand(RichEditCommandId.CapitalizeEachWordTextCase)
capCommand.ForceExecute(capCommand.CreateDefaultCommandUIState())
Dim boldCommand As RichEditCommand = richEdit.CreateCommand(RichEditCommandId.ToggleFontBold)
boldCommand.ForceExecute(boldCommand.CreateDefaultCommandUIState())
Dim changeFontColorCommand As RichEditCommand = richEdit.CreateCommand(RichEditCommandId.ChangeFontBackColor)
Dim state As DevExpress.Utils.Commands.ICommandUIState = changeFontColorCommand.CreateDefaultCommandUIState()
state.EditValue = System.Drawing.Color.Yellow
changeFontColorCommand.ForceExecute(state)
Dim previewCommand As RichEditCommand = richEdit.CreateCommand(RichEditCommandId.PrintPreview)
previewCommand.ForceExecute(previewCommand.CreateDefaultCommandUIState())
richEdit.DeselectAll()
End Sub
You can bind a command to any UI element. Refer to the following article for more information: How to: Customize Context Menus for the Rich Text Editor
Take into account the following when you work with commands:
true.To change the actions performed when the built-in command is executed, use the service substitution technique. Create the IRichEditCommandFactoryService descendant which generates custom commands and use the RichEditControl.ReplaceService<T> method (or the GetService -> RemoveService -> AddService method sequence) to replace default service with a newly created service.
Refer to the following article for more information: How to: Replace Standard DXRichEdit Command with a Custom Command
The commands in Rich Text Editor ship with assigned keyboard shortcuts. You can use the RichEditControl.RemoveShortcutKey and the RichEditControl.AssignShortcutKeyToCommand methods to modify shortcut keys assigned to commands. Refer to the following article for a full list of available shortcuts: Keyboard Shortcuts
The following example removes the Ctrl+O shortcut and assigns the Alt+Y shortcut to the CreateFieldCommand to insert a field::
using System.Windows.Forms;
//...
public MainWindow()
{
InitializeComponent();
richEditControl.Loaded += RichEditControl_DocumentLoaded;
}
private void RichEditControl_DocumentLoaded(object sender, EventArgs e)
{
richEditControl.RemoveShortcutKey(Keys.O, Keys.Control, true);
richEditControl1.AssignShortcutKeyToCommand(Keys.Y, Keys.Alt, RichEditCommandId.CreateField, RichEditViewType.PrintLayout);
}
Imports DevExpress.XtraRichEdit
Imports System.Windows.Forms
'...
Public Sub New()
InitializeComponent()
AddHandler richEditControl.Loaded, AddressOf RichEditControl_DocumentLoaded
End Sub
Private Sub RichEditControl_DocumentLoaded(ByVal sender As Object, ByVal e As EventArgs)
richEditControl.RemoveShortcutKey(Keys.O, Keys.Control, true)
richEditControl1.AssignShortcutKeyToCommand(Keys.Y, Keys.Alt, RichEditCommandId.CreateField, RichEditViewType.PrintLayout)
End Sub
Use the RichEditControl.BehaviorOptions and DocumentOptions.DocumentCapabilities properties to disable the required functionality in the Rich Text Editor. As a result, the corresponding commands are also disabled.
The table below lists options and the operations they manage:
The code sample below hides all printing and page layout commands and disables zooming commands in a Ribbon UI:
<dxr:RichEditControl x:Name="richEditControl1"
CommandBarStyle="Ribbon">
<dxr:RichEditControl.BehaviorOptions>
<dxr:DXRichEditBehaviorOptions Printing="Hidden"
Zooming="Hidden"/>
</dxr:RichEditControl.BehaviorOptions>
<dxr:RichEditControl.DocumentCapabilitiesOptions>
<dxr:DXRichEditDocumentCapabilitiesOptions Sections="Disabled"/>
</dxr:RichEditControl.DocumentCapabilitiesOptions>
</dxr:RichEditControl>
You can disable or hide a command when meeting the specified criteria. Create a custom command and override its UpdateCommandUIState method. Change the state depending on the required condition. Set the ICommandUIState.Enabled property to false to disable the command; set the ICommandUIState.Visible property to false to hide the command.
The code sample below creates a custom Replace command and disables it if the document is protected:
public class CustomReplaceCommand : ReplaceCommand {
public CustomReplaceCommand(IRichEditControl control) : base(control)
{
}
public override void UpdateUIState(ICommandUIState state)
{
base.UpdateUIState(state);
if (this.Control.Document.IsDocumentProtected)
state.Enabled = false;
}
}
public class CustomRichEditCommandFactoryService : IRichEditCommandFactoryService {
readonly IRichEditCommandFactoryService service;
readonly RichEditControl control;
public CustomRichEditCommandFactoryService(RichEditControl control, IRichEditCommandFactoryService service)
{
DevExpress.Utils.Guard.ArgumentNotNull(control, "control");
DevExpress.Utils.Guard.ArgumentNotNull(service, "service");
this.control = control;
this.service = service;
}
public RichEditCommand CreateCommand(RichEditCommandId id)
{
if (id == RichEditCommandId.Replace)
return new CustomReplaceCommand(control);
return service.CreateCommand(id);
}
}
Public Class CustomReplaceCommand
Inherits ReplaceCommand
Public Sub New(ByVal control As IRichEditControl)
MyBase.New(control)
End Sub
Public Overrides Sub UpdateUIState(ByVal state As ICommandUIState)
MyBase.UpdateUIState(state)
If Me.Control.Document.IsDocumentProtected Then
state.Enabled = False
End If
End Sub
End Class
Public Class CustomRichEditCommandFactoryService
Implements IRichEditCommandFactoryService
Private ReadOnly service As IRichEditCommandFactoryService
Private ReadOnly control As RichEditControl
Public Sub New(ByVal control As RichEditControl, ByVal service As IRichEditCommandFactoryService)
DevExpress.Utils.Guard.ArgumentNotNull(control, "control")
DevExpress.Utils.Guard.ArgumentNotNull(service, "service")
Me.control = control
Me.service = service
End Sub
Public Function CreateCommand(ByVal id As RichEditCommandId) As RichEditCommand
If id = RichEditCommandId.Replace Then
Return New CustomReplaceCommand(control)
End If
Return service.CreateCommand(id)
End Function
End Class