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.