Microsoft-ui-xaml: Proposal: NumberBox V2 for WinUI 3.0

[SavoySchuler]

Proposal: NumberBox V2

Summary

Finish up NumberBox feature work that was blocked on WinUI 3.0 or did not make the V1 cut.

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: https://github.com/microsoft/calculator/issues/453

Scope

| Capability | Priority |
| :---------- | :------- |
| Add text and icon warning input validation modes. | Must |
| Add TextAlignment property to NumberBox | Must |
| Drag-to-change | Should |

Open Questions

• Is it interesting to provide configurability of the calculation engine, or make the engine available for general-purpose expression parsing? For example, should it be enabled that the developer could plug in something that routed the expression to wolframalpha.com and handed back the resulting value?

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

[shaheedmalik]

I like the second one.

[mdtauk]

You already have the validation and calculation preview ideas listed

---

How about adding a Mini Calculator popup with a Calculate icon for more complicated calculating scenarios?

---

Also more options for positioning the Spin Buttons could be considered

---

And then consideration for how the Spin Buttons would work with possible future Prefix, Suffix, Masking Textboxes if that proposal #784 is implemented (as is possible with FastDNA and Fabric Web)

[sonnemaf]

@mdtauk I really like the Mini Calculator idea. I had this 20 years ago in Smalltalk.

The Prefix and Suffix are also very nice (Must have). I'm not sure about the Masked one. That would be a nice to have.

[sonnemaf]

Maybe there should also be an IsReadOnly property. Similar to TextBox. In turned on the spin buttons should hide.

[sonnemaf]

Should the NumberBox prevent alphanumeric keyboard input when AcceptsExpression is turned off. You can then only enter 0-9, minus, dot and a comma.

Take extra care about pasting a new from the clipboard.

I'm not sure about this feature. It should be an optional thing. I'm also not sure if this would introduce extra localization issues.

[lhak]

Some features that could be added:

• If the input has been modified, pressing the TAB key will set it as the new value. Add a property to control this behavior, i.e. allow the modified input to be discarded in this scenario.
• An event that fires if the modified input has been discarded by pressing the ESCAPE key.
• Make it possible to add tooltips to buttons.

[robloo]

I'm definitely behind:

• TextAlignment
• IsReadOnly
• Prefix/Suffix (I would use for currency codes or symbols)
• Spin buttons separated on both sides of the control like in OneNote UWP (Realize that was already shot down in the last discussion)
• Calculated preview (Not to be confused with the mini calculator. A mini calculator would be too heavy for this control I think)

@sonnemaf I also brought up ignoring anything other than numeric key presses. However, that was widely shot down as it is against the platform conventions Discussed here. I would be behind this though if you can convince Microsoft :)

[harvinders]

@SavoySchuler
Can we also add support for conversion from one unit of measure to another by selecting a drop down unit of measure? It would be a great addition for engineering focused enterprise application development.

Something like what @mdtauk proposed

Say a number box is displaying a value of 100 with unit of measure of L/min for flow. One maybe interested in looking at the same value as 1.66 with L/sec or 0.001666 with m3/sec.

[mrlacey]

Can we also add support for conversion from one unit of measure to another by selecting a drop down unit of measure? It would be a great addition for engineering focused enterprise application development.

That seems specialized for a general purpose control.
A text box with integrated combo box also seems to go beyond being specific to numbers too.
If such functionality was added I'd recommend an event (or command-obvs) when the combo box item changed and then making updating the value based on the selection change be something the app is responsible for. If this was down to the control, there's a high risk of split application logic (some in the app/vm and some in the control) and a lot of potential complexity needed in the control to handle a variety of scenarios that would need to be accounted for.

[adrientetar]

One important thing is being able to customize value↔text conversion. For instance I have a use-case where I would like to display a NumberBox with three-digits zfill (e.g. 3 becomes 003) and I don't think it's currently possible.

[robloo]

@adrientetar Yes! The internal processing needs to be more explicitly defined in the spec and allow for customization. I made that comment here. Formatting should be overridable with an OnFormatting method for derived controls and by default use the specified Globalization.NumberFormatting. This also allows special formatting like showing feet and inches while the actual Value is fractional feet.

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

We should also switch Value from type double to double? and make the default null. That is important to fix the two-way binding issues.

[chingucoding]

We should also switch Value from type double to double? and make the default null. That is important to fix the two-way binding issues.

I think a more flexible solution is leave it double, have the default fallback be NaN (as it seems to be now) and have a property defining the default value/fallback value to let developers also have a NumberBox which is guaranteed to have a valid value, instead of having to implement custom checks.

double? may be problematic as it is may not be available in all languages in which WinUI can be programmed in.

[robloo]

@SavoySchuler In the call today about NumberBox you basically said a production-ready version of NumberBox won’t be complete until after WinUI 3.0 -- expected by the end of 2020. That means there are a lot of apps that either won’t use NumberBox or will ship with several little issues that when taken together add up. I'm thinking it would take a few developer weeks to get the NumberBox to production quality. That shouldn’t be a problem if there are more than a handful of developers working on WinUI. Is there anything you can do to prioritize this?

You also mentioned type/default value and all the discussions you had internally to choose the type making it a compromise with all languages/tooling. That statement is not saying a lot. We realize the type was chosen considering other languages/tooling. We want to know the details and technical limitations. As I also stated, CalendarDatePicker supports nullability so we have a Microsoft example which is a contradiction to your statement. This is all coming up because NumberBox crashes with two-way data binding... I would feel a bit guilty if I shipped a control that had issues like that.

Known NumberBox issues that need to be fixed to get the quality up to standards are:

1708

1721

1839

1846

1852

1853

1854

[MikeHillberg]

@robloo, some background on Nullable support ... The issue is that Xaml markup used to have a bug in the support for Nullable-typed properties, except on in-box controls. It was fixed in version 17763 (Windows 1809). To allow NumberBox on older versions (I think down to 14393/1607) we picked a different sentinel value (NaN).

[robloo]

@MikeHillberg, thanks a lot for the information. NaN did originally make sense for the default/unset value. However, I think everyone overlooked NaN != NaN which causes the binding stack overflow when being set. It's not like I want to support null -- it's just the only way to fix this correctly that I can think of. For that reason I think the Value backing type needs to be re-evaluated.

Also, WinUI 3.0 certainly will remove the restriction on using nullable types in older versions of Windows. It might make sense to restrict NumberBox to supported, newer versions of Windows until WinUI 3.0 is released. It wouldn't be different than a lot of the other existing controls.

[Poopooracoocoo]

If there isn't already, it would be nice to be able to make the spin buttons stack like this (maybe on devices that only have a mouse & keyboard?):

[SavoySchuler]

@SavoySchuler In the call today about NumberBox you basically said a production-ready version of NumberBox won’t be complete until after WinUI 3.0 -- expected by the end of 2020. That means there are a lot of apps that either won’t use NumberBox or will ship with several little issues that when taken together add up. I'm thinking it would take a few developer weeks to get the NumberBox to production quality. That shouldn’t be a problem if there are more than a handful of developers working on WinUI. Is there anything you can do to prioritize this?

Apologies, I missed this discussion taking off here too. The first thing I want to do is clarify: what I intended to say is that the full feature set promised for v1 NumberBox won't be available until WinUI 3. This is because input validation was moved from WinUI 2 to WinUI 3 _after_ we had defined our intended NumberBox v1 feature set, of which input validation is a part of. I know how desired integrated input validation is for everyone, so we won't consider v1 feature complete until input validation is included. 🙂

You also mentioned type/default value and all the discussions you had internally to choose the type making it a compromise with all languages/tooling. That statement is not saying a lot. We realize the type was chosen considering other languages/tooling. We want to know the details and technical limitations. As I also stated, CalendarDatePicker supports nullability so we have a Microsoft example which is a contradiction to your statement. This is all coming up because NumberBox crashes with two-way data binding... I would feel a bit guilty if I shipped a control that had issues like that.

Known NumberBox issues that need to be fixed to get the quality up to standards are:

1708

1721

1839

1846

1852

1853

1854

With and exception of #1853, 1912, and #1925, and #1978 (which just opened), I believe we have this issue you called out, and all other bugs listed here, resolved. The first few fixes are going out with this release which went live today, and more will follow! 😄

I just audited the list of open NumberBox bugs and request to ensure this. Shout out to @teaP for helping make this list dramatically shorter than it was a month ago! You rock!

@robloo If I missed _anything_ please let me know.

New Feature Requests

Thank you, EVERYONE, for your patience while we worked to clean up these bugs! I have to get headed home tonight, but I will be back in Tuesday to begin evaluating these awesome features you have proposed and response will come. Your ideas are fabulous and I want to give them justice with careful consideration and responses on my part. 🙂

Thanks again and enjoy the weekend!

[robloo]

@SavoySchuler @teaP It's awesome to see the last few updates to NumberBox following the initial release. Thank you both so much for going through the open issues! The control is in a much better state of usability now and I'm glad it was not abandoned until WinUI 3 :)

[robloo]

I attempted to integrate NumberBox into a production control. I ran into a few show-stoppers that ideally would be addressed in NumberBox v2.

2055 Proposal: Add Paste, CopyingToClipboard, and CuttingToClipboard Events to NumberBox

https://github.com/microsoft/microsoft-ui-xaml/issues/1721#issuecomment-593731932

I keep saying this, but it's imperative for a number of things that the flow of data between Text<->Value is clearly defined and coded. This would address a number of things. My suggestion again is this:

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

[robloo]

Proposal: Support Hex Display and Input in NumberBox #2757