Thursday, November 30, 2017

UWP Tip #11 - UWP Community Toolkit - Part 9, DockPanel Control

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

Intro

The UWP Community Toolkit v2.1.0, released November 21st, includes a new XAML control called the DockPanel.

Using the DockPanel

Like the name implies, the DockPanel control is a panel that allows children to dock to one of its sides. This docking is achieved through the DockPanel.Dock attached property. The property can be set to Top, Left, Right or Bottom. There is no Fill value to indicate filling the center of the panel.

Here is the sample Window I created with a DockPanel control:

uwp_tk_dockpanel1

Each side contains a docked StackPanel. The Top and Bottom StackPanels appear first in the XAML, which is why they extend all the way to the left and right sides of the parent control instead of the left and right StackPanels extending completely to the top and bottom. I don't claim to be a UX expert, but I think the colored StackPanels help to visualize the docked areas.

To work around the lack of a Fill dock property, I tried a couple of options. When I first tried putting my TextBox as the last child of the DockPanel, it filled the middle space vertically but not horizontally. It was only about 100px wide. It could only be made wider by hard-coding the Width property. I had no luck trying different HorizontalAlignment settings on the TextBox either. I suspect there is a bug in the DockPanel causing this behavior and will be submitting an issue on GitHub.

I decided to add the TextBox as a second child in the Grid containing the DockPanel as the first child. I used the Margin property on the TextBox as a hack to make the control fit within the center of the DockPanel.

Here is the XAML source for the Window's layout:

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
     <Grid.RowDefinitions>
         <RowDefinition Height="Auto"/>
         <RowDefinition Height="*"/>
     </Grid.RowDefinitions>
         
     <TextBlock Margin="4" Text="Hello DockPanel" VerticalAlignment="Top" HorizontalAlignment="Left"/>
         
     <Grid Padding="4,0,4,4" Grid.Row="1">
         <controls:DockPanel Background="LightSlateGray" LastChildFill="False" >
             <StackPanel Height="80" controls:DockPanel.Dock="Top" Background="DarkGray">
                 <TextBlock Text="Header" Margin="18" 
                             HorizontalAlignment="Left"  Foreground="DarkSlateBlue"
                             FontSize="36" FontWeight="Bold"/>
             </StackPanel>
             <StackPanel Height="80" controls:DockPanel.Dock="Bottom" Background="DarkGray">
                 <TextBlock Text="Footer" Margin="18" 
                             HorizontalAlignment="Left" Foreground="DarkSlateBlue"
                             FontSize="36" FontWeight="Bold"/>
             </StackPanel>
             <StackPanel Width="120" controls:DockPanel.Dock="Left" Background="DarkSlateBlue"></StackPanel>
             <StackPanel Width="120" controls:DockPanel.Dock="Right" Background="DarkSlateBlue"></StackPanel>
         </controls:DockPanel>
             
         <TextBox Margin="128,88,128,88" Opacity="0.6"
                     AcceptsReturn="True" PlaceholderText="The content. Add yours here..."/>
     </Grid>

</Grid>

Wrap-Up

It is very straightforward to use the DockPanel, outside of the quirky center area layout. Go installed the Microsoft.Toolkit.Uwp.UI.Controls NuGet package today and try it for yourself.

Happy coding!

del.icio.us Tags: ,

Monday, November 20, 2017

UWP Tip #10 - UWP Community Toolkit - Part 8, 2 Developer Tools

Welcome back to my UWP Community Toolkit series. Previous Tips in the series can be found here:

Intro

The UWP Community Toolkit contains a couple of XAML controls targeted specifically at developers and dev-focused apps. They are an AlignmentGrid and the FocusTracker. Each could be useful when developing an app UI.

AlignmentGrid XAML Control

The AlignmentGrid control can help you align other elements on a window (or within a specific container element). Let's take a look at the control running within the UWP Toolkit Sample App, outlined in Part 7 of this series.

uwp-toolkit-8.1

The control resides within the same parent Grid as the StackPanel containing the five TextBlock controls. It makes a nice way to quickly visualize your controls' layout/alignment. You can change the AlignmentGrid's Opacity and LineBrush color, depending on your preferences and your app's appearance. You can also modify the spacing of the grid lines independently with the HorizontalStep and VerticalStep properties. Here's the XAML for a simple grid containing four buttons.

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
     <developerTools:AlignmentGrid
         x:Name="MainAlignmentGrid"
         Opacity="1"
         LineBrush="DarkGreen"
         HorizontalStep="20"
         VerticalStep="20"/>
     <StackPanel HorizontalAlignment="Center" Margin="0,40,0,0">
         <Button Content="Button 1" Margin="4"/>
         <Button Content="Button 2" Margin="4"/>
         <Button Content="Button 3" Margin="4"/>
         <Button Content="Button 4" Margin="4"/>
     </StackPanel>

</Grid>

The designer in Visual Studio 2017 shows the four buttons spaced evenly between the horizontal gridlines.

uwp-toolkit-8.2

By default the grid appears at design-time and runtime. This can be handy to check alignment at different resolutions and on different devices. When you're ready to deploy your app to the store, you can either remove the control, comment it out or add a line of code to your page's code behind to change the Visibility at runtime.

public MainPage()

{
     InitializeComponent();
     Loaded += MainPage_Loaded;

}


private void MainPage_Loaded(object sender, RoutedEventArgs e)

{
     if (!DesignMode.DesignModeEnabled)
         MainAlignmentGrid.Visibility = Visibility.Collapsed;

}

Now when we launch the app, the page appears with only the four buttons on an empty background.

uwp-toolkit-8.3


This control could also come in handy if you're developing an app that provides your users with some type of visual designer. You could additionally provide a button to toggle the visibility of the grid on/off.

FocusTracker

The FocusTracker appears as a read-only property panel displaying four properties of the currently selected XAML control on your page. The four properties displayed are:
  • Name - The name of the current XAML control, if it has one.
  • Type - The type of the current XAML control.
  • Automation.Name - If you're using UI automation and have provided the current control for this, it is displayed here (set via AutomationProperties.Name attached property).
  • Parent with Name - Traversing up the visual tree, the first parent found to have a name is displayed here, if any.
Here is the FocusTracker control running within the Sample App:

uwp-toolkit-8.4

I had clicked on the header of the code panel on the right side before taking the screen shot. Here's another shot after clicking within the code panel itself:

uwp-toolkit-8.5

You can see the FocusTracker immediately updated to display the info for the WebView hosting the XAML editor. Pretty cool!

I could see this being particularly useful to drop onto a page when you're trying to track down some issues with your automated UI tests. Give it a try if you deal with a lot of complex UI under test.

Wrap-Up

Both of these controls are definitely niche tools for a specific set of use cases, but they could both save you a ton of time if your app falls into one of those categories. Both are available in the Microsoft.Toolkit.Uwp.DeveloperTools NuGet package. Go give them a try!

Happy coding!

Tuesday, November 7, 2017

UWP Tip #9 - UWP Community Toolkit - Part 7, the Sample App

Welcome back to the UWP Community Toolkit series. Previous Tips in the UWP Community Toolkit series:
Did you know that there is a UWP Community Toolkit Sample App in the Microsoft Store?
uwptoolkitapp
The main page of the app is a dashboard with several sections:
  • Recent Activity - Shows your recent activity within the sample app.
  • What's New - Highlights new and updated features of the UWP Community Toolkit.
  • UWP Community Toolkit - General official links to aspects of the toolkit, including the GitHub repo, issues, roadmap and UserVoice.
  • Useful Links - These are links relevant to Windows app developers which aren't necessarily directly related to the toolkit. Things like the Windows Developer Center can be found here.
  • Release Notes - Release notes for recent UWP Community Toolkit releases are linked here.
  • About the App - Info and links that you would typically find on your app's About page are here on the dashboard.
Across the top, you'll find a menu bar with the categories of resources available in the Toolkit.
  • Controls
  • Notifications
  • Animations
  • Services
  • Helpers
  • Extensions
  • Developer tools
We've already covered many of these categories in this series. Clicking on controls expands a submenu with the different control types currently available in the toolkit, and hovering over one of them displays a preview of the control and its description.
uwptoolkit-controls
Let's select the HamburgerMenu and see what we can do with it in the sample app.
uwptoolkit-hamburger
Here you'll find a live preview of the control on the left side and a pane on the right with a link to the source on GitHub and three selectable panes.
  • Properties - Exposes some of the control's properties for manipulation. Make changes here and they're immediately reflected on the live preview.
  • Xaml - Displays the current Xaml source code of the page hosting the control in the live preview. Any updates you make to the Xaml source are immediately reflected in the live preview.
  • Documentation - Displays the documentation for the selected control from docs.microsoft.com.
The live preview is functional and interactive. You can interact with the menu to navigate through it's sections, displaying different images in the main panel.
The sections not related to controls, display a preview of the code output for different helper types. You can use the right panel to view both source code and docs. Take a look at the Network helper.
uwptoolkit-network
The sample app is a great way to get started exploring the UWP Community Toolkit. If you have been following along with my toolkit series and are ready to start using it yourself, I strongly encourage you to download the sample app. It will be a handy guide as you get started on your own apps leveraging the toolkit.

Happy coding!

Friday, October 27, 2017

UWP News - The UWP Community Toolkit Cheese Has Moved

Hello UWP App Dev peeps!

If you've been following along with my UWP Community Toolkit tips, you may have noticed a few of the links are either dead or redirecting to other pages. This is happening because all UWP Community Toolkit information and documentation can now be found on docs.microsoft.com. Docs is now the home for all things documentation in the Microsoft development world, in case you haven't heard. The many of the old links on developer.microsoft.com are now redirecting to Docs.

I will be going back through my blog posts over the next couple of weeks to update links. Until that time, if you encounter a dead link, feel free to leave a comment on the post or reach out to me on Twitter. You can use the excellent search feature on docs.microsoft.com to find the docs for all the UWP Toolkit features and APIs.

The code itself still lives over on GitHub. Use this site to report issues, request enhancements or contribute to the toolkit yourself through a PR. You can also contribute to the documentation on the Docs site if you find anything missing, lacking depth, or altogether incorrect.

Thanks again for following along with the UWP App Dev Tips! You can expect to see a new tip in the next couple of days.


Cheers!

Saturday, October 21, 2017

UWP Tip #8 - UWP Community Toolkit - Part 6, Using the VisualTree and LogicalTree UI Helpers

Welcome back to the UWP Community Toolkit series. Previous Tips in the UWP Community Toolkit series:
Introduction
This tip will continue exploring the Code Helpers that we started looking at in Part 3. There are only a few types of helpers remaining, and today we will examine the collection of available VisualTree and LogicalTree UI extension methods.
VisualTree Extensions
The VisualTree extension methods extend and simplify the built-in UI element navigation methods of the framework. There are currently five methods available to use in the toolkit.
  • FindDescendantByName(elementName) - Navigates down the visual tree until an element with the provided name is found.
  • FindDescendant<T>() - Navigates down the visual tree and returns the first element for the given type.
  • FindDescendants<T>() - Returns an IEnumerable of all descendant elements of the given type.
  • FindAscendantByName(elementName) - Navigates up the visual tree until an element with the provided name is found.
  • FindAscendant<T>() - Navigates up the visual tree and returns the first element for the given type.
Here is an example of the use of each method to retrieve UI elements from your visual tree.
public void ProcessVisualUiElements()
{
    var listControl = mainGrid.FindDescendantByName("resultList");
    listControl = mainGrid.FindDescendant<ListView>();
    listControl.MaxWidth = 500;
    foreach (var item in mainGrid.FindDescendants<ListViewItem>())
    {
        item.IsEnabled = false;
    }
    var gridControl = resultList.FindAscendantByName("mainGrid");
    gridControl = resultList.FindAscendant<Grid>();
    gridControl.Margin = new Thickness() { Bottom = 2, Left = 2, Right = 2, Top = 4 };
}

Most UWP developers will probably use the FindAscendant/FindDescendant methods using the type of element to find as we try to avoid naming our UI elements.
LogicalTree Extensions
The LogicalTree extensions are very similar but they operate over logical elements, ignoring certain containers and style elements only found in the visual tree. Not having to rely on knowing if the elements have been rendered yet before finding them can be an advantage of this method also.
The set of methods available mirror those for the visual tree with one additional method to find an element's content control.
  • FindChildByName(elementName)
  • FindChild<T>()
  • FindChildren<T>()
  • FindParentByName(elementName)
  • FindParent<T>()
  • GetContentControl()
The sample code also mirrors the previous sample.
public void ProcessLogicalUiElements()
{
    var listControl = mainGrid.FindChildByName("resultList");
   
    listControl = mainGrid.FindChild<ListView>();
   
    foreach (var item in resultList.FindChildren<ListViewItem>())
    {
        item.IsEnabled = true;
    }
   
    var gridControl = resultList.FindParentByName("mainGrid");
   
    gridControl = resultList.FindParent<Grid>();
   
    var searchContent = searchTextBox.GetContentControl();
}

Wrap-Up
That's all for today's helpers! They're very straightforward to use and can save quite a bit of manually traversing the visual and logical trees to find a target element. Check back as next time we will finish up the helpers provided by the UWP Community Toolkit.
Happy coding!

del.icio.us Tags: ,,