Xamarin.Forms Editor Tutorial
Before attempting this tutorial, you should have successfully completed the:
- Build your first Xamarin.Forms app quickstart.
- StackLayout tutorial.
In this tutorial, you learn how to:
- Create a Xamarin.Forms
Editor
in XAML. - Respond to the text in the
Editor
changing. - Customize the behavior of the
Editor
.
You will use Visual Studio 2019, or Visual Studio for Mac, to create a simple application that demonstrates how to customize the behavior of an Editor
. The following screenshots show the final application:
You'll also use XAML Hot Reload for Xamarin.Forms to see UI changes without rebuilding your application.
Create a editor
To complete this tutorial you should have Visual Studio 2019 (latest release), with the Mobile development with .NET workload installed. In addition, you will require a paired Mac to build the tutorial application on iOS. For information about installing the Xamarin platform, see Installing Xamarin. For information about connecting Visual Studio 2019 to a Mac build host, see Pair to Mac for Xamarin.iOS development.
Launch Visual Studio, and create a new blank Xamarin.Forms app named EditorTutorial.
Important
The C# and XAML snippets in this tutorial requires that the solution is named EditorTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.
For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.
In Solution Explorer, in the EditorTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:
<?xml version="1.0" encoding="utf-8"?> <ContentPage xmlns="http://xamarin.com/schemas/2014/forms" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" x:Class="EditorTutorial.MainPage"> <StackLayout Margin="20,35,20,20"> <Editor Placeholder="Enter multi-line text here" HeightRequest="200" /> </StackLayout> </ContentPage>
This code declaratively defines the user interface for the page, which consists of an
Editor
in aStackLayout
. TheEditor.Placeholder
property specifies the placeholder text that's shown when theEditor
is first displayed. In addition, theHeightRequest
property specifies the height of theEditor
in device-independent units.In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:
Note
While Android indicates the height of the
Editor
, iOS does not.In Visual Studio, stop the application.
Respond to text changes
In MainPage.xaml, modify the
Editor
declaration so that it sets a handler for theTextChanged
andCompleted
events:<Editor Placeholder="Enter multi-line text here" HeightRequest="200" TextChanged="OnEditorTextChanged" Completed="OnEditorCompleted" />
This code sets the
TextChanged
event to an event handler namedOnEditorTextChanged
, and theCompleted
event to an event handler namedOnEditorCompleted
. Both event handlers will be created in the next step.In Solution Explorer, in the EditorTutorial project, expand MainPage.xaml and double-click MainPage.xaml.cs to open it. Then, in MainPage.xaml.cs, add the
OnEditorTextChanged
andOnEditorCompleted
event handlers to the class:void OnEditorTextChanged(object sender, TextChangedEventArgs e) { string oldText = e.OldTextValue; string newText = e.NewTextValue; } void OnEditorCompleted(object sender, EventArgs e) { string text = ((Editor)sender).Text; }
When the text in the
Editor
changes, theOnEditorTextChanged
method executes. Thesender
argument is theEditor
object responsible for firing theTextChanged
event, and can be used to access theEditor
object. TheTextChangedEventArgs
argument provides the old and new text values, from before and after the text change.When the editing is completed, the
OnEditorCompleted
method executes. This is achieved by unfocussing theEditor
, or additionally by pressing the "Done" button on iOS. Thesender
argument is theEditor
object responsible for firing theTextChanged
event, and can be used to access theEditor
object.In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:
Set breakpoints in the two event handlers, enter text into the
Editor
, and observe theTextChanged
event firing. Unfocus theEditor
to observe theCompleted
event firing.For more information about
Editor
events, see Events and interactivity in the Xamarin.Forms Editor guide.
Customize behavior
In MainPage.xaml, modify the
Editor
declaration to customize its behavior:<Editor Placeholder="Enter multi-line text here" AutoSize="TextChanges" MaxLength="200" IsSpellCheckEnabled="false" IsTextPredictionEnabled="false" />
This code sets properties that customize the behavior of the
Editor
. TheAutoSize
property is set toTextChanges
, which indicates that the height of theEditor
will increase when its filled with text, and decrease as text is removed. TheMaxLength
property limits the input length that's permitted for theEditor
. In addition, theIsSpellCheckEnabled
property is set tofalse
to disable spell checking, while theIsTextPredictionEnabled
property is set tofalse
to disable text prediction and automatic text prediction.If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator. Enter text into the
Editor
and observe that the height of theEditor
increases as it fills with text, and decreases as text is removed, and that the maximum number of characters that can be entered is 200:In Visual Studio, stop the application.
For more information about customizing
Editor
behavior, see the Xamarin.Forms Editor guide.
Congratulations!
Congratulations on completing this tutorial, where you learned how to:
- Create a Xamarin.Forms
Editor
in XAML. - Respond to the text in the
Editor
changing. - Customize the behavior of the
Editor
.
Next steps
To learn more about the basics of creating mobile applications with Xamarin.Forms, continue to the Image tutorial.
Related links
Have an issue with this section? If so, please give us some feedback so we can improve this section.