Microsoft-ui-xaml: Proposal: Prefix and Suffix Properties for TextBox

[mdtauk]

Proposal: Prefix and Suffix properties for TextBox

Summary

These would be templated and stylable content properties for the TextBox control and any controls deriving from it. They would add context to the text being entered, and enable easy formatting of things like URLs, currencies, and units and well as Xaml content such as icons, buttons, ComboBox, etc.

Rationale

During discussion, planning and spec writing for the NumberBox control #483
https://github.com/microsoft/microsoft-ui-xaml-specs/pull/29
One of the features that received a lot of support was the addition of Prefix and Suffix content - which is a feature taken from the Fabric Web TextField control.

Because of the useful-ness of this feature, it was suggested that this feature should make its way to the TextBox itself, and could then be available for NumberBox and other similar controls in the future.

Scope

| Capability | Priority |
| :---------- | :------- |
| Display content within the TextBox before and/or after the Text string | Must |
| Provide default styling for Buttons or ComboBoxes added as content to match the UX | Must |
| The ability to edit the template and/or style of the Prefix and Suffix | Must |
| The ability to append the content to text that is copy and pasted | Could |

| API | Priority |
| :---------- | :------- |
| Display/Hide Prefix and Suffix. | Must |

Important Notes

Here are some visual examples of how these properties could look on the TextBox:

The look for these Prefix and Suffix content is taken from the FabricWeb controls, but using the XAML control metrics.

Notes

• Note that this concept already exists in Fabric Web. Alignment of design and APIs where able is ideal.

[vborovikov]

What if I want put an icon there? Will I be able to use DataTemplates for Prefix/Suffix properties?

[dpierangeli]

Ok, maybe it is a bit too complicated.. but since it seems like the Bootstrap Input Addon i think that the icon support is important.
I've seen the pattern of using an icon in the prefix a lot.

Maybe in future support for buttons can be added :)

(and sorry for the bad english :( )

[SavoySchuler]

Fantastic, @mdtauk! I look forward to refining this proposal as a potential feature improvement for WinUI 3's TextBox. As you know, we may have speculative opportunity to pilot this in NumberBox (#483) also if the timing works out.

@dpierangeli - benvenuto! There is no need to apologize. We wouldn't be Microsoft without a global community so please join the conversations across our repos as much as you can. We specifically need voices like yours and @vboroviko to make sure our controls are world-class! 😄

@vborovikov - Приветствовать! Same to you, thank you for joining the conversation.

I have also seen icons used in a prefix or suffix. Most memorably is a telephone or address marker. Is this feature worth delaying V1 for? Or would icons be an appropriate V2 addition if it means getting the basic prefix and suffix capability sooner?

I would be interested to know how you plan to use PrefixText and SuffixText in your live apps.

[mrlacey]

Calling these properties PrefixText and SuffixText is potentially limiting and problematic if the eventual goal is to be able to support more than just text.

If a future version will support DataTemplates and arbitrary content, having "Text" at the end of the name could be confusing and misleading.
Changing the property names in the future would be a breaking change and so should be avoided.
Just calling them Prefix and Suffix would allow for flexibility in the future and follow the convention used by the Header property.

Adding "Text" to the names was originally mentioned in the NumberBox spec review when that only talked about them containing strings. As that followed the precedent set by PlaceholderText.

I would like to see Prefix and Suffix defined as being of type object, like Header so that any content can be passed in and displayed. Like Header if a string is passed in this would be rendered in a TextBlock.

I would also really like to see the ability to include PrefixTemplate and SuffixTemplate properties that all the full customization of what is displayed but can understand if this doesn't make the cut for an initial release.

Even if these new properties are initially added as just supporting strings/text, they should still also include the ability to set the Foreground and Background colors for each property separately. I don't think it would be appropriate to have these exposed as different properties (as they also need to vary for each state.)

[vborovikov]

Personally I would achieve the same look and feel by restyling the TextBox, or deriving from it, or creating an UserControl. Adding properties, somewhat useful in specific scenarios, to core controls only makes their styles more complex.

[mdtauk]

I am in favour of making them content properties so they can include not only icons, but maybe even buttons and drop downs.

In fact I've updated the proposal to take this into account.

You could have a drop down to change the unit of measurement in the suffix for instance, change the end of a URL to .co.uk, or change the unit of currency in a prefix.

Buttons added could adopt the style we determined for the spin buttons on the NumberBox. The existing SearchBox, and PasswordBox could then use these buttons also, keeping a consistent look and feel.

The Suffix and Prefix should have templates and styles so their appearance can be changed without having to retemplate the entire control

[robloo]

Here is another example where a generic (content property) Prefix/Suffix would be useful. There is a ComboBox Suffix to select currency and a ToggleButton Prefix to negate the amount.

Adding a currency symbol as text would also be a good use of the prefix/suffix as mentioned earlier.

@mdtauk I don't know how you keep cranking out those amazing illustrations -- especially so quickly -- but they are awesome!

[mrlacey]

@robloo but that doesn't necessarily work for cultures that indicate negatives after the amount.

[robloo]

@mrlacey Yes, that's true but the app (not the TextBox control) handles that logic. My point was having a generic Prefix/Suffix would allow developers to put controls into the TextBox like the examples I gave. It doesn't matter if the negative sign should be in the suffix instead of the prefix. The TextBox would have no knowledge about this type of localization -- or usecase -- itself.

[SavoySchuler]

@mdtauk - I'm about to make a few edits to the proposal as I am prepping to pitch this to the team today, I hope this is OK?

Thanks for helping get this jump-started everyone! Love where this is going! 😄

[MikeHillberg]

There should be a 'must' for the prefix/main/suffix text to all be baseline aligned.

[mdtauk]

@SavoySchuler Please share how it is received, and the changes you make.

[SavoySchuler]

@mdtauk, of course! You can view the edit history at the top of the proposal by click the "edited by..." text.

Pitch Review Summary

The consensus on adding Prefix and Suffix text properties was unanimously positive (for those in attendance).

Where things got more interesting was in respect to the concept of making these properties content areas to embed Xaml controls (ComboBox, Button). @chrisglein noted that this concept of combining side-by-side controls into a uniform style and contiguous layout is not new - in fact, looking at SplitButton and ToggleSplitButton, it may be a problem that we are once again architecting a unique control for rather than addressing the problem at its root. More useful, perhaps, than continuing to append content properties or add static control combinations is the idea of creating a "ControlCombiner" that comes with a pre-defined set of combinable controls and layouts/style/templates/accessible navigation patterns for their configurations.

Given that this proposal as it stands is blocked on WinUI 3.0, I am going to open a ControlCombiner proposal to explore its value and see if could solve the scenarios listed here (E.g., configurations needed being TextBox-TextBox, TextBox-Button. TextBox-ComboBox) with the goal of this exploration being to understand if we can offer a more universal solution upstream that avoid. Depending on how this turns out, it may or may not be necessary to still add SuffixText/PrefixText properties to TextBox in this way.

Regardless, the idea at its core is worthy. Its the question of _how best_ that I will continue to work at. 😊

[mdtauk]

A Control Combiner as it stands right now feels like an overdesigned solution - but the Ribbon is full of combined controls I guess, and that control has been on the backlog for a long time, so it may be part of the step to realising that.

Would there be a list of controls that get combined?

Would there be a syntax for defining where one control combines with another?

Is it just a XAML Parent control, which contains multiple controls, and allows some clever kind of styling?

Do you just create a superset of the TextBox that can include other controls within it?

[SavoySchuler]

@mdtauk - I spoke with @ryandemopoulos and the over-designed concern exists here too. I am going to pitch this again to a broader team audience and see if we can ignite more discussion on this. The goal, ultimately, is to ensure we aren't only bolting on after-market features but also giving headspace to flexible, Fluent solutions with respect to the idea of embedding XamlControls in the Prefix/Suffix content

The spectrum of solutions includes:

1. PrefixText/SuffixText only
2. ControlCombiner
3. Prefix/Suffix content (allows Xaml Controls)

To answer your trailing questions, option # 2 would likely require a defined list of pre-configured options (e.g., configurations needed being TextBox-TextBox, TextBox-Button. TextBox-ComboBox). Intuition tells me a "ControlCombiner" would be a parent control that contains ~2 sub controls and that horizontal contiguousness would be the default layout defined via an enum value that could be expanded as needed by customer scenarios in v1 or otherwise. This, however, is a rabbit hole that I am still skeptical of. I have pitches booked for the next few weeks, so it will take me some time to get this back in the loop, but I will do my diligence and get you another update as soon as I can. 😄

In the meantime, it would be useful for me to hear opinions on the question @chrisglein raised, which is that contiguous layout (especially with the coming future of rounded corners) is a problem that we could solve via some Control combiner and, perhaps in doing so, also satisfy this Prefix/Suffix requirement with a -TextBox / TextBox- combination?

[mdtauk]

@SavoySchuler I can't think of any other XAML control in UWP, WPF, Silverlight, or Windows Phone. The closest I can think of is the Adorner in WPF?

The point of a ControlCombiner seems to be solving the design problem of integrating controls within controls, so they visually appear to be a single control, yet it also needs to:

• Support Styling individual template parts via ResourceDictionaries, Implicit styling and Lightweight Resources;
• Support re-positioning of the individual controls, whilst keeping the control visually one entity;
• Support proper Focus, Keyboarding, and Accessibility for each part of the control;
• Include failsafes for how the ControlTemplate is written and re-templated by others, to avoid breaking controls;
• Remain consistent as new Combined Controls are added to WinUI in the future;

---

Thinking of the current suite of controls, that could be redone with the control combiner:

• AutoSuggest Box - Flyout, TextField, Search Icon Button
• SplitButton - Two Buttons, flyout
• ComboBox / Editable ComboBox - TextField, Chevron Icon Button
• CalendarDatePicker - TextField, maybe a Calendar Icon Button
• TimePicker / _proposed_ SplitTimePicker #905 - Hour, Min, Seconds, Period(AM/PM) ComboBoxes
• DatePicker / _proposed_ SplitDatePicker #905 - Day, Month, Year ComboBoxes
• _proposed_ NumberBox #483 - TextField, Up and Down Buttons

There are probably others, but what this control type would do, is a little up in the air right now.

[chrisglein]

It's entirely possible a "control combiner" is over-designing the problem. But it's also possible we're hitting up against a general pattern here and a shared utility could simplify some controls and/or make others redundant. I don't know where this one would fall, as my thinking on it is pretty fresh.

Visually there are a couple of areas we've hit that need to be coordinated when doing this kind of multiple-controls-in-a-box:

• Corners
• Borders (interior versus exterior)
• Shadow

All of these have involved more work in the layout/VSM than you'd think necessary. Looking at PRs for those features there's a lot of implementation/policy duplicated here that probably doesn't need to be.

I'm not yet convinced on whether we need a full control for this or just some sort of utility/layout/something to reduce the redundant implementation. Needs more thought. But since raising this I keep seeing more and more examples of controls on the web and in apps that could fit into this bucket. It could be a thing...

To be clear this doesn't seem like it would want to be open ended problem. More like a fixed collection of controls that can be slotted together into a group. And I don't think it'd be a goal to handle retemplated versions of those sub-controls. "ControlCombiner" sounds a bit too open ended. More like "GroupOfTwoToThreeSubPartWhichMayIndividuallyBeTextOrButtonOrDropDown"

[mdtauk]

@chrisglein I posted a discussion #899 about Text and Form controls, which compare controls which all share a design.

Other than the Button/SplitButton - I can't think of other controls which are so intrinsically intertwined visually. So perhaps this is something to be made for FormField controls primarily?

The XAML Ribbon when it happens, may need the same thing as there are lots of custom controls which need flexible designs.

[SavoySchuler]

Accidental close - I am still actively working on this issue.

[MuziburRahman]

Any update on this? It's been a while.