With this template you can add a new Text Editor component to your project. Text Editor provides functionality to enter, edit and delete text - be it single or multiline. The user can scroll the text by using the keyboard or by touching the screen. When the user touches the screen for a while, a magnifying glass appears permitting the user to move the caret directly with the finger. Each time the user modifies the text in the Editor, the component sends signals to associated slot methods where your particular implementation is executed.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Text Editor you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Text Editor wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Text Editors created by the template are working widgets. If desired, they can already be used as they are. The following figure demonstrates the default appearance of the Text Editor created by using the here described component template:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Text Editor from scratch you can use the available template. The second function is more educative. The template implements fully working Text Editor component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Text Editor component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Text Editor component.

To create a new Text Editor component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Text Editor component from a template:

The new created Text Editor component appears accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Text Editor component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Text Editor class in-place within some superior GUI component. At the runtime, the superior GUI component takes care of the correct initialization and the displaying of all embedded components, so they appear similarly as you have composed them at the design time.

The following are the typical steps to create a new instance of an already existing Text Editor component:

As long as the Text Editor is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Text Editor are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Text Editor component descends from the Mosaic class Core::Group. Consequently, most of the properties listed in the above screenshot are inherited from this base class. Particular to the Text Editor are only few following properties:

Property	Description
Alignment	The property Alignment determines how the editor should display the text rows if their size differs from the size of the editor. In this manner the rows can be aligned horizontally. The entire text block can be aligned vertically.
Color	The property Color controls the color of the text and the blinking caret.
Font	The property Font refers to the font object used to display the text. The text is determined by the property String.
OnChange	The property OnChange can refer to a slot method, which should be invoked by the text editor when the user modifies the text.
String	The property String stores the text of the editor.
WrapText	The property WrapText determines whether long text rows should be wrapped automatically.

Once added to the component, you can freely move the Text Editor instance, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the component also by directly modifying its property Bounds. If you want the Text Editor to appear behind other views you can reorder it explicitly.

To enable the Text Editor to receive keyboard input, the editor must obtain focus. Focus is managed through the focus path mechanism. The Text Editor component can receive keyboard events only when:

This creates a chain of focused components from the root application down to the Text Editor, forming the focus path. Only components on this active focus path can process keyboard events. To give focus to a Text Editor instance, assign it to the Focus property of the superior component and ensure the superior component itself is focused in scope of its own superior component:

This assignment should typically be done in a slot method that responds to a user action, such as pressing a button. The Text Editor template already implements automatic focus acquisition through touch. When the user touches the editor area, the focus path is automatically established leadin to the affected Text Editor instance.

If your GUI component contains multiple input fields (multiple Text Editor instances), you can implement focus navigation using the Tab key. The superior component should handle Tab key events and move focus between the editors. For example:

Also possible, you can invoke the editor's method ObtainFocus() to establish the focus path to this editor. This will ensure that also all superior components are correctly focused:

For more details about focus management and the focus path concept, see Understanding the Focus path.

The text content of the editor is stored in and accessed through the String property. This property allows you to both set the initial text content and retrieve the current text that the user has entered or modified. To retrieve the current text from the editor, simply evaluate the String property. To assign text to the editor programmatically, modify the String property:

You can validate the entered text by checking the String property:

When the user modifies the text in the editor (by typing new contents or deleting existing contents), the editor can notify the superior component about these changes. This notification mechanism uses the signal-slot paradigm. Each time the text is modified, the editor sends a signal to an associated slot method where your particular implementation is executed.

The Text Editor exposes for this purpose the property OnChange which can store a reference to a slot method. This slot method will be invoked automatically whenever the text content changes due to user input. You can initialize OnChange with already existing slot methods or you add a new one and implement it as desired. The following steps describe how to do this:

When you start the Prototyper now, you can interact with the editor. Thereupon the editor will trigger the associated slot method each time its content is modified by the user.

Example of an OnChange slot method intended to store the content of the editor inside a data model after each modification but only when the content is valid:

The Text Editor component exposes several properties that control its appearance and behavior. These properties allow you to customize the editor without modifying its internal implementation. Once you have added a Text Editor instance to your component, you can configure these properties in the Inspector window or programmatically in your code.

Configuration examples:

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Text Editor component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Text Editor displays only the text content. At the runtime a blinking caret symbol is shown when the editor has focus. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The Text Editor can react to touch and keyboard inputs.

This default functionality is implemented by following members belonging to the Text Editor. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Text Editor to your particular needs:

Icon	Member	Description
	Font	The property Font refers to the font object used to display the text. The text is determined by the property String.
	OnSetFont	The onset method belongs to the property Font. Each time the value of the property is changed, the code implemented in the method is executed to update the Text view and reset the scroll position.
	Color	The property Color controls the color of the text and the blinking caret.
	OnSetColor	The onset method belongs to the property Color. Each time the value of the property is changed, the code implemented in the method is executed to update the Text and Caret views with the new color.
	String	The property String stores the text content of the editor.
	OnSetString	The onset method belongs to the property String. Each time the value of the property is changed, the code implemented in the method is executed to process special control characters, update the Text view and reset the scroll position.
	OnGetString	The onget method belongs to the property String. Each time the property is evaluated, this method is called to return the pure text content without special control characters.
	Alignment	The property Alignment determines how the editor should display the text rows horizontally and the entire text block vertically.
	OnSetAlignment	The onset method belongs to the property Alignment. Each time the value of the property is changed, the code implemented in the method is executed to update the Text view and reset the scroll position.
	WrapText	The property WrapText determines whether long text rows should be wrapped automatically.
	OnSetWrapText	The onset method belongs to the property WrapText. Each time the value of the property is changed, the code implemented in the method is executed to update the Text view and adjust the horizontal scrolling behavior.
	OnChange	The property OnChange can refer to a slot method, which should be invoked by the text editor when the user modifies the text.
	Text	This Text view displays the text content of the editor. The view is connected to the SlideTouchHandler for scrolling functionality and calls the updateCaret slot method whenever the text layout changes.
	Caret	This Line view displays the blinking caret indicating the current text insertion position. Its visibility is controlled by the blinkEffect and the focused state of the editor.
	CharacterKeyHandler	This key handler reacts to character key press events. When the user presses an alphanumeric key, the handler activates the method onCharacterKey which inserts the character at the caret position.
	onCharacterKey	This slot method is called when the CharacterKeyHandler has been activated. The method inserts the input character at the current caret position and sends an OnChange notification.
	NewlineKeyHandler	This key handler reacts to the Enter key. When pressed, it activates the method onNewlineKey which inserts a newline character at the caret position.
	onNewlineKey	This slot method is called when the Enter key is pressed. The method inserts a newline character at the current caret position and sends an OnChange notification.
	DeleteKeyHandler	This key handler reacts to the Delete key. When pressed, it activates the method onDeleteKey which removes the character at the caret position.
	onDeleteKey	This slot method is called when the Delete key is pressed. The method removes the character at the current caret position and sends an OnChange notification.
	BackspaceKeyHandler	This key handler reacts to the Backspace key. When pressed, it activates the method onBackspaceKey which removes the character preceding the caret position.
	onBackspaceKey	This slot method is called when the Backspace key is pressed. The method removes the character before the current caret position and sends an OnChange notification.
	CursorKeyHandler	This key handler reacts to cursor key press events (Left, Right, Up, Down). When pressed, it activates the method onCursorKey which moves the caret in the corresponding direction.
	onCursorKey	This slot method is called when a cursor key is pressed. The method calculates the new caret position based on the pressed key and updates the caret accordingly.
	SimpleTouchHandler	This touch handler processes touch interactions for caret positioning and magnifying glass activation. It covers the entire area of the editor.
	onPressTouch	This slot method is called when the user touches the editor area. It obtains focus for the editor and positions the caret at the touched location.
	onHoldTouch	This slot method is called when the user holds the finger on the editor for more than 300 milliseconds. It activates the magnifying glass feature for precise caret positioning.
	onDragTouch	This slot method is called when the user moves the finger while touching. It either moves the caret (if magnifying glass is active) or redirects to scrolling mode.
	onReleaseTouch	This slot method is called when the user releases the finger. It deactivates the magnifying glass feature.
	SlideTouchHandler	This touch handler handles scrolling of the text content with physics-based inertia. It is connected to the Text view via its SlideHandler property.
	caretIndex	This variable stores the current caret position as an index within the text string (0 = beginning, String.length = end).
	autoScroll	This variable flags whether automatic scrolling should be performed to keep the caret visible after text modification or caret movement.
	magnifyingView	This variable stores a reference to the temporary Views::WarpGroup object used to display the magnifying glass with enlarged text content.
	magnifyingBack	This variable stores a reference to the temporary Views::Rectangle object used as background for the magnifying glass.
	updateCaret	This slot method calculates and updates the pixel position of the caret based on the current caretIndex. It is called automatically when the text layout changes.
	updateScrollOffset	This slot method adjusts the scroll position of the Text view to ensure the caret remains visible after text modification or caret movement.
	updateMagnifyingView	This slot method calculates and updates the position of the magnifying glass views to follow the caret position during touch-based caret dragging.
	blinkEffect	This Bool Effect toggles the visibility of the Caret view to create the blinking animation. It is enabled when the editor has focus and disabled otherwise.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Text Editor, the method controls the caret blinking effect based on the focused state.

During its lifetime, the Text Editor will assume different states as direct effect of user interactions and as result of other superior state alternations within the GUI application. The most important state for the Text Editor is the Focused state, which determines whether the editor can receive keyboard input.

The Text Editor tracks this state through the UpdateViewState method. This method evaluates the common component state with the name Focused and controls the caret blinking animation accordingly:

The local variable is determined by testing whether the Focused state is contained in the aState parameter. When the editor lies on the focus path, this state is present, and the caret should be visible and blinking to indicate that the user can actively interact with the editor via keyboard.

When the component state Focused changes, the method UpdateViewState is invoked automatically. You don't need to worry about it. The Mosaic framework takes care of this invocation. In the default template, the state management is intentionally minimal - it only controls the caret blinking. Depending on your design expectations, you may want to extend the state management to handle additional visual feedback. For example:

To implement such extensions:

Originally, if not yet modified, the Text Editor displays only the text content and a blinking caret when focused. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the editor to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Text Editor template contains the Text view which displays the text content. You can modify the properties of this view to change the default appearance. However, be careful not to change properties that are controlled by the editor's own properties (Font, Color, String, Alignment, WrapText). These are managed automatically through the onset methods.

You can safely modify following properties of the Text view:

The Caret view displays the blinking vertical line indicating the text insertion position. You can modify its appearance:

To make the editor more visible, you can add a background rectangle:

To visually separate the editor from surrounding content, you can add a border:

Per default the caret appears as vertical line. If desired, you can replace it with another view, for example with a Bitmap Frame view, which displays a bitmap, but can be adjusted in size similar to how the caret is adjusted in height depending on the used font:

The initial size of the Text Editor is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Text Editor component will have by default. If desired, you can adjust the Canvas area and change this default size accordingly. This could be for example the case when you plan to create a large Text Editor. For this purpose you click and drag the edges of the surrounding border (see also Resize the Canvas area). Once the size is changed, you can then adapt (move, resize) the views existing within the component. For example, to make the Text Editor taller you adjust its bottom edge:

The resulting size of the Text Editor, however, is not necessarily fixed. It can be adjusted for each editor instance individually when the editor instance is arranged within a superior GUI component or it can change dynamically at the runtime. The GUI application can thus contain multiple instances of the editor, each with another size. From this arises the question, how the Text Editor will react to its size alternation?

In case of the Text view existing per default in the Text Editor template the view is automatically adjusted to fill the entire area of the editor. The same is true for the SimpleTouchHandler and SlideTouchHandler, which should usually fill the entire editor otherwise the user can't interact with it. All other views, you have added later to the Text Editor are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property. (see also Configure component layout). Let's assume, in order to display some border you have added a Border view to the Text Editor. Then you have arranged the view to fill the entire Canvas area. If you want now that the view grows and shrinks according to size changes of the Text Editor, you enable in the property Layout of this view following settings:

Now the Text Editor knows how to react to its size changes. Each editor instance can have individual size and the enclosed views are automatically arranged within the available area.

When creating your own Text Editor component you should ensure that instances of the editor can be configured to control all the features implemented in it. For example, if you have enhanced the editor to limit the maximum text length, you should allow this limit to be specified individually for each editor instance.

To control the features in your editor you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the background color. When the value of the property changes, the editor can react to it and update its appearace. The properties reflect thus the settings within your editor. Together they form the interface of the component.

In its original version, the Text Editor contains already several properties which control the font, color, text content, alignment, and text wrapping. In order to enhance this interface by your own properties, following steps are necessary:

Now when you use instances of the Text Editor component, you can configure the background color:

The Text Editor is an interactive component that can be controlled via keyboard or hardware buttons. For this purpose the template contains several Key Press Handler objects. Each handler is associated with a slot method that is invoked when the user presses a key matching the filter condition specified in the handler object.

The default template includes following keyboard handlers:

Handler	Key Filter	Associated Slot	Description
CharacterKeyHandler	Core::KeyCode.CharacterKeys	onCharacterKey	Handles alphanumeric character input and inserts the character at the current caret position.
NewlineKeyHandler	Core::KeyCode.Enter	onNewlineKey	Handles the Enter key to insert a new line character at the current caret position.
DeleteKeyHandler	Core::KeyCode.Delete	onDeleteKey	Handles the Delete key to remove the character at the current caret position.
BackspaceKeyHandler	Core::KeyCode.Backspace	onBackspaceKey	Handles the Backspace key to remove the character preceding the caret position.
CursorKeyHandler	Core::KeyCode.CursorKeys	onCursorKey	Handles cursor keys (Left, Right, Up, Down) to move the caret through the text.

Each handler object is configured with following properties:

The implementation of each slot method takes care of the corresponding text editing operation:

After each text modification, the slot methods perform following actions:

Usually you will not need to edit the implementation of these methods. They correspond already to what typical text editors do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your editor. For more details, please see the inline comments in the implementation of the respective method.

The Text Editor can also be controlled via touch screen or mouse interactions. For this purpose the template contains two touch handler objects that enable the user to position the caret and scroll the text content.

The Simple Touch Handler object named SimpleTouchHandler handles direct touch interactions for caret positioning. It covers the entire area of the editor and reacts to following touch events:

Event	Associated Slot	Description
OnPress	onPressTouch	When the user touches the screen, this slot method obtains focus for the editor and positions the caret at the touched position.
OnHold	onHoldTouch	When the user holds the finger on the screen for more than 300 milliseconds, this slot method displays the magnifying glass for precise caret positioning.
OnDrag	onDragTouch	When the user moves the finger while touching the screen, this slot method either moves the caret (if magnifying glass is active) or redirects to the slide handler for scrolling.
OnRelease	onReleaseTouch	When the user releases the finger, this slot method hides the magnifying glass again.

The SimpleTouchHandler implements intelligent behavior:

For more details, please see the inline comments in the implementation of the respective method.

The Slide Touch Handler object named SlideTouchHandler handles scrolling of the text content. It is configured with following properties:

The slide handler is automatically connected to the Text view via its SlideHandler property. This connection ensures that touch-based scrolling directly affects the text's ScrollOffset property.

The handler provides physics-based scrolling with inertia, allowing the user to flick the text content and have it continue scrolling naturally with friction-based deceleration.

If your device does not have a touch screen, both touch handlers and all associated slot methods (onPressTouch, onHoldTouch, onDragTouch, onReleaseTouch) are unnecessary and can be removed. See Add or remove touch handlers for details.

The caret is the blinking vertical line that indicates where the next character will be inserted in the text editor. The caret management involves several components working together to maintain, display, and animate the caret.

The caret is displayed using a Line view named Caret. This view is configured as:

The position of the caret is determined by the internal variable caretIndex, which stores the index within the text string where the caret is located. The value ranges from 0 (beginning of text) to the length of the text string (end of text).

The slot method updateCaret is responsible for calculating and updating the caret's pixel position. This method is called automatically whenever:

The positioning algorithm performs following steps:

The caret blinks to draw the user's attention. This blinking is implemented using the Bool Effect object named blinkEffect. The effect is connected directly to caret's Visible property and it is configured to toggle this property every 500 milliseconds. The blinking effect is controlled by the UpdateViewState method:

When the editor gains focus, the blinking animation starts. When focus is lost, the animation stops and the caret is hidden. Additionally, whenever the caret is moved or text is modified, the blink effect is restarted to ensure the caret is immediately visible. This prevents the situation where the caret might be invisible at the moment of movement, which could confuse the user:

When the user touches the screen and holds the finger for a while, a magnifying glass appears showing an enlarged view of the text around the caret. This feature helps users position the caret precisely, especially on small screens or with small fonts. This behavior is usually well known from modern mobile phone devices.

The magnifying glass feature is implemented in the slot method onHoldTouch. When the SimpleTouchHandler detects that the user has held the finger on the screen for at least 300 milliseconds, the magnifying glass is activated:

Once activated, the magnifying glass remains visible as long as the user keeps the finger on the screen. During this time, moving the finger moves the caret, and the magnifying glass follows the caret position.

The magnifying glass consists of two temporary views that are created dynamically and added to the superior component (Owner):

The magnifying glass setup involves following steps. The code is found in the method onHoldTouch:

Important aspects:

The slot method updateMagnifyingView calculates the correct position for the magnifying glass based on the current caret position. The method is invoked whenever the position of the caret changes during touch interaction:

The positioning ensures that:

When the user releases the finger from the screen, the onReleaseTouch method removes the magnifying glass views and releases the off-screen buffer:

In its original version the magnifying glass is uses a semi-transparent rectangle as background. You are free to modify the configuration of the view. For example, you can change its color or you use other views for this purpose. In the last case, you should adapt the variable magnifyingBack to have data type corresponding to the type of the view, you intend to use instead of the rectangle, for example Views::Border. Then, in the method onHoldTouch adapt the code to create an instance of the desired view, for example Views::Border:

The magnifying glass effect is achieved by zooming the content of the editor by factor 2. If desired you can adapt the implementation and calculate with other factor, for example 4. Additionally, you can disable the bi-linear filtering if you don't want the zoomed contents to appear blured. Following could be the necessary adaptation in the method onHoldTouch:

If you changed the zoom factor, also the method updateMagnifyingView requires an adaptation:

If you don't want the magnifying glass feature in your text editor, you can remove it:

The Text Editor automatically manages scrolling to ensure that the caret remains visible when the user edits text or moves the caret. This involves two types of scrolling: automatic scrolling and manual scrolling.

The slot method updateScrollOffset ensures that the caret is always visible within the text editor's bounds. This method is invoked automatically (via postsignal) after text modifications or caret movements when the autoScroll flag is set.

The algorithm checks all four edges and calculates the necessary scroll offset. For example, if the caret is to the left of the visible area, calculates an offset to scroll right:

After scrolling, the method additionally checks whether the entire text content can fit within the visible area and adjusts the scroll position accordingly. This optimization ensures that, if text becomes shorter and fits completely, the scrolling is reset and the user doesn't see unnecessary blank space when text is deleted:

Users can manually scroll the text content using touch gestures. This is handled by the SlideTouchHandler:

The internal variable autoScroll is set to true whenever:

After the updateCaret method completes, it checks this flag and triggers updateScrollOffset if necessary. This delayed execution ensures that all text layout calculations are complete before the scroll position is adjusted:

The Text Editor uses Views::Text view to display the text content. This view interprets the characters ~, ^ and % as special control characters that affect text formatting. To allow users to input and see these special characters literally, the Text Editor requires the respective character to be prefixed by the % (percent sign) character. Without the escape mechanism, users couldn't input these characters visibly.

When text is assigned to the String property, the OnSetString method processes the input string and adds escape '%' characters before each special control character:

When the String property is evaluated, the OnGetString method removes all escape '%' characters to return the clean string without escape sequences. This ensures that when the application reads the text content, it receives the clean string without any escape characters:

When the user inputs a special character via keyboard, the onCharacterKey method adds the necessary escape sequence:

Important: The caretIndex is adjusted by str.length (not just 1) because special characters are stored as two-character sequences (escape + character).

When deleting characters, the onBackspaceKey and onDeleteKey methods check whether the character to be deleted is a special character and adjust the deletion count accordingly. This ensures that both the escape '%' and the special character are deleted together, maintaining the consistency of the escape mechanism:

When the caret is positioned using cursor keys or touch input, the code checks whether the caret points to a special character and adjusts the position to refer to the escape character instead:

This ensures that the caret is always positioned before the entire escape sequence, preventing the user from inserting characters between the '%' escape and the special character.

The Text Editor adds a trailing '\n' character to the displayed text as a workaround for a text flow parser issue (in the method OnSetString):

This trailing newline is automatically removed when the string is retrieved (in the method OnGetString):

This ensures that the trailing newline is internal to the text view and doesn't appear in the actual text content returned by the editor.

The Text Editor template includes five keyboard handlers by default. Depending on your application requirements and target device capabilities, you may want to add additional handlers or remove unnecessary ones.

Following steps explain how to add a new keyboard handler to implement custom functionality. In this example, the editor is enhanced by a handler for the Escape key. When pressing this key, the content of the editor is cleared:

Similarly, you can enhance the editor to handle other keys. Following are examples of keyboard handlers that you might want to add:

Handler	Filter	Use Case
HomeKeyHandler	Core::KeyCode.Home	Move caret to beginning of text
EndKeyHandler	Core::KeyCode.End	Move caret to end of text

Example of a slot method implementing Home key:

Example of a slot method implementing End key:

If your application doesn't need certain keyboard functionality, you can remove the corresponding handler. We recommend performing the steps in following order to avoid error messages:

Similarly, if your target device has no physical keyboard and relies only on touch input and virtual keyboards, you can remove the keyboard handler related to cursor navigation keys:

The Text Editor template includes two touch handlers that enable caret positioning and text scrolling on touch-screen devices. If your target device doesn't have a touch screen, or if you want to implement custom touch behavior, you can modify or remove these handlers.

If your device has no touch screen and relies only on keyboard input, you can remove the touch handlers. We recommend performing the steps in following order:

After these steps, the text editor can still be used fully via keyboard input, but touch interactions will not be processed.

If you want touch-based caret positioning but not the scrolling:

You can add additional touch handlers for custom gestures. For example, to add a double-tap gesture to select all text:

A cue banner text (also called placeholder or hint text) is a common UI pattern that displays informative text inside an empty input field, e.g. "Search ..." or "Enter password ...". The text disappears when the editor gains focus or when the input field is not empty. This feature helps users understand what type of input is expected:

The placeholder can be implemented by adding a Text view that displays the hint text and controlling its visibility based on:

Following steps explain how to implement this feature:

Once implemented, you can configure the placeholder text for different editor instances:

The placeholder text will automatically appear and disappear as the user interacts with the editor.

A common requirement for text input fields is to limit the maximum number of characters the user can enter. Following steps explain how to add a MaxLength property to implement this functionality:

Now modify the keyboard input slot methods to check the length limit before inserting new characters:

Now when you use instances of the Text Editor component, you can configure the maximum length:

A common requirement for text input fields is to limit the input to specific characters, for example to digits for numeric inputs. This application case requires an adaptation of the method onCharacterKey. For example, to test whether the just entered character is a digit, following condition can be added at the beginning of the method. Entering a non digit character causes the method to exit ignoring the entered character:

Another application case when using a Text Editor is an automatic correction or modification of the text just in the moment when the user enters it. For example, the text can be capitalized. This application case requires an adaptation of the method onCharacterKey to test and modify the entered characters. The following code snipped demonstrates the modification for the application case of automatically capitalized text:

A common requirement for text editors is to display password input where the actual characters are masked with asterisks (*) or other symbols for security. The Text Editor template can be adapted to implement this functionality by intercepting the text display and replacing characters with mask symbols. Following steps explain how to implement password input:

When the target device doesn't have a physical keyboard, text input can still be accomplished using a virtual keyboard displayed on the screen. The Text Editor component template works seamlessly with virtual keyboard components, such as the Alphanumeric Keyboard or Numeric Keyboard template. As soon as the virtual keyboard is visible on the screen, it automatically generates keyboard events that the Text Editor receives and processes - just as if the user were pressing keys on a physical keyboard.

The integration between the Text Editor and a virtual keyboard is based on the focus path mechanism. When a Text Editor has focus (lies on the focus path), it receives all keyboard events - whether they originate from a physical keyboard or are generated by a virtual keyboard component. This automatic event routing ensures that no special configuration is needed in the Text Editor itself. The component processes character input, cursor key navigation, backspace, and delete operations identically, regardless of the event source.

The virtual keyboard generates keyboard events by calling the DriveKeyboardHitting() method, which sends events to the root object (application component). These events are then automatically forwarded along the focus path to the currently focused component. If a Text Editor is focused, it receives the events through its keyboard handlers (CharacterKeyHandler, DeleteKeyHandler, BackspaceKeyHandler, etc.) and processes them normally.

The most common pattern for virtual keyboard integration is to show the keyboard when the Text Editor gains focus and hide it when focus is lost. This provides an intuitive user experience where the keyboard automatically appears when text input is needed and disappears when it's not required.

To implement this functionality, you need to:

First, you need to add a virtual keyboard component to your Application component. For this example, we'll use the Alphanumeric Keyboard template:

Now you need to add two methods to the Application component that take care of presenting and hiding the virtual keyboard. These methods will be called by the Text Editor when its focus state changes:

Now you need to modify the Text Editor component to call these Application methods when its focus state changes. This is done in the UpdateViewState method:

If your application contains multiple Text Editor instances, the same virtual keyboard can serve all of them. The focus path mechanism automatically ensures that keyboard events are delivered to whichever editor currently has focus:

To implement this behavior, each Text Editor calls ShowKeyboard when it gains focus and HideKeyboard when it loses focus. The ShowKeyboard method checks if the keyboard is already visible and does nothing if so, avoiding unnecessary animations or state changes.

Different text editors in your application might require different keyboard layouts. For example, a numeric input field needs only digits, while a general text field needs the full alphanumeric keyboard. To implement this you can enhance the ShowKeyboard method to accept a parameter indicating which layout to use. In the method evaluate the parameter and ensure the desired virtual keyboard is visible and enabled. Other keyboards remain hidden.