Skip to content

Latest commit

 

History

History
120 lines (87 loc) · 4.69 KB

RichSuggestBox.md

File metadata and controls

120 lines (87 loc) · 4.69 KB
Raw
title author description keywords dev_langs
RichSuggestBox
huynhsontung
A rich text input control that auto-suggests and stores token items in a document.
windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, RichSuggestBox
csharp

RichSuggestBox

The RichSuggestBox is a combination of AutoSuggestBox and RichEditBox that can provide suggestions based on customizable prefixes. Selected suggestions are embedded and tracked in the document as tokens.

RichSuggestBox resembles text controls commonly found in social applications where you type "@" to mention people.

Platform APIs: RichSuggestBox

[!div class="nextstepaction"] Try it in the sample app

Syntax

<controls:RichSuggestBox
  PlaceholderText="Leave a comment"
  ItemTemplate="{StaticResource SuggestionTemplate}"
  Prefixes="@#" />

Example Output

RichSuggestBox Example

Remarks

When a suggestion is selected, RichSuggestBox assigns the selected item a unique Guid and a display text (provided by the developer) to make up a token. The display text is then padded with Zero Width Spaces (ZWSP) and inserted into the document as a hyperlink using the identifier as the link address. These hyperlinks are tracked and validated on every text change.

The token text inserted into the document has the following layout: ZWSP - Prefix character - Display text - ZWSP.

For example, a token with "@" as the prefix and "John Doe" as the display text is inserted as:

"\u200b@John Doe\u200b"

Important

Token text contains Zero Width Spaces, which are Unicode characters.

Note

To support Undo/Redo function, RichSuggestBox keeps all the tokens in an internal collection even when the token text is deleted from the document. These token are marked as inactive and are not included in the Tokens collection. Use ClearUndoRedoSuggestionHistory() method to clear inactive tokens or Clear() method to clear all tokens.

Examples

Handle multiple token types

The example below creates a RichSuggestBox that can tokenize both mentions (query starts with @) and hashtags (query starts with #).

<controls:RichSuggestBox
  PlaceholderText="Leave a comment"
  ItemTemplate="{StaticResource SuggestionTemplate}"
  SuggestionChosen="OnSuggestionChosen"
  SuggestionRequested="OnSuggestionRequested"
  Prefixes="@#" />
private void OnSuggestionChosen(RichSuggestBox sender, SuggestionChosenEventArgs args)
{
  if (args.Prefix == "#")
  {
    // User selected a hashtag item
    args.DisplayText = ((SampleHashtagDataType)args.SelectedItem).Text;
  }
  else
  {
    // User selected a mention item
    args.DisplayText = ((SampleEmailDataType)args.SelectedItem).DisplayName;
  }
}

private void OnSuggestionRequested(RichSuggestBox sender, SuggestionRequestedEventArgs args)
{
  sender.ItemsSource = args.Prefix == "#"
    ? _hashtags.Where(x => x.Text.Contains(args.QueryText, StringComparison.OrdinalIgnoreCase))
    : _emails.Where(x => x.DisplayName.Contains(args.QueryText, StringComparison.OrdinalIgnoreCase));
}

Plain text only

The example below creates a RichSuggestBox that only allows users to enter plain text. The only formatted texts in the document are tokens.

<controls:RichSuggestBox
  ClipboardCopyFormat="PlainText"
  ClipboardPasteFormat="PlainText"
  DisabledFormattingAccelerators="All" />

Sample Project

RichSuggestBox sample page Source. You can see this in action in Windows Community Toolkit Sample App.

Requirements

Device family Universal, 10.0.17763.0 or higher
Namespace Microsoft.Toolkit.Uwp.UI.Controls
NuGet package Microsoft.Toolkit.Uwp.UI.Controls

Source Code

Related Topics