search

microsoft / microsoft-ui-xaml

Windows UI Library: the latest Windows 10 native controls and Fluent styles for your applications
MIT License
6.26k stars 673 forks source link

Proposal: Provide lightweight styling resources for the glyphs of the NumberBox's spin buttons #2789

Open Felix-Dev opened 4 years ago

Felix-Dev commented 4 years ago

Proposal: Provide lightweight styling resources for the glyphs of the NumberBox's spin buttons

Summary

Currently, the glyphs used for the spin buttons of the NumberBox control cannot be easily changed: https://github.com/microsoft/microsoft-ui-xaml/blob/865e4fcc00e8649baeaec1ba7daeca398671aa72/dev/NumberBox/NumberBox.xaml#L152

In order to avoid having to re-template the control or walk the visual tree to change the appearance of these spin buttons, I propose the following theme resources to be added:

See the XAML markup below for an example:

<Application.Resources>
    <x:String x:Key="NumberBoxSpinButtonUpGlyph">&#xE948;</x:String>
    <x:String x:Key="NumberBoxSpinButtonDownGlyph">&#xE949;</x:String>
    <x:String x:Key="NumberBoxPopupIndicatorGlyph">&#xECE8;</x:String>
    <x:Double x:Key="NumberBoxPopupIndicatorFontSize">17</x:Double>
</Application.Resources>

This gives us the following resulting UI:

NumberBox SpinButtonPlacementMode - Inline

image

NumberBox SpinButtonPlacementMode - Compact

image

image

The theme resource NumberBoxPopupIndicatorFontSize is needed here because the custom popup indicator glyph would be too small to identify comfortably with the default FontSize of 12: image

Rationale

Enable developers to easily style the glyphs of the spin buttons without having to re-template the control.

Important Notes

The theme resources NumberBoxSpinButtonUpGlyph and NumberBoxSpinButtonDownGlyph would have to be set on the app level to take effect in SpinButtonPlacementMode::Compact as they are inside a popup control then.

StephenLPeters commented 4 years ago

@SavoySchuler and @teaP FYI. I think these make sense :)

Felix-Dev commented 4 years ago

@StephenLPeters Should I wait for more input here or can I create a PR?

StephenLPeters commented 4 years ago

My vote is we do it, @SavoySchuler @chigy might want to input. Should we also consider adding resources for the glyph foreground?

Felix-Dev commented 4 years ago

Should we also consider adding resources for the glyph foreground?

I am currently tracking those theme resources in issue https://github.com/microsoft/microsoft-ui-xaml/issues/2844 I.e.:

* NumberBoxPopupSpinButtonUpBackground + ["", PointerOver, Pressed, Disabled]
* NumberBoxPopupSpinButtonUpForeground + ["", PointerOver, Pressed, Disabled]
* NumberBoxPopupSpinButtonUpBorderBrush + ["", PointerOver, Pressed, Disabled]
* NumberBoxPopupSpinButtonDownBackground + ["", PointerOver, Pressed, Disabled]
* NumberBoxPopupSpinButtonDownForeground + ["", PointerOver, Pressed, Disabled]
* NumberBoxPopupSpinButtonDownBorderBrush + ["", PointerOver, Pressed, Disabled]

We could "merge" both issues and create a single PR covering them or just tackle them one-by-one (so no issue would be blocked by the other potentially waiting for the resolve of open questions).

chigy commented 4 years ago

I do not quite understand the benefit of suggestion to update the glyph from up/down button to +/-?

Felix-Dev commented 4 years ago

@chigy This proposal is not about changing the default glyphs used for the NumberBox spin buttons. This proposal is merely about providing developers an easy way to customize the appearance of the spin buttons, if they so wish. I don't think having +/- glyphs in a scenario like this is all that uncommen. The NumberBox proposal itself used +/- in the intial mockups.

chigy commented 4 years ago

@Felix-Dev , we need to make sure our platform is predictable to our users. I am not sure making these glyph easily changeable would cause more user pain by having many different variations that user has to learn every time they encounter this control. I do believe the glyph should be customization but not sure if I feel compelled to make it easier because of the concern to add to our user's cognitive load.

Felix-Dev commented 4 years ago

I do believe the glyph should be customization but not sure if I feel compelled to make it easier because of the concern to add to our user's cognitive load.

So if I understand you correctly here, you want these glyphs to be customizable, yet you don't want that customization to be easy to use? In other words, developers/designers who want to use different glyphs here have to create a local copy of the NumberBox style frozen in time? I thought developers were the important customers of WinUI and we should provide them with friendly customization options for the inbox controls without requiring them to re-template the controls (which should be avoided whenever possible).

chigy commented 4 years ago

@Felix-Dev , sorry this fell through the cracks... What I am saying is that consistent use of glyph is very important to educate user and help user not have to learn and re-learn the functionality every time different app loads. If the app developer insists in updating the glyph, that's fine, but I want them to be responsible and maybe it may mean that they have to maintain code manually. In other words, benefit should outweigh the effort. Is it benefit the user that much by changing the glyph?

mdtauk commented 4 years ago

@Felix-Dev , sorry this fell through the cracks... What I am saying is that consistent use of glyph is very important to educate user and help user not have to learn and re-learn the functionality every time different app loads. If the app developer insists in updating the glyph, that's fine, but I want them to be responsible and maybe it may mean that they have to maintain code manually. In other words, benefit should outweigh the effort. Is it benefit the user that much by changing the glyph?

@chigy So a behavioural science approach. Nudge the developers to do the right thing, and not change the glyphs.

maxkatz6 commented 4 years ago

I believe it should use IconSourceElement internally with IconSource from static resource, so developer can override it with any other kind of supported IconSource without specific font-family limitation too. 

    <FontIconSource x:Key="NumberBoxSpinButtonUpIcon" Glyph="&#xE948;" />
    <FontIconSource x:Key="NumberBoxSpinButtonDownIcon" Glyph="&#xE949;" />
    <FontIconSource x:Key="NumberBoxPopupIndicatorIcon" Glyph="&#xECE8;" />

Or

    <BitmapIconSource x:Key="NumberBoxSpinButtonUpIcon" UriSource="../Assets/CustomUpIcon.png" />
Felix-Dev commented 4 years ago

@mdtauk

So a behavioural science approach. Nudge the developers to do the right thing, and not change the glyphs.

Using +/- for the increment/decrement buttons is, I'd argue, just as "right" as using up/down glyphs.

What I am saying is that consistent use of glyph is very important to educate user and help user not have to learn and re-learn the functionality every time different app loads.

@chigy I don't think this is an issue here. There are really only a select few different icon combinations which would make sense here (in fact, it is probably fair to assume that the vast majority of icons used here are either up/down chevrons or the +/- buttons). +/- buttons have been used quite a bit in UIs to increase/decrease some values and users are familiar with them. They won't have to "re-learn the functionality every time different app loads" because the +/- buttons are strongly connected to the notion of increasing/decreasing values. (The fact that there also were used in the NumberBox proposal supports this as well).

If the app developer insists in updating the glyph, that's fine, but I want them to be responsible and maybe it may mean that they have to maintain code manually.

Again, swapping out up/down chevrons with +/- is a reasonable change because +/- is well-connected to increasing/decreasing values. Of course, the developers could set glyphs which are entirely unfamiliar to a user here but that would result in user dissatisfaction and probably cause them to change their glyphs. For example, just because we expose control colors via theme resources, developers don't just suddenly "become irresponsible" and set foreground/background color combinations which make the UI elements barely discernible. They could do so very easily by just overriding theme resources, yet I am not suddenly seeing a bunch of apps which are "misusing" this power. Instead, what we do provide developers here is a simple and maintainable way to modify the appearance of the existing WinUI/UWP controls to create the app UI they know is best for their product and userbase - and not what some folks at Microsoft think is best in their app context (just to clear here - I mean no disrespect with that).

In other words, benefit should outweigh the effort. Is it benefit the user that much by changing the glyph?

As said above, +/- buttons are well used here to increment/decrement values. Picture developers who have existing apps and want to use WinUI going forward. However, WinUI's NumberBox doesn't have a nice way to change the glyphs used for its spin buttons. So, an app which today uses +/- buttons suddenly uses different UI symbols. To keep the existing glyphs, WinUI currently forces the developers to re-template the control, which will just add more development cost down the line (for example having to regularly check if they need to update the control template again).

I will end this with some articles I found after doing some quick research:

I will add a quote here from the article above so that this won't be missed by folks:

Use +/- or arrow up/down as the button visualizations. For horizontal steppers, plus and minus signs usually work best as labels for the step segments. For vertical steppers (with segments above and below the value), you can also use arrow-up and arrow-down buttons, often visualized as chevrons.

(I won't claim they are right or wrong. The purpose of this quote is solely to show that there is thinking/research out there making the case for +/- symbols to be used here.)

To sum it all up, @chigy, I'm not coming to the conclusion that +/- are perhaps more widely used than the up/down chevrons. I don't have enough data on that and this also not important to my reasoning here. What is important here is that a quick and simple research shows that using +/- glyphs instead of up/down chevrons is far from being uncommon. Chakra UI and Apple's UIKit for example recognize this fact and provide easy options to change the look of their glyphs. I strongly believe WinUI should strive to attract developers of all kinds of apps and if they and their users are accustomed to +/- glyphs, then WinUI should make it easy for these developers to make this change to the NumberBox UI. Lighweight-styling will give developers just this flexibility. Many developers won't suddenly use theme resources and create a NumberBox UI which is unfamiliar to users - this would be detrimental to the user experience of their apps because they will divert from the proven and user-expected UI of this control on the market. I don't believe we have to be concerned here that suddenly users will be greeted with many unfamiliar-looking NumberBox UIs creating only confusion.

chigy commented 4 years ago

@chigy ... (in fact, it is probably fair to assume that the vast majority of icons used here are either up/down chevrons or the +/- buttons). ...

@Felix-Dev , if this is true, should this proposal really about providing developer option to swap chevrons with +/- buttons?

Also at minimum, there should be a guidance explaining what is recommended. Scanning through some of the guidance you shared, it didn't feel to me that anyone is talking about letting you use any icons but only about chevron vs. +/-?

Felix-Dev commented 4 years ago

if this is true, should this proposal really about providing developer option to swap chevrons with +/- buttons?

@chigy Edit: Scratch what I said about WinUI shipping with two NumberBox styles then (one using the up/down glyphs and the other using +/- glyphs). An API proposal like the below is also an option.

@maxkatz6 Out of interest, would you set the glyphs to anything other than up/down or +/- symbols? Or would you also at most change the fonts used to provide the up/down or +/- glyphs?

StephenLPeters commented 4 years ago

@chigy ... (in fact, it is probably fair to assume that the vast majority of icons used here are either up/down chevrons or the +/- buttons). ...

@Felix-Dev , if this is true, should this proposal really about providing developer option to swap chevrons with +/- buttons?

Also at minimum, there should be a guidance explaining what is recommended. Scanning through some of the guidance you shared, it didn't feel to me that anyone is talking about letting you use any icons but only about chevron vs. +/-?

I had a similar thought, after reading your argument I think that an API in the idl is probably warranted for switching between chevron and +- glyphs. Theme resources aren't very discoverable and it seems like this customization point should be front and center. Personally I think the harm in also including a resource that could be overridden to something else like 加 /减去 (google translate of plus/minus in mandarin) is low and adding it makes sense to me

Felix-Dev commented 4 years ago

@StephenLPeters @chigy Interesting, I only thought about providing two different NumberBox styles and having to maintain them as a consequence (outside of using theme resources)....

Would an API essentially look similar to an API like the TabView.CloseButtonOverlayMode API and provide a set of values like this?

public enum NumberBoxSpinButtonGlyphMode
{
    Auto = 0,
    UpDown = 1,
    PlusMinus = 2
}

public class NumberBox
{
     public NumberBoxSpinButtonGlyphMode SpinButtonGlyphMode { get; set; }
}

where using NumberBoxSpinButtonGlyphMode.Auto makes sure the app will always use the current WinUI glyph standard for the NumberBox (similar to the linked TabView.CloseButtonOverlayMode API above).

StephenLPeters commented 4 years ago

That is essentially what I pictured :), I think the API makes a custom icon case a little more confusing... would we expose both sets as resources, if both the icons are resources which one do you override to apply your custom one, but the complications seem manageable.

mdtauk commented 4 years ago

Adding an API seems a little OTT for what is essentially a Glyph FontIcon resource.

Plus and Minus glyphs make sense, alongside the chevrons, and the Chevrons should remain the default.

But if you have an API:

Then your have three states for these glyphs...

Do they share the Glyph resource, or does each require their own sets off glyphs and styles?

Felix-Dev commented 4 years ago

Compact (two small glyphs on to of each other, or a single Glyph with both symbols in optimised for the small size)

To add to what @mdtauk said here: If we decide to allow full glyph customization I think we should explore changing the PopupIndicator glyph in Compact mode then to be made up of two small glyphs (currently it is a TextBlock setting a single glyph) as that should make it a lot easier for developers to customize the SpinButton glyphs here. That way, developers won't have to create a custom glyph solely for the Popup indicator in compact mode and we could reuse their specified two glyphs here. (It could be that this "automated" approach might have some issues in some cases where a specifically made icon for that scenario would be better.)

Felix-Dev commented 4 years ago

The added API to enable full glyph customization could resemble the TabViewItem.IconSource API and look like this:

public class NumberBox
{
    public IconSource IncrementIconSource { get; set; }
    public IconSource DecrementIconSource { get; set; }

    public static Windows.UI.Xaml.DependencyProperty IncrementIconSourceProperty { get; };
    public static Windows.UI.Xaml.DependencyProperty DecrementIconSourceProperty { get; };
}

to be used like this:

<NumberBox>
    <NumberBox.IncrementIconSource>
        <FontIconSource FontFamily="Segoe MDL2 Assets" Glyph="&#xE948;" />
    </NumberBox.IncrementIconSource>
    <NumberBox.DecrementIconSource>
        <FontIconSource FontFamily="Segoe MDL2 Assets" Glyph="&#xE949;" />
    </NumberBox.DecrementIconSource>
</controls:NumberBox>

If no Increment/DeccrementIconSource is specified, the NumberBox will fall back to the default glyph for the respective spin button - one of the the up/down glyphs used today.

This will also enable the scenario @maxkatz6 was mentioning where developers might want to specify a BitmapIconSource for the glyphs.

Both API proposals would effectively address my main concern here ensuring developers can swap out the up/down chevrons with +/- symbols if they prefer. Now, it seems to me as if @chigy, @StephenLPeters and the rest of the team have to decide if they also want to enable additional customization (free reign for the developer) or keeping it restricted so that the common UIs are supported but "exotic" UI configurations are made harder to achieve (by "forcing" developers to re-template the control).

That being said, both APIs would require some engineering thinking about finding a clean implementation solution to style the popup indicator symbol in the Compact spin button placement mode. That UI part is currently not directly exposed in the NumberBox control template but resides in a custom TextBox style and the NumberBox swaps out the used TextBox style depending on the spin button placement mode: https://github.com/microsoft/microsoft-ui-xaml/blob/0d08c3bff927776002c0ba8f3d08524fd60f1f92/dev/NumberBox/NumberBox.xaml#L457

Additionally, as already mentioned by @mdtauk, it should be decided if the Popup indicator should consist of two independent icons which are stacked above each other or whether only a single icon is used. Today, a single icon is used as Segoe MDLS 2 Assets provides a nice icon for the up/down chevrons: image

The best icon I could find in Segoe MDL2 Assets for the +/- icons seems to be this one: image

This icon is probably not the best possible icon UI we could come up here. This would mean that if we decide to stick with the current popup indicator icon implementation (where we only specify a single icon instead of stacking two small icons on top of each other), the MS Design team should perhaps design a new Segoe MDL2 Assets icon (or a new Fluent UI font icon) for this special case for us to use here.

robloo commented 4 years ago

@Felix-Dev pointed out this discussion to me as it relates to #2998. I think we should be adding Style properties like AutoSuggestBox.TextBoxStyle in this scenario. Then the developer could completely swap out the style and template changing whatever is needed. It's possible the background/foreground color need to be modified instead of simply the glyph. It's also potentially necessary to adjust corner radius.

I also see the benefit in separating out resources to quickly change glyphs to +/- symbols.

dedaap72 commented 2 years ago

A bit late in the game but someone above asked the question why one would want to change the standard chevrons into +/- which would deviate from the standard. I actually have a scenario where this would make sense: imagine you use a NumberBox in a ListViewItem to indicate the item's order number in the list (ordered from low to high). The 'Up' chevron means increase the value in the number box, but that moves it down in the list, which to the user is counterintuitive. So changing the chevrons to +/- is one way to go around this (I actually solved it by not using the NumberBox but separate buttons, but using a NumberBox with custom glyphs would be an elegant solution here).

Fuahi commented 2 years ago

aa I really want a number box Like this

please