Monday, January 29, 2018

UWP Tip #15 - UWP Community Toolkit - Part 12, Working with Headings

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


The UWP Community Toolkit has a few controls to add headers to your WPF application's content. Drop this into your app and add a little styling to match their look to the rest of your app and you'll quickly and easily save time creating repetitive markup throughout your UI.

The HeaderedContentControl

The HeaderedContentControl provides the base functionality for the other headered controls. It will display a header along with any content. Wrap any of your existing controls with this one to quickly add some header text. Here's an example of the HeaderedContentControl containing a TextBox.

<HeaderedContentControl Header="TextBox Content"
     <TextBox Text="Hello headers!"/>

That markup will render the following UI in your WPF Window:


Pretty simple. As you'll see in the next section, it is also pretty simple to add some style to the header text too.

The HeaderedItemsControl

The HeaderedItemsControl providers all of the functionality of a standard ItemsControl with a header added above the items. It's a HeaderedContentControl but the content is always an ItemsControl. Set the Header text property and the ItemsSource to your list of items, and you're all set. You can drop this in place of any of your existing ItemsControls and re-use the same ItemTemplate to achieve an identical look and feel of the list items.

With any of the headered controls, the header itself can also be customized be assigning a DataTemplate to the HeaderTemplate, in this case the HeaderedItemsControl.HeaderTemplate.

Here's the simplest use of the control, with the Header hard-coded and the ItemsSource bound to a collection in the DataContext.

<controls:HeaderedItemsControl Header="Some Items" 
                                 ItemsSource="{Binding SomeItems}" >

Take a look at a couple of HeaderedItemsControls in the UWP Community Toolkit Sample App. The first list's XAML is as simple as mine above. The second add a little custom layout to the header and the list.


Here's the markup to add the blue foreground to the second header.

         <TextBlock DataContext="{Binding DataContext, ElementName=Page, Mode=OneWay}"
                    Text="Header 2" />

The HeaderedTextBlock

The HeaderedTextBlock control providers a quick way to display some read-only text with some corresponding header text. It's a HeaderedContentControl but the content is always a TextBlock. The three properties you need to know are straightforward: Header, Text and Orientation. You can lay out the header and text in a Horizontal or Vertical layout, the Vertical being the most common use.

Check it out in the Sample App.


Here's the corresponding XAML for the control.

     Header="My Item"
     Text="Some really interesting information about my item."
     Margin="20,10,0,0" />

A few of these controls is a great, simple way to lay out a read-only form on your app.


Go grab the latest toolkit packages via NuGet or browse the repo on GitHub today! There are many more controls you can use in your apps today. We'll check out a few more in a couple of weeks.

Happy coding!

Tuesday, January 9, 2018

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:


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.

       <TextBlock AutomationProperties.Name="{Binding Title}"
                  Style="{StaticResource CaptionTextBlockStyle}"
                  Text="{Binding Title}"
                  TextWrapping="WrapWholeWords" />
     <TextBlock FontSize="16"
                Text="Pull down to refresh data" />

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.


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! Tags: ,,