Muokkaa

Jaa

Editor

  • Artikkeli

The .NET Multi-platform App UI (.NET MAUI) Editor allows you to enter and edit multiple lines of text.

Editor defines the following properties:

  • AutoSize, of type EditorAutoSizeOption, defines whether the editor will change size to accommodate user input. By default, the editor doesn't auto size.
  • HorizontalTextAlignment, of type TextAlignment, defines the horizontal alignment of the text.
  • VerticalTextAlignment, of type TextAlignment, defines the vertical alignment of the text.

These properties are backed by BindableProperty objects, which means that they can be targets of data bindings, and styled.

In addition, Editor defines a Completed event, which is raised when the user finalizes text in the Editor with the return key.

Editor derives from the InputView class, from which it inherits the following properties:

  • CharacterSpacing, of type double, sets the spacing between characters in the entered text.
  • CursorPosition, of type int, defines the position of the cursor within the editor.
  • FontAttributes, of type FontAttributes, determines text style.
  • FontAutoScalingEnabled, of type bool, defines whether the text will reflect scaling preferences set in the operating system. The default value of this property is true.
  • FontFamily, of type string, defines the font family.
  • FontSize, of type double, defines the font size.
  • IsReadOnly, of type bool, defines whether the user should be prevented from modifying text. The default value of this property is false.
  • IsSpellCheckEnabled, of type bool, controls whether spell checking is enabled.
  • IsTextPredictionEnabled, of type bool, controls whether text prediction and automatic text correction is enabled.
  • Keyboard, of type Keyboard, specifies the soft input keyboard that's displayed when entering text.
  • MaxLength, of type int, defines the maximum input length.
  • Placeholder, of type string, defines the text that's displayed when the control is empty.
  • PlaceholderColor, of type Color, defines the color of the placeholder text.
  • SelectionLength, of type int, represents the length of selected text within the control.
  • Text, of type string, defines the text entered into the control.
  • TextColor, of type Color, defines the color of the entered text.
  • TextTransform, of type TextTransform, specifies the casing of the entered text.

These properties are backed by BindableProperty objects, which means that they can be targets of data bindings, and styled.

In addition, InputView defines a TextChanged event, which is raised when the text in the Editor changes. The TextChangedEventArgs object that accompanies the TextChanged event has NewTextValue and OldTextValue properties, which specify the new and old text, respectively.

For information about specifying fonts on an Editor, see Fonts.

Create an Editor

The following example shows how to create an Editor:

<Editor x:Name="editor"
        Placeholder="Enter your response here"
        HeightRequest="250"
        TextChanged="OnEditorTextChanged"
        Completed="OnEditorCompleted" />

The equivalent C# code is:

Editor editor = new Editor { Placeholder = "Enter text", HeightRequest = 250 };
editor.TextChanged += OnEditorTextChanged;
editor.Completed += OnEditorCompleted;

The following screenshot shows the resulting Editor on Android:

Screenshot of a basic Editor on Android.

Note

On iOS, the soft input keyboard can cover a text input field when the field is near the bottom of the screen, making it difficult to enter text. However, in a .NET MAUI iOS app, pages automatically scroll when the soft input keyboard would cover a text entry field, so that the field is above the soft input keyboard. The KeyboardAutoManagerScroll.Disconnect method, in the Microsoft.Maui.Platform namespace, can be called to disable this default behavior. The KeyboardAutoManagerScroll.Connect method can be called to re-enable the behavior after it's been disabled.

Entered text can be accessed by reading the Text property, and the TextChanged and Completed events signal that the text has changed or been completed.

The TextChanged event is raised when the text in the Editor changes, and the TextChangedEventArgs provide the text before and after the change via the OldTextValue and NewTextValue properties:

void OnEditorTextChanged(object sender, TextChangedEventArgs e)
{
    string oldText = e.OldTextValue;
    string newText = e.NewTextValue;
    string myText = editor.Text;
}

The Completed event is only raised on Windows when the user has ended input by pressing the Tab key on the keyboard, or by focusing another control. The handler for the event is a generic event handler:

void OnEditorCompleted(object sender, EventArgs e)
{
   string text = ((Editor)sender).Text;
}

Set character spacing

Character spacing can be applied to an Editor by setting the CharacterSpacing property to a double value:

<Editor ...
        CharacterSpacing="10" />

The result is that characters in the text displayed by the Editor are spaced CharacterSpacing device-independent units apart.

Note

The CharacterSpacing property value is applied to the text displayed by the Text and Placeholder properties.

Limit input length

The MaxLength property can be used to limit the input length that's permitted for the Editor. This property should be set to a positive integer:

<Editor ... MaxLength="10" />

A MaxLength property value of 0 indicates that no input will be allowed, and a value of int.MaxValue, which is the default value for an Editor, indicates that there is no effective limit on the number of characters that may be entered.

Auto-size an Editor

An Editor can be made to auto-size to its content by setting the Editor.AutoSize property to TextChanges, which is a value of the EditorAutoSizeOption enumeration. This enumeration has two values:

  • Disabled indicates that automatic resizing is disabled, and is the default value.
  • TextChanges indicates that automatic resizing is enabled.

This can be accomplished as follows:

<Editor Text="Enter text here"
        AutoSize="TextChanges" />

When auto-resizing is enabled, the height of the Editor will increase when the user fills it with text, and the height will decrease as the user deletes text. This can be used to ensure that Editor objects in a DataTemplate in a CollectionView size correctly.

Important

An Editor will not auto-size if the HeightRequest property has been set.

Transform text

An Editor can transform the casing of its text, stored in the Text property, by setting the TextTransform property to a value of the TextTransform enumeration. This enumeration has four values:

  • None indicates that the text won't be transformed.
  • Default indicates that the default behavior for the platform will be used. This is the default value of the TextTransform property.
  • Lowercase indicates that the text will be transformed to lowercase.
  • Uppercase indicates that the text will be transformed to uppercase.

The following example shows transforming text to uppercase:

<Editor Text="This text will be displayed in uppercase."
        TextTransform="Uppercase" />

Customize the keyboard

The keyboard that's presented when users interact with an Editor can be set programmatically via the Keyboard property, to one of the following properties from the Keyboard class:

  • Chat – used for texting and places where emoji are useful.
  • Default – the default keyboard.
  • Email – used when entering email addresses.
  • Numeric – used when entering numbers.
  • Plain – used when entering text, without any KeyboardFlags specified.
  • Telephone – used when entering telephone numbers.
  • Text – used when entering text.
  • Url – used for entering file paths & web addresses.

The following example shows setting the Keyboard property:

<Editor Keyboard="Chat" />

The Keyboard class also has a Create factory method that can be used to customize a keyboard by specifying capitalization, spellcheck, and suggestion behavior. KeyboardFlags enumeration values are specified as arguments to the method, with a customized Keyboard being returned. The KeyboardFlags enumeration contains the following values:

  • None – no features are added to the keyboard.
  • CapitalizeSentence – indicates that the first letter of the first word of each entered sentence will be automatically capitalized.
  • Spellcheck – indicates that spellcheck will be performed on entered text.
  • Suggestions – indicates that word completions will be offered on entered text.
  • CapitalizeWord – indicates that the first letter of each word will be automatically capitalized.
  • CapitalizeCharacter – indicates that every character will be automatically capitalized.
  • CapitalizeNone – indicates that no automatic capitalization will occur.
  • All – indicates that spellcheck, word completions, and sentence capitalization will occur on entered text.

The following XAML code example shows how to customize the default Keyboard to offer word completions and capitalize every entered character:

<Editor>
    <Editor.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Editor.Keyboard>
</Editor>

The equivalent C# code is:

Editor editor = new Editor();
editor.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

Hide and show the soft input keyboard

The SoftInputExtensions class, in the Microsoft.Maui namespace, provides a series of extension methods that support interacting with the soft input keyboard on controls that support text input. The class defines the following methods:

  • IsSoftInputShowing, which checks to see if the device is currently showing the soft input keyboard.
  • HideSoftInputAsync, which will attempt to hide the soft input keyboard if it's currently showing.
  • ShowSoftInputAsync, which will attempt to show the soft input keyboard if it's currently hidden.

The following example shows how to hide the soft input keyboard on an Editor named editor, if it's currently showing:

if (editor.IsSoftInputShowing())
    await editor.HideSoftInputAsync(System.Threading.CancellationToken.None);

Enable and disable spell checking

The IsSpellCheckEnabled property controls whether spell checking is enabled. By default, the property is set to true. As the user enters text, misspellings are indicated.

However, for some text entry scenarios, such as entering a username, spell checking provides a negative experience and so should be disabled by setting the IsSpellCheckEnabled property to false:

<Editor ... IsSpellCheckEnabled="false" />

Note

When the IsSpellCheckEnabled property is set to false, and a custom keyboard isn't being used, the native spell checker will be disabled. However, if a Keyboard has been set that disables spell checking, such as Keyboard.Chat, the IsSpellCheckEnabled property is ignored. Therefore, the property cannot be used to enable spell checking for a Keyboard that explicitly disables it.

Enable and disable text prediction

The IsTextPredictionEnabled property controls whether text prediction and automatic text correction is enabled. By default, the property is set to true. As the user enters text, word predictions are presented.

However, for some text entry scenarios, such as entering a username, text prediction and automatic text correction provides a negative experience and should be disabled by setting the IsTextPredictionEnabled property to false:

<Editor ... IsTextPredictionEnabled="false" />

Note

When the IsTextPredictionEnabled property is set to false, and a custom keyboard isn't being used, text prediction and automatic text correction is disabled. However, if a Keyboard has been set that disables text prediction, the IsTextPredictionEnabled property is ignored. Therefore, the property cannot be used to enable text prediction for a Keyboard that explicitly disables it.

Prevent text entry

Users can be prevented from modifying the text in an Editor by setting the IsReadOnly property, which has a default value of false, to true:

<Editor Text="This is a read-only Editor"
        IsReadOnly="true" />

Note

The IsReadonly property does not alter the visual appearance of an Editor, unlike the IsEnabled property that also changes the visual appearance of the Editor to gray.