Proposal: NumberBox control

[sonnemaf]

The WinUI Team has opened a spec and PR for this feature.

Proposal: NumberBox Control

Summary

The NumberBox control provides developers a fully featured control for receiving a numeric (integer, floating point or currency) value. The keyboard InputScope is set to Number and additional support such as Up/Down buttons, formatting, and basic computation is optionally provided.

Rationale

• UWP has controls for Text, Date and Time values. Why not for Numeric values? Numbers are very common. They deserve an own input control. It will help all enterprise app developers who create data entry dialogs.

• Similar proposal found on Calculator's repo: Embed as UWP Control calculator#453

Scope

Capability	Priority
Input validation (including min/max).	Must
Mechanism to increment/decrement value by custom step size with enableable wraparound.	Must
Formatting support for currency, prefix/suffix, etc.	Must
Calculator support.	Must
Scroll and drag to change input.	TBD

Important Notes

Calculator support
It would be nice if there was a calculator support. If you type '5 + 2' in the NumberBox it calculates 7 on lostfocus.

I have tried to implement this as a Behavior but I think a NumberBox control is more suitable and easier to discover. https://github.com/sonnemaf/XamlCalculatorBehavior

Input validation
It would be nice if the control would validate all input. It wouldn't allow (for example) to enter the decimal separator twice. A CanBeNegative (bool) and DecimalsPlaces (int) properties would also be needed.

I have tried to implement this as a Behavior but I think a NumberBox control is more suitable and easier to discover. https://github.com/sonnemaf/NumberBoxBehavior

Up/Down buttons
It would be nice if you can set a flag which allows met to add '+' and '-' buttons next to the NumberBox. A Minimum and Maximum properties would be nice.

Currency support
Support for currency input.

Accessibility and Inputs

• For Narrator users, ensure the Up/Down buttons + increment can be stated and clearly understood, as opposed to "plus" and "minus".

• Will Xbox controller need any focus trapping to ensure the analog sticks and D-Pad will function as expected?

Open Questions

• Does anyone have any real app scenarios that justify needing support for hexadecimal or binary?

• Is there value in creating a preview for calculation results? @mdtauk created a few example visualizations:

[ArchieCoder]

As a starting point, Telerik has one https://www.telerik.com/universal-windows-platform-ui/numericbox. It is available in Open Source too: https://github.com/telerik/UI-For-UWP/blob/master/Controls/Input/Input.UWP/NumericBox/RadNumericBox.cs.

What I like from them is their approach for the formatting with the property ValueFormat.

Example: ValueFormat="{}{0,0:C2}"

[robloo]

Please also make sure this is correctly localised. The Windows Community Toolkit implementation has some shortcomings:

The TextBoxRegex extension with ValidationType="Decimal" does not support all UI cultures. Instead it's fixed to InvariantCulture. In English decimal values are "10.1234" with a period. In Spanish or German decimal values are written "10,1234". Parsing the English will be correct; however, Spanish or German user input will just be "101234" with the fractional portion lost.

See: CommunityToolkit/WindowsCommunityToolkit#2700

[mdtauk]

Up and Down arrows should increment or decrement the value by a value the dev can set, but the default should be an int of 1

[adrientetar]

• wraparound min/max values is good e.g. if selecting an angle
• ability to add a suffix
• click the textbox and drag up/down to change the values, Adobe XD has this in the number inputs.

[xyzzer]

My implementation in WinRT XAML Toolkit also supports drag up/down to change values and it makes it much more usable when using with mouse than clicking buttons in certain scenarios.
https://github.com/xyzzer/WinRTXamlToolkit/tree/master/WinRTXamlToolkit/Controls/NumericUpDown

[SavoySchuler]

Hello, @sonnemaf , @ArchieCoder, @robloo, @mdtauk, @adrientetar, and @xyzzer! I have been assigned to this proposal.

First, thank you, @sonnemaf, for submitting this. I showed it at Microsoft Build 2019 last week and it received cheers from the audience! The community response here in the comments also reflects the excitement we have to see NumberBox happen.

I have read through everyone’s comments and updated the scope section to reflect the input received. I would appreciate it if everyone could take a chance to checkout this small update and let me know if I have not accurately captured your requests, noting that some details (such as formatting localization) will be handled at the spec level.

[ArchieCoder]

Hi @SavoySchuler,

This week, I'm working on accessibility feature on my app. This would be a plus if accessibility would be handled correctly with the new control for example, the increment can be said out loud instead of "plus", "minus". The rest seems fine to me.

[mdtauk]

Ensuring narrator is able to read out the values properly so it is clear what is happening is important.

Not sure if the Xbox controller will need any focus tapping to ensure the analog sticks and D-Pad will function correctly

[xyzzer]

Small correction - drag to increase/decrease should work on the text field itself until it is activated. IIRC in my implementation I had to put some transparent overlay on top of the text field to enable it and also hide the mouse cursor while dragging so that borders of the control or screen would not limit the drag distance and that when you're done dragging and I show the cursor again - it shows up where it first disappeared.

[sonnemaf]

@SavoySchuler you got a nice task. I can live with your scope. Calculator is a nice to have (WinUI 3.0 or 3.1). I have developed in many desktop environments (VB6, WinForms, WPF and UWP) and always missed a NumberBox. Finally we will get it.

Maybe you can also add the mouse scroll wheel for Up/Down. Blend for Visual Studio supports this.

I also love Drag-to-change, something I used a lot in Expression Blend.

I'm not sure what input validation will do and not do. Will it only be min/max or also limit keyboard (letters a-z, etc)? Will it handle Pasting invalid numbers?

I would love to read the full specs.

[SavoySchuler]

@ArchieCoder, I hear you loud and clear. Accessibility is a priority and its best handled upfront. I have started an Accessibility and Inputs section on this proposal where I have added your note.

@mdtauk, great question as always. I have added this to the Accessibility and Inputs section as a note to look into it.

@xyzzer, you're right. When reorganizing, the scope list, I grouped Up/Down buttons and drag-to-change as related functionality. Upon re-reading it did appear as though I was suggesting drag-to-change be a feature on the buttons. I have moved drag-to-change to its own section to provide clarity.

@sonnemaf, awesome. I will post a link to the spec as soon as its opened, which will likely be today or next week. Please feel encourage to join me in writing it! Until then, I've added scroll-to-change to the scope here.

All, With a note on calculator support - I believe in the value. I am working with my team to figure out if it is something we should modularize in the case the functionality could be leveraged further in the platform. Additionally, there is the question of how far do we go with calculator support? Would simple order of operations on +-/* do? Or something more comprehensive such as connecting to some kind of wolfram alpha service? Exploring a modular route could perhaps allow us to start with the more basic case while not blocking opportunity for a more comprehensive form of calculator support. I would be interested to know everyone's needs here.

For input validation, I have the same question. Does min, max, no letters, and no invalid pasting cover it?

[ArchieCoder]

I find the calculator feature cute, but practically how is this feature be discovered by a user? Is there going to be a little widget hint about this?

[SavoySchuler]

@ArchieCoder, do you think faded custom placeholder text in the NumberBox could appropriately prompt a user? If so, I imagine a string such as "a + b - c" or "enter equation" could be succinct ways to deliver that information. Excel has also created a standard with "=" appearing at the start of an equation. Perhaps once the user clicks the NumberBox, an immutable "=" appears at the front that the user then types behind?

We do have ToolTip or the heavier TeachingTip for guidance at the app level that we could ask developers to rely on, but my strong preference would be to solve this within NumberBox itself.

I'm interested to hear your thoughts here!

[ArchieCoder]

Placeholder would be indeed a good way as long as other context is not required due to the space limitation. I would think a NumberBox width will be smaller than a textbox for example.

[xyzzer]

Unless the control supports nullable numbers - it will always show a value, so there won't be space for a placeholder string inside of it.

…

On Fri, May 17, 2019 at 10:14 AM ArchieCoder ***@***.***> wrote: Placeholder would be indeed a good way as long as other context is not required due to the space limitation. I would think a NumberBox width will be smaller than a textbox for example. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#483?email_source=notifications&email_token=AANMBMAL7LUOVPIM55PYO4LPV3RWPA5CNFSM4HA4PBNKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODVVKWTI#issuecomment-493529933>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANMBMBKHP7GP5WUHLPWNZLPV3RWPANCNFSM4HA4PBNA> .

[SavoySchuler]

@ArchieCoder, looking as @sonnemaf 's examples (thank you again for these), any NumberBox that is not wide enough to display placeholder text for "a + b - c" would also not be wide enough to create a recommended user experience for entering equations into. In that respect, I would imagine this solution option is still viable for this purpose. However, I do think you're tapping into an area we have not addressed yet - scenarios where we want a compact NumberBox/only a simple number to be entered. I imagine Calculator support would need an API for disabling it, in which case we need not concern ourselves with long placeholder text nor breaking min space constraints the equation form of NumberBox would otherwise need - though some placeholder text option for compact mode may still be nice, even if its just for something like "#" or "e.g. 2".

@xyzzer, thanks for bringing this up. Let's make sure this is even the right user experience first and we can figure out the implementation from there! There's no need yet to cap our search for the right user experience due to technical limitations that we may be able to mitigate. ☺️

[SavoySchuler]

I have a higher priority question for everyone:

Would you rather have a NumberBox control that consolidates these features independent from a standard TextBox or would you rather have these features baked into TextBox as native capabilities that could be activated through APIs or InputScope?

(@sonnemaf, @ArchieCoder, @robloo, @mdtauk, @adrientetar, and @xyzzer)

[mdtauk]

It is a significant change to put all this into a TextBox control.

The validation for characters entered.

Using the correct keyboard layout with the InputScope

The differing mouse behaviours.

The ability to display spinner buttons as in the FabricWeb version.

If all of these things could be added, with a behaviour enum to define the TextBox type, without having an impact on everyone else currently using a TextBox in their app, then good.

And you could even consider combining other TextBox behaviours like an icon that could represent search or calendar which acts like a button. Masks for things like IP addresses or URLs which display "http://" in the style of placeholder text as you enter in text beside it.

FabricWeb has a wide variety with their TextFields.

https://developer.microsoft.com/en-us/fabric#/controls/web/textfield

https://developer.microsoft.com/en-us/fabric#/controls/web/spinbutton

[Felix-Dev]

I'd definitely go with an own NumberBox control instead of baking all these features into a TextBox control (similar to how there also is a PasswordBox control and not a TextBox with an input-mode "password").

The NumberBox control will be much more than a simple input field for IP addresses, for example. It will come with its own accessibilty/unique scroll & drag features, calculator support,... all which will distinguish it quite a lot from how I normally have used a TextBox so far (cases as simple as specifing a representation name for a group of data). And as even more special features/requirements will get proposed for the NumberBox control we can keep a nice and clean separation between both NumberBox and TextBox.

That spearation would also come down in the documentation and the app xaml layout (NumberBox more easily detectable than, say, a TextBox with a bunch of properties with one of them specifying the input mode). Instead of reading the TextBox documentation about its numeric input capabilities, that part would be nice and tidy in a specific NumberBox control documentation (just like with PasswordBox today).

[mdtauk]

@mdtauk, Adding the degree symbol would be possible with an INumberFormatter2 -- that's another good reason this needs to be kept generic. You can do whatever is necessary to convert a number to a string and pass the string back to the control.

For wrapping, actually that's what the IsWrapEnabled property is for... I need to read the end of the documentation next time.

Bottom line I think we can do everything you want with the existing API.

I know the Min, Max, Wrap, handles it, but are Degrees common enough to have an explicit Angle mode for the box? And should it display the symbol in the TextBox Text, while the internal Value is just the number.

[mdtauk]

@teaP Looking at the new Compact SpinButtonMode, would it be possible to add a show and hide animation to the overlayed Spin Buttons?

Also have you considered adding Acrylic to this, to better match ComboBoxes and other form fields with flyout elements?

Edit: It would fix this issue of visibility in the Dark Theme. Is the intention to match the focused colour of the TextBox or matching the current theme colours? Eitherway, Acrylic solves this.

[SavoySchuler]

@SavoySchuler, will you open a new PR for the spec? Also, did you take note of what I write in this comment particularly around NaN display? Thanks.

@adrientetar for sure. When NumberBox is empty, Value will be set to NaN (as you have requested) and PlaceholderText will show.

[SavoySchuler]

@SavoySchuler Some comments on the spec/NumberBox code so far. Hopefully, comments to this can end up in the spec/documentation too. Overall, it's great to see this coming together!

StepFrequency

Using the word 'Frequency' here just doesn't sit right with me. In the Slider control TickFrequency makes sense because the ticks are calculated and shown on a modulus of the overall max-min range. However, in this control, it's just the increment/step size. It's more of a 'StepAmount' or 'StepValue' -- better yet just 'Step' similar to 'Minimum' instead of 'MinimumValue'.

I have shared this feedback with @MikeHillberg and we are talking about it now. To be self-documenting among all the other properties here, we're considering something along the lines of "SpinButtonStep" should this reasoning be justification enough to deviate. I'll let you know. Thanks for raising the point!

Also, will the user be able to input a value that is outside of the defined Step?
For example Minimum = 0, Maximum = 6, StepFrequency = 2. Using the up arrow value will be {2, 4, 6} fair enough. Can the user type 0.5 as a valid value though? Or will that be rounded to 0 or 2?

The user can enter any numerically or legally formulaic input they like. See the formatting section for an example on how to use the NumberFormatter property to then coerce that input to your configured formatting.

The SpinButton will only increment or decrement that value by the defined SpinButton step size (API name now pending). So be sure you configure formatting and a step size that play together nicely.

The rounding strategy used is defined via your formatting. To expound on the DecimalFormatter example, here is an example of a rounding property that you can configure.

Rounding

How is mathematical rounding handled? This is especially important when inputting Currency values using expressions. We need to be able to specify -- or provide -- custom rounding after an Expression is calculated. HalfAwayFromZero is what I'm looking for to start but other rounding modes should be allowed as well.

Rounding is handled through formatting. Here is an example of a rounding property that can be set for DecimalFormatter. I will add an example in the Guidelines to help make this more clear. Thanks again. 😊

Localization

Please confirm that NumberBox will accept any INumberFormatter/INumberFormatter2 implementation -- and will continue to do so in the future (that's how it's implemented in code, I just want to make sure the spec calls it out too). That should allow for full control over localizing the text as compared to using an existing CurrencyFormatter/DecimalFormatter. It's great we have a solution for this!

That's the intention of the current implementation. As for guarantees of future-proofing, NumberBox will continue to have a solution for localization and formatting needs. For now and for the foreseeable future, we have that implemented.

Text Wrapping

Edit: I should read the whole spec next time.

Why have you created a new 'IsWrapEnabled' property? This goes against the TextBox/XAML convention of using TextBlock.TextWrapping and the TextWrapping Enum. Is it because you feel the term 'Text' doesn't apply very well to a NumberBox?

Also, I understand perhaps both Wrap and WrapWithOverflow are implemented the same but then just allow both enum values to be equivalent and describe the functionality in the documentation. Creating a new property here just means we need new value converters, etc... there is no reason to break an existing convention I think.

Correctly Handle KeyboardAccelerators

Please make sure this control supports using keyboard accelerator better than the TextBox does. Perhaps that cannot be done until/if TextBox is fixed, but #1435 is really a problem for me that causes lots of ugly work arounds. The TextBox will handle a 'Ctrl+V' paste itself and then any KeyboardAccelerator will be raised. However, there is no way within the KeyboardAccelerator to know that the TextBox just did its own thing.

NumberBox contains a TextBox and adds properties and configurations on top. I'll tag @jevan as he might have a more comprehensive understanding, but my intuition is that this might need to be fixed on the TextBox level.

---

All in all, awesome feedback @robloo! I appreciate the time you took to help make sure we are as comprehensive and complete with V1 NumberBox as we can be! Please let me know if you have any more questions. 😊

[SavoySchuler]

@mdtauk

A quick thought. Should there be an Angle Mode which would append the degree glyph to the value (and any logic for the 360° wrap around)

°

Or would this appendage be better handled in the future with my Suffix proposal for the TextBox #784

So far, NumberBox does not support display of any non-numeric characters (as even formulaic characters are removed on evaluation of expressions).

I think your proposal for #784 is by far the most comprehensive for our platform. If that proposal does not get acted upon, it strikes me as an appropriate V2 feature NumberBox as a fallback.

We're already planning on a V2 to release alongside or shortly after WinUI 3.0 as two of the highly requested input validation modes for NumberBox are blocked on needing WinUI 3.0. So I'll be opening a V2 issue after V1 goes live and I'll try to be sure to note this there as well.

[jevansaks]

To be self-documenting among all the other properties here, we're considering something along the lines of "SpinButtonStep" should this reasoning be justification enough to deviate

I see that StepFrequency is what Slider uses, so I think we were trying to be consistent with that terminology. Don't forget that it isn't just for spin buttons but also for the dragging and UIAutomation provider change values.

[SavoySchuler]

@robloo and @mdtauk, I should have read further into the thread before replying about °. I do not believe it is currently supported to have this symbol show inside Text as NumberBox keeps Text and Value tightly in sync so for the purpose of allowing you as developers can grab which ever type you need without the overhead of conversion. I didn't see a way to achieve this through the formatting properties available, but if you know a way, please let me know!

We're getting right up against the V1 release now, but for V2 we will take a look again at prefix/suffic/special characters. In the mean time, I believe @mdtauk's proposal for #784 is the most comprehensive solution that has been put forward for the platform so far. Please give that proposal a thumbs up and a comment if this is a feature you need.

[SavoySchuler]

@adrientetar, scroll-to-change made it in for V1 but drag-to-change was delayed to V2. As we're still looking to complete those features, we have not yet made it around to discussing your request that Shift+Up/Down step in unites of 10 and Ctrl+Shift+Up/Down step in units of 100.

Could you give me more context on the scenarios you would use this feature in? How do your users know this is available? Can you help me understand why this should be default (or at least available) in all NumberBoxes as compared to implemented locally in your solution?

[robloo]

@SavoySchuler

Thanks a lot for your comments.

To be self-documenting among all the other properties here, we're considering something along the lines of "SpinButtonStep" should this reasoning be justification enough to deviate

I like that terminology a lot, I missed that Slider has the StepFrequency property already though. Since that's the case it doesn't make sense to deviate from convention as @jevansaks stated.

Rounding is handled through formatting. Here is an example of a rounding property that can be set for DecimalFormatter.

Let's say the user enters "1 / 3" in the NumberBox. Is the following sequence then correct:

• At loss of focus / enter the expression will be evaluated and the double value of 0.33333333...34 will be calculated
• The 0.33333333...34 will be passed to the DecimalFormatter
• The 0.33333333...34, depending on your settings, could be rounded to "0.30" (just to be difficult)
• That "0.30" value will then be put in the TextBox for display to the user
• The double Value is now {0.33333333...34} and the Text value is now "0.30"
• Reading the double Value will NOT return the rounded number that is displayed in Text
  (Or is the decimal formatted value somehow parsed again after conversion to a string? and then the whole thing re-evaluated?)

I'm also concerned that Value and Text properties are so tightly coupled internally. The documentation doesn't define this coupling and if it's not highly structured two-way dependencies are never fun.

I'm not sure how this is implemented internally quite yet, but it seems the correct way to do this would be to treat the double Value as the only real property. Text is just a formatted version of Value. Then the developer would be able to format the value however they want for it to be displayed in the TextBox and the Text property (we would get the degree symbol or the feet/inches symbols previously asked for). That wouldn't be difficult to do at all if everything is already internally driven by the Value property. Textual input from the user is not kept anyway and would only be used to recalculate Value which is then formatted again for display.

Sequence should be:

• User Textual Input -> Parser -> Double Value -> Formatting -> Text

Changing the Text value from code would be as if the user inputted some text. Changing the Value directly would just go through the Formatting and the Text step.

To keep the rounding accurate between Value and Text sequence would be more like:

• User Textual Input -> Parser -> Value -> Rounding -> Value -> Formatting -> Text

Edit: To implement rounding in the expression/input parser and evaluation engine (whatever it's called), you would probably need to add a new property to define the algorithm like RoundingAlgorithm. That enum is already defined in Windows.Globalization.NumberFormatting as you pointed out. INumberFormatter2 should be used for formatting and nothing else -- again keep the stages decoupled between calculation and finally displayed text.

[mdtauk]

@adrientetar, scroll-to-change made it in for V1 but drag-to-change was delayed to V2. As we're still looking to complete those features, we have not yet made it around to discussing your request that Shift+Up/Down step in unites of 10 and Ctrl+Shift+Up/Down step in units of 100.

Could you give me more context on the scenarios you would use this feature in? How do your users know this is available? Can you help me understand why this should be default (or at least available) in all NumberBoxes as compared to implemented locally in your solution?

One should be a Larger increment, and the other should be smaller - similar to nudging selected areas/objects in Adobe apps

[adrientetar]

Could you give me more context on the scenarios you would use this feature in?

It's great when you want to change a value with visual implications (for instance rotation of an object) but you're not sure how far you want to go. So it's good for visual design.

How do your users know this is available?

It's just a feature that modern tools have, e.g. Adobe XD, Framer...

Can you help me understand why this should be default (or at least available) in all NumberBoxes as compared to implemented locally in your solution?

I think it's good to have this when you're on a touch device, that's a convenient way, tap-drag, to tweak a given value (kinda like phone time chooser widget where you tap-drag to scroll the values).

[eugenegff]

One should be a Larger increment, and the other should be smaller - similar to nudging selected areas/objects in Adobe apps

RangeBase has properties SmallChange and LargeChange. We at BeLight Software in our version of NumericUpDown are derived from RangeBase and change value by SmallChange using ArrowUp and ArrowDown shortcuts, and by LargeChange using PageUp and PageDown shortcuts

And we are not alone here,
https://help.syncfusion.com/uwp/numeric-updown/gestures
https://docs.telerik.com/devtools/wpf/controls/radnumericupdown/features/navigation

[tbolon]

Just one remark regarding the keyboard numeric keypad which came to my mind during the community call...

In most apps, the "." keypad button is still mapped to the "." character, which is different from the decimal separator when using a non english language (for example "," in French). So when you press the "." key in notepad, it writes a "." characther.

Some apps (Excel is the most known about that) change this key behavior to reinterpret any key press on the keypad "." as a decimal separator input. It's more compatible with the "calculator" design of the keypad.

The Calculator app also rewrite the "." press to interpret it as a decimal separator character.

Because the numberbox will be allowed to work more as a "calculator", could the control allow to use the "." key in the keypad as a decimal separator ? Or at least provide a way for the developer to add this feature without having to fight with key filters and events ?

Perhaps a property could allow to enable (if opt-in) or disable (if opt-out) the feature. Such as KeyPadDotAsDecimalSeparator="false" ?

[SavoySchuler]

V2 NumberBox Proposal: #1736

Hello wonderful WinUI Community! Thank you sincerely for helping us drive home our first community proposed control to see release. We know this was a huge undertaking and that all of you invested a significant amount of time into crafting the best collection of V1 features we could design together.

We also know that not everything made it into the V1 release. Some highly desired input validation configurations are dependent on WinUI 3.0 feature work, some desired feature needs surfaced late in validation/application, and some features we knew would be better explored after the V1 release.

We are looking to finish out our intended NumberBox feature work with a WinUI 3 release. I've opened an issue for collecting feedback on needed features that are missing from V1. If NumberBox is missing something you need, please be sure to drop a comment here: #1736

[heartacker]

can anybody tell me how to hide to x button in Number Box or TextBox

TextBox:

NumberBox