Feature Proposal: PagerControl

[SavoySchuler]

The WinUI Team has opened a Spec for this feature.

Proposal: New UI Pagination Widget

Summary

This widget would provide a customizable pager UI, generic states, and generic events that can be configured to navigate pages for several view controls.

Rationale

• Desired by community - tied with Make Grid Better for most engaged with issue on our repo.
• Desired by 8/12 MVPs in survey.
• Several UI teams actively interested in parallel development.

The absence of a standard UI pager control, last seen as DataPager in Silverlight, has been a pain point in both WPF and UWP that has forced a variety of unfavorable workarounds for developers. Inclusion of this control in UWP would resolve an ecosystem gap and enable developers to efficiently deliver UI paging experiences in their applications. Through XAML Islands, it may also provide an opportunity to benefit WPF developers working with DataGrid or ListView. The scope of this proposal is not provide a data paging solution at this time but to start with UI paging as a foundation on top of which data paging may be later integrated.

Requirements

#	Feature	Priority
1	Can support the option to have multiple display modes as the core navigation component (NumberBox, ComboBox, Button panel).	Must
2	Can have optional text and/or glyphic bookend navigation controls (First/Last, Next/Back, none).	Must
2	Can be used to page GridView, ListView, DataGrid, and ItemsRepeater.	Must
4	Support for non-data binding/indeterminate page count solutions.	Must
5	Designed to support later possible integrated data paging component.	Must

Important Notes

Here are how the three configurations could look:

ComboBox configuration

NumberBox configuration:

Button panel configuration:

Usage Examples

Using a button panel as the display mode.

<UserControl x:Class="DataPagerSample.MainPage">
   <Grid x:Name="LayoutRoot" RowDefinitions="*,Auto">
        <GridView x:Name="gridView1" ... />
	<muxc:UIPager x:Name="uiPager1"
            Source="{Binding}"
	    LastButton="AlwaysVisible"
            FirstButton="AlwaysVisible"
            NumberOfIndicesShowing="7"
	    EllipsisMaxBefore="5"
	    EllipsisMaxAfter="1"
            EllipsisShowBounds="True" />
    </Grid>
</UserControl>

Using an editable ComboBox as the display mode.

<UserControl x:Class="DataPagerSample.MainPage">
    <Grid x:Name="LayoutRoot" RowDefinitions="*,Auto">
        <GridView x:Name="gridView1" ... />
	<muxc:UIPager x:Name="uiPager1"
	    Source="{Binding}"
	    DisplayMode="EditableComboBox"
	    NextButtonText="Prev"
	    PreviousButtonText="Next"
	    PrefixText="Page"  
	    TotalNumberOfPages="10" />
    </Grid>
</UserControl>

Visual Components

Component	Notes
DisplayMode	* Used to set either a button panel (default) or an editable ComboBox as the indexing component. * When set to be a button panel, the number of visible indices can be specified.
LastButton	* Button displaying text and/or glyph indicating that the user may navigate to the last index. * Automatically disabled when at last index. * Can be set to not be visible when at the last index.
FirstButton	* Button displaying text and/or glyph indicating that the user may navigate to the first index. * Automatically disabled when at first index. * Can be set to not be visible when at the first index.
NextButton	* Button displaying text and/or glyph indicating that the user may navigate to the next index. * Automatically disabled when at last index. * Can be set to not be visible when at the last index.
PreviousButton	* Button displaying text and/or glyph indicating that the user may navigate to the previous index. * Automatically disabled when at first index. * Can be set to not be visible when at the first index.
Ellipsis	* Button, often reading "...", used between indexes and before or after the first/last index to indicate an accessible but omitted range of indexes. * MaxBefore and MaxAfter properties can be used to set how many indices appear between the current page and the ellipsis before/after it. * Visibility of the first/last index can be disabled. * Only visible when using button panel as the display mode.
PrefixText	* Text displayed before the editable ComboBox indexing component.
NumberOfPages	* When a total number of indices (N) is given, this suffix string will appear after the editable ComboBox indexing component and read "of N". Localization will put "N" where it should be in a given language.

Accessibility

State	Action	Narrator
UI pager is first focused on by tabbing	Focus defaults to the next page button if available (current page otherwise) after announcing accessible name of UI pager.	“Page selector. Next page is N."
UI pager is tabbed through	Tab Button: Will go through all actionable items in order without regard to groups. Arrow keys: Will be able to explore groups in the specified directions. Pressing the down arrow key at the bottom of the ComboBox will wrap the user to the top. Escape: Will escape UI pager. Enter and Spacebar: Will select the component focused on. Home: Will move focus to "go back" elements. In the ComboBox, it will jump the user to the first index. End: Will move focus to "go forward" elements. In the ComboBox, it will jump the user to the last index.	Narrator will announce an accessible name of the visual component. Ex: “first page button” “previous page button” “1st page” “current page” "page selection drop down menu: current page is 1”

API Surface Example

<PagerControl
    DisplayMode = { Auto | ComboBox | NumberBox | ButtonPanel }
    NumberOfIndicesShowing = { int }
    LastButton = { Auto | AlwaysVisible | HiddenOnLast | None } 
    LastButtonGlyph = { string }
    LastButtonText = { string }
    LastButtonStyle = { string }
    FirstButton = { Auto | AlwaysVisible | HiddenOnFirst | None }
    FirstButtonGlyph = { string }
    FirstButtonText = { string }
    FirstButtonStyle = { string }
    NextButton = { Auto | AlwaysVisible | HiddenOnLast | None } 
    NextButtonGlyph = { string }
    NextButtonText = { string }
    NextButtonStyle = { string }
    PreviousButton = { Auto | AlwaysVisible | HiddenOnFirst | None }  
    PreviousButtonGlyph = { string }
    PreviousButtonText = { string }
    PreviousButtonStyle = { string }
    EllipsisEnabled = { True | False }
    EllipsisMaxBefore = { int }
    EllipsisMaxAfter = { int }
    EllipsisShowBounds = { True | False }
    PrefixText = { string }  
    NumberOfPages = { int } >
</PagerControl>

Related

Proposal: Data Paging for PagerControl #268

[ryandemopoulos]

Made a few minor updates Savoy:

• Added a hyperlink to the WCT DataGrid control, since it's part of a separate library
• Updated the ""s and #s to be string and int respectively, in the code snippet
• Replaced ViewPager with PagerControl, to match the title.

[kmgallahan]

Great proposal.

I feel like with this display mode:

The First & Last buttons are redundant, so the default state could be None. That is assuming the first and last index are displayed by default, which seems to be the case: "Visibility of the first/last index can be disabled."

Regarding these open questions:

Should numerals in the button panel be replaceable with glyphs?

Seems to be a popular design choice, and I'd like to have the option.

Will some scenarios require the glyphs to not be clickable (buttons not needed and spacing may be narrowed)?

I'm sure some designers might want this option, but as a user I pretty much always dislike when I can't interact with them.

Should a timer and wrap-around feature be added?

Would be useful, but low priority IMO.

[michael-hawker]

I think it's important to highlight the 'not in scope' part in the rationale a bit better, as that was my first question/thought:

The scope of this proposal is not provide a data paging solution at this time but to start with UI paging as a foundation on top of which data paging may be integrated.

So, to clarify, this is a UI element only, but the developer is still responsible for manipulating the source to the GridView/ListView/etc... to make the pages work? It'd be good to provide a code sample here about how that's expected to be accomplished to see how this scenario would work end-to-end.

(Also, in the sample XAML, don't indent the pager control as it makes it look like it goes in the GridView component not next to it in the tree.)

[SavoySchuler]

@kmgallahan Great feedback, thank you! I agree it reduces redundancy to only have the LastButton/FirstButton or the range bounds visible. Upon reviewing several example implementations, it appears most actually have neither - which I will update the default behavior to be. I have left the redundancy of these optional components in the Usage Examples to help communicate what they are and how they look.

I agree that glyph panels are a popular design. I am not sure if I would if it would make more sense to have "GlyphPanel" as a DisplayMode, subclass of a pager parent, or just as an option to replace numerals with glyphs in the ButtonPanel DisplayMode. When you think of wanting to create a glyph panel for these kind of displays, are one of these options where you would think to start?

[SavoySchuler]

@michael-hawker Thank you for the great feedback! That is correct - by developing both sides of this solution as distinct but cooperative components, we can allow PagerControl to be more flexible for developers. I will refine this proposal with clear examples that show end-to-end solutions for these scenarios and I will tag you in a comment when new Usage Examples are posted. Thanks for the code catch, I have it updated!

[kmgallahan]

@SavoySchuler My initial thought was that a subclass would somewhat defeat the purpose of the DisplayMode property. However, looking over the properties & proposed features, it seems many of them would only be applicable to a particular display mode.

GlyphMode would not use:

• NumberOfIndicesShowing (assuming most use cases involve a small fixed number of glyphs)
• LastButton * et al.
• FirstButton * et al.
• Ellipsis * et al.
• PrefixText
• NumberOfPages

While it would be the exclusive use case for a built-in timer function (based on 'normal' design choices of not auto-cycling through paged data).

Similarly ButtonPanel mode doesn't need:

• PrefixText
• NumberOfPages

and similar situation for the EditableComboBox mode.

So using a DisplayMode property vs. base class / subclass approach would result in a rotating set of irrelevant properties, depending on the selected mode. Not that having a subclass for every mode seems like an amazing approach either... classic programming dilemma.

[SavoySchuler]

@kmgallahan I agreed! The button panel and combobox scenarios certainly have more in common with each other than either of them do with glyphs. Consider a pager base class with two subclasses: one for glyphs and another for both ButtonPanel + ComboBox (which uses the display mode property to set the core indexing component). Does this feel like an ideal compromise to pair the two display modes with common properties as one sublass and to share all the methods and events common to all three from the base class? I feel like this the reduces redundancy of a sublcass-only approach and adds clarity by removing atavistic properties left by the DisplayMode only approach, but I also want to make sure I am not adding complexity with out benefit.

[kmgallahan]

@SavoySchuler Seems like a good compromise yes. Having the base class also provides an opportunity for reuse in the future, if there were ever some 4th/5th modes that one might want to introduce (without having to always propose more DisplayModes and bloating the single class with properties).

[betrue-final-final]

Some interesting iterations here. I just want to add that you want to be sure to think about freeway scenarios for both sighted and blind users. The numbers are definitely more helpful for both the blind and sighted, however the combo box is much easier to understand for blind users. That said, I would not offer the version with just pips instead of numbers, and I would suggest making the combobox version default.

[SavoySchuler]

@betrue-final-final Thank you for this feedback! I will set the default display mode to be ComboBox.

Regarding the glyphic display mode, do you think it would it be an appropriate compromise for it to visually display pips but read out numerals to narrator? In this case, you could think of them as the same display mode that differs only in whether glyphs or numerals are visually displayed on the button panel but all other accessiblity navigation and output would be the same. This glyphic display pops up in a lot of store applications and are often custom implementations that are not accessibility inclusive. I believe we have an opportunity to create an accessible version of this control where there have previously been few. Please let me know if you see things differently as inclusion of the glyphic display mode is still an open question. Thanks again for starting this conversation!

[micahl]

An additional open question I think would be great to have answered from the community is whether anyone has encountered situations other than a FlipView UX that required the use of the dots / glyphs? The FlipView's design guidance refers to it as a type of context indicator. If it's only used with a FlipView UX then should FlipView just provide that as a built-in option?