UWP Tip #14 - UWP Community Toolkit - Part 11, PullToRefreshListView Control

Welcome back to my UWP Community Toolkit series. The previous five tips in the series can be found here:

• Part 6, Using the VisualTree and LogicalTree UI Helpers
• Part 7, the Sample App
• Part 8, 2 Developer Tools
• Part 9, DockPanel Control
• Part 10, OrbitView Control

Intro

The PullToRefreshListView XAML control in the toolkit takes the familiar ListView and adds the pull-to-refresh functionality that widely used in touch-friendly UX. The PullToRefreshListView of course inherits from the ListView. Here is a look at the control running in the UWP Community Toolkit Sample App.

Using the PullToRefreshListView Control

There are a few properties available to customize the pull-to-refresh experience for your users.

• PullToRefreshLabel - Text shown when the user pulls down.
• ReleaseToRefreshLabel - Text shown when the user can release (threshold has been reached).
• PullToRefreshContent - Content shown when the user pulls down (Supersedes PullToRefreshLabel… it will not be shown).
• ReleaseToRefreshContent - Content shown when the user can release (Supersedes ReleaseToRefeshLabel… it will not be shown).
• RefreshIndicatorContent - The refresh indicator's content. This element will display when the list is refreshing.
• PullThreshold - Distance in pixels that the content must be pulled to trigger a refresh on release.
• OverscrollLimit - A System.Double between 0 and 1 which specifies the overscroll limit. The default value is 0.3.
• IsPullToRefreshWithMouseEnabled - Indicates if the mouse can be used to trigger a pull-to-refresh. If this is false, touch must be used.

Here is the XAML for the control taken from the Sample Application. You can see that you create a DataTemplate for the item display like you would for any other ListView in UWP. The PullToRefreshContent is used instead of the label to allow for a custom TextBlock to be created.

<controls:PullToRefreshListView
         x:Name="ListView"
         MinWidth="200"
         Margin="24"
         HorizontalAlignment="Center"
         Background="White"
         OverscrollLimit="0.4"
         PullThreshold="100"
         IsPullToRefreshWithMouseEnabled="True">
   <controls:PullToRefreshListView.ItemTemplate>
     <DataTemplate>
       <TextBlock AutomationProperties.Name="{Binding Title}"
                  Style="{StaticResource CaptionTextBlockStyle}"
                  Text="{Binding Title}"
                  TextWrapping="WrapWholeWords" />
     </DataTemplate>
   </controls:PullToRefreshListView.ItemTemplate>
   <controls:PullToRefreshListView.PullToRefreshContent>
     <TextBlock FontSize="16"
                Opacity="0.5"
                Text="Pull down to refresh data" />
   </controls:PullToRefreshListView.PullToRefreshContent>

</controls:PullToRefreshListView>

There is a RefreshCommand that gets triggered when the refresh is triggered on release. This is where you will add your code in either the code behind or (preferably) the corresponding ViewModel. If you have a Refesh button or menu option someplace else in the View, the logic can be shared by both commands.

There is a also a PullProgressChanged you can use to update the RefreshIndicatorContent with the progress of a long-running refresh.

Wrap-Up

The PullToRefreshListView control is a great shortcut control to add a little extra something to your app with very little extra coding necessary. Go check it out today and spice up your UWP app's UX!

Happy coding!

del.icio.us Tags: uwp community toolkit,xaml,uwp