Category Archives: Toolkit

Windows Phone Toolkit - September 2012 Release

6 Replies

A few astute people (@Patric68,  @scottisafool) have noticed that we pushed out the September 2012 release of the Windows Phone Toolkit.  This was a soft launch, quietly pushed out because we’ve been going like crazy with bug fixes, prepping for Build and doing a whole host of things and I really wanted to get a build out that had the latest fixes and improvements without blocking on all the paperwork. That’s agile baby!

What’s New

Branding

It’s now just the “Windows Phone Toolkit”.  Honestly “Silverlight for Windows Phone Toolkit” was too much of a mouthful and new developers targeting Windows Phone often don’t know of the Silverlight underpinnings.  We’re slowly transitioning all branding in the source to the shorter version.

CustomMessageBox

Sample CustomMessageBox Image

CustomMessageBox is a new control that makes it easy to create, well, custom message boxes that look and feel just like the default ones on the phone.  I did a little write-up of it last week in my blog post, “Welcome CustomMessageBox to the Windows Phone Toolkit”.

Rating

Sample Rating Control Image

Rating is another new control that does exactly what it says, provides a rating control that matches the Windows Phone UI.  Expect a blog post on using it soon but it as always you can see it in action by downloading the sample application from CodePlex.

Transition Effects

There are new transition effects that make it even easier to match the Windows Phone UX.

  • SlideInEffect – Ever notice when you’re in a Pivot or Panorama on the phone in one of the native experiences , say the People Hub, how the items in a list slide in on a separate animation as you swipe back and forth?  It’s subtle but adds a nice level of polish to the whole experience and now it’s super easy to add to your application as well.  There is a new attached property, toolkit:SlideInEffect that you set on each item in your DataTemplate that controls the order in which elements slide in: 
    <DataTemplate>
    <StackPanel Margin="0,0,0,17" Width="432">
        <TextBlock Text="{Binding LineOne}" 
                   TextWrapping="Wrap" 
                   Style="{StaticResource PhoneTextExtraLargeStyle}"/>
        <TextBlock Text="{Binding LineTwo}" 
                   TextWrapping="Wrap" 
                   Margin="12,-6,12,0" 
                   Style="{StaticResource PhoneTextAccentStyle}"
                   toolkit:SlideInEffect.LineIndex="1"/>
        <TextBlock Text="{Binding LineTwo}" 
                   TextWrapping="Wrap" 
                   Margin="12,-6,12,0" 
                   Style="{StaticResource PhoneTextSubtleStyle}"
                   toolkit:SlideInEffect.LineIndex="2"/>
    </StackPanel>
</DataTemplate>
  • FeatherTransition – Another common effect seen on Windows Phone is a “feathering” in of the controls on a page such as when you launch the mail app.  Notice how the items on the page feather in from top to bottom. 
    <!--TitlePanel-->
<StackPanel Grid.Row="0" Margin="12,17,0,28">
    <TextBlock Text="{StaticResource ApplicationTitle}" 
                Style="{StaticResource PhoneTextNormalStyle}"
                toolkit:TurnstileFeatherEffect.FeatheringIndex="0"/>
    <TextBlock Text="turnstilefeathereffect" 
                Margin="9,-7,0,0" 
                Style="{StaticResource PhoneTextTitle1Style}"
                toolkit:TurnstileFeatherEffect.FeatheringIndex="1"/>
</StackPanel>

Distribution / Installation

We’ve taken a new approach to distribution this time and gone “all-in” on NuGet as the official way to install the toolkit.  We’ll no longer be supporting an MSI-based installer as it’s not very maintainable or discoverable.  NuGet is built into Visual Studio 2012 and is fast becoming the de-facto standard for installing packages and if you haven’t already installed the plug-in for Visual Studio 2010 I highly recommend it.

As always you can still either download the source as a zip or from the source control on CodePlex and compiling the assembly yourself.

Bug Fixes

No release is complete without bug fixes and we have roughly 25 of the top user voted bugs fixed in this release.

Feedback

As always we love feedback, bug reports, creative uses and ideas.  We have more plans for the toolkit in the near future as well so stay tuned!

Welcome CustomMessageBox to the Windows Phone Toolkit

15 Replies

A big welcome to CustomMessageBox, a new control to the toolkit which is exactly what it sounds like, a customizable, Windows Phone-UI compliant, easy to use message box offering the following features:

  • Native look & feel including font sizes, layout, alignment and animations
  • Ability to display full screen or to only consume as much space as needed
  • Very simple “basic” mode with ability to easily extend it to complex scenarios
  • Customizable buttons without needing to re-template

Here is what it looks like, from the basic (a message and some buttons) to the complex (a full screen message box with an embedded Pivot):

imageimage

Getting Started

As of today (9/30/2012) you’ll need to download the latest source from CodePlex and recompile the toolkit assembly to use it but we’ll soon have an updated NuGet package for your convenience. As usual add a reference to the Microsoft.Phone.Controls.Toolkit.dll to your project and add the toolkit XML namespace to the top of your XAML:

xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"

Basic Usage

The basic usage is very similar to the default MessageBox and how you’re probably used to using dialogs in other UI platforms; set some properties, call Show(), handle the event that is raised when the user returns from the dialog.

Possible values to customize are:

  • Caption – sets the title caption of the message box
  • Message – the actual message to display to the user
  • LeftButtonContent, RightButtonContent – the buttons that appear on the bottom of the dialog, if you omit the text then the button won’t be shown.

To handle the user’s selection hook up the Dismissed() event and look at the e.Result value which is of type CustomMessageBoxResult indicating which, if any, button was tapped. If the user presses the back button vs. making a selection the result will be None.

Finally to kick-off the whole process call Show(). Show() is non-blocking so be aware that any code you put after the Show() call will run before the user has made a selection.

By default the the message box only takes up as much space as required but you can force it to full-screen by setting the property IsFullScreen to true.

Simple Example

To recreate the first message box in the screen shot do the following in code-behind:

CustomMessageBox messageBox = new CustomMessageBox()
{
    Caption = "Do you like this sample?",
    Message = "There are tons of things you can do using custom message boxes. To learn more, be sure to check out the source code at CodePlex.",
    LeftButtonContent = "yes",
    RightButtonContent = "no"
};
messageBox.Dismissed += (s1, e1) =>
    {
        switch (e1.Result)
        {
            case CustomMessageBoxResult.LeftButton:
                // Do something.
                break;
            case CustomMessageBoxResult.RightButton:
                // Do something.
                break;
            case CustomMessageBoxResult.None:
                // Do something.
                break;
            default:
                break;
        }
    };
messageBox.Show();

The title caption, message and buttons are configured, the Dismissed() event is assigned a handler and finally the Show() method is called to kick off the party.

Taking It Up A Notch

That’s all well and good but where is the real “custom” part of the CustomMessageBox? That comes in with the Content property where you insert your own content into the overall layout. You can define your extra content in either code-behind or as a XAML resource and then set it to the Content of the CustomMessageBox.

The content area exists below where the Message is displayed yet right above the buttons.

Let’s say we want to recreate this dialog:

image

Via Code-Behind

One way to go about it would be to create all the custom content inline at the time of invocation:

HyperlinkButton hyperlinkButton = new HyperlinkButton()
{
    Content = "Privacy Statement",
    Margin = new Thickness(0, 28, 0, 8),
    HorizontalAlignment = HorizontalAlignment.Left,
    NavigateUri = new Uri("http://silverlight.codeplex.com/", UriKind.Absolute)
};
TiltEffect.SetIsTiltEnabled(hyperlinkButton, true);
CustomMessageBox messageBox = new CustomMessageBox()
{
    Caption = "Allow this application to access and use your location?",
    Message = "Sharing this information helps us provide and improve the location-based services offered for this phone. We won't use the information to identify or contact you.",
    Content = hyperlinkButton,
    LeftButtonContent = "allow",
    RightButtonContent = "cancel"
};

The HyperlinkButton is created in code, tilt effect is set on the HyperlinkButton and to hook it together the HyperlinkButton is assigned to the Content property.

Via XAML

Another approach is to create it as a DataTemplate in either the page or application resources and when you configure the dialog set the ContentTemplate property which may prove easier for more complicated templates.

<DataTemplate x:Key="HyperlinkContentTemplate">
    <HyperlinkButton Content="Privacy Statement"
                        Margin="0,28,0,8"
                        HorizontalAlignment="Left"
                        NavigateUri="http://silverlight.codeplex.com/"
                        TargetName="_blank" />
</DataTemplate>

Now the code-behind looks like this:

CustomMessageBox messageBox = new CustomMessageBox()
{
    Caption = "Allow this application to access and use your location?",
    Message = "Sharing this information helps us provide and improve the location-based services offered for this phone. We won't use the information to identify or contact you.",
    ContentTemplate = (DataTemplate)this.Resources["HyperlinkContentTemplate"],
    LeftButtonContent = "allow",
    RightButtonContent = "cancel"
};

More Samples

You can find more examples, including the source to the “What Can I Say?” screenshot I showed above, in the Toolkit Samples project which you can either get via downloading the latest source or looking at it directly on CodePlex.

As always feedback is appreciated via either comments here or on CodePlex. We review each piece of feedback and we do get to them, if sometimes a little later than we’d like. Our goal is to make it so you can focus on writing your application vs. having to recreate the UI you see on the phone.

How to make the Windows Phone Toolkit ToggleSwitch Header wrap

Leave a reply

I’m going through the Windows Phone Toolkit bugs fixing some of the low hanging fruit and came across this bug where a ToggleSwitch with a long header is clipped.  The proper Metro behavior is that it should wrap which is easy enough to do on a TextBlock.  The rub though is that the Header is represented by a ContentControl, not a TextBlock.

ContentControl makes it easy to put whatever you’d like into the Header; images, other controls, buttons, etc. and is the standard Silverlight way of representing content.  This is great for an open-ended environment like the Silverlight plug-in where each app has it’s own UI but on the phone you want as close to the Metro UI as you can get.  In a perfect world (or just one with a time machine) we would have made Header a TextBlock with wrapping turned on but, well, we didn’t.  We’re still debating if we should just make the switch and deal with the fall out but until then here is a super simple way to ensure your Header text wraps when it needs to:

<toolkit:ToggleSwitch Header="This is an example of a really long description label for localization">
    <toolkit:ToggleSwitch.HeaderTemplate>
        <DataTemplate>
            <TextBlock FontFamily="{StaticResource PhoneFontFamilyNormal}"
                        FontSize="{StaticResource PhoneFontSizeNormal}"
                        Foreground="{StaticResource PhoneSubtleBrush}"
                        TextWrapping="Wrap"
                        Text="{Binding}" />
        </DataTemplate>
    </toolkit:ToggleSwitch.HeaderTemplate>
</toolkit:ToggleSwitch>

Which gets you:

image

If you’re going to do any type of localization I recommend you make this change to all your ToggleSwitch controls.

Silverlight TreeView Connecting Lines And Blend 3 Support for HierarchicalDataTemplates

9 Replies

The July 2009 release of the Silverlight Toolkit has a bunch of great things in it but a few of them require just a little digging. A common request in the forums and on CodePlex is how to add connecting lines to the standard TreeView. Well, thanks to TreeViewExtensions and a pre-built template it’s now an easy request to fulfill.

I’m going to show you how to add connecting lines using Blend 3 but it’s not a requirement. Grab a copy of Expression Studio 3 if you don’t already have Blend installed. There were a lot of great enhancements with the last release so I encourage you to give it a go.

Prerequisites

  1. Make sure you’ve installed the July 2009 release of the Silverlight Toolkit
  2. Start a new Silverlight project in Blend 3
  3. While you could start by dragging a TreeView from the Asset pane onto the design surface I want to show off Blend’s support for sample data and editing the HierarchialDataTemplate.

Define Sample Data

One of the more annoying things when trying a do a little research into how you can tweak a control is having to come up with some kind of mock data to work with, especially when working with a TreeView because of its hierarchical nature. Blend 3 introduced a huge time-saving feature, Sample Data, that we’ll take advantage of.

For this example I want to end up with a common TreeView UI pattern, an icon followed by some text, similar to a basic file browser. With those requirements in mind lets create some sample data.

  1. Switch to the Data panel
  2. Click on the ‘Add sample data source’ icon (circled below) and choose ‘Define New Sample Data…’
    Define New Sample Data
  3. Go with all the defaults and click OK
  4. Presto, magic sample data!

At this point you can drag the SampleDataSource onto the design surface and Blend will create a ListBox with fields properly bound to the control and fully interactive sample data. Very useful but we need to do a just a little more tweaking to get it where we want it.

Change the property type of Property1 to an Image and Property2 to a String. You do this via the property type dialog accessed by clicking on the icon to the right of property name (circled below).

image

Almost there. We now have an image and some text but it’s missing that hierarchical nature. Easy enough to fix. Click on the drop down to the right of the Collection and click “Convert to Hierarchical Collection”:

image

At this point you’ll have a collection that contains a collection that contains a collection that… you get my drift. Grab the first Collection underneath SampleDataSource and drag it onto the Blend design surface and watch the magic happen!

You’ll end up with something like this:

image

Pretty awesome considering you didn’t have to create a single mock object, mess with any XAML or write any code.

Customizing the HierarchialDataTemplate in Blend

OK, now that the rush of excitement has worn off (if it hasn’t don’t worry, just take a few deep breaths, take a walk and come back when you’ve got your heart rate under control) the harsh reality creeps in that this doesn’t look exactly like your basic file browser. Image is a bit big and the text is underneath it the icon.

Easy enough to fix:

  1. Select the TreeView
  2. There are at least three ways to navigate to the Edit Current Template menu but I find the fastest is clicking on the TreeView breadcrumb underneath the MainPage.xaml tab (illustrated below)
    image

At this point you have a very simple template to work with, a basic StackPanel containing an Image and TextBlock

image

Go ahead and tweak the template into something a little more like what you’d expect from a file browser:

  1. Change the orientation of the StackPanel to Horizontal
  2. Change the Width and Height of the Image to 16 x 16
  3. Change the VerticalAlignment of the TextBlock to Center

Now we have something much more useful:

image

(I changed my sample data generation on the string to only create one word with a maximum of 12 characters)

Where Are Those Connecting Lines?

I know what you’re thinking, I brought you all this way, are we ever going to get to the connecting lines part? Well, the grand revel is here!

  1. Add a reference to System.Windows.Controls.Toolkit (if you went with the default install it should be in C:Program FilesMicrosoft SDKsSilverlightv3.0ToolkitJul09Bin)
  2. Download TreeViewConnectingLines.xaml and add it to your project
  3. Switch to the Resources panel and expand TreeViewConnectingLines.xaml, it’ll look like this:
    image
  4. There is a style for both the TreeView itself and the TreeViewItems that it contains.
  5. Drag ConnectingLinesTreeView onto the TreeView and when prompted select “Select property on “[TreeView]” Style
    image
  6. Switch to the Properties panel for the TreeView
  7. Scroll down to ItemContainerStyle (in Miscellaneous section)
  8. Click the Advanced property button to the right of the property (circled below)
    image
  9. Select Local Resource –> ConnectingLinesTreeViewItem

And there you go! You now have connecting lines, with a plus/plus icon showing expansion state. It even shows inside of Blend so you see exactly what you get but it’s more fun to run it and see it in all its connecting line glory!

image

Source

UPDATE: I’ve been asked in the comments to provide the source so without further ado get it here:

Connecting Lines Source

Epilogue

To be honest I could have just started with adding the connecting lines and you’d be on your way but I really wanted to show off sample data for TreeView, converting that sample data into a hierarchy and editing the HierarchicalDataTemplate in Blend 3.

Adding Silverlight Toolkit Controls to the Visual Studio and Blend Toolbox

4 Replies

Now that title is a mouth-full. I’ve seen a few questions in the Silverlight.net forums asking how to get the Silverlight Toolkit controls into the toolbox/asset library of Visual Studio 2008 and/or Expression Blend 2. There are a bunch of great posts scattered among the tubes on how to do this but I wanted to explain both Visual Studio 2008 and Blend 2 in one post. Plus it’ll segue nicely into an upcoming post :)

Download the Silverlight Toolkit

  1. Download the latest release of the Silverlight Toolkit (December 2008 as of this post).
  2. Unzip to a folder of your liking (I use the highly imaginative C:SourceSilverlight Toolkit December 2008).

Adding to the Visual Studio 2008 Toolbox

You can add the controls to any tab in the Toolbox you like, for this example I’m going to create a new tab, Silverlight Toolkit.

  1. Right-click anywhere in the Toolbox and select Add Tab, name it Silverlight Toolkit.
  2. Right-click in the empty space of the Silverlight Toolkit group and select Choose Items.
  3. Select the Silverlight Components tab.
  4. Click Browse and browse to Binaries folder, adding Microsoft.Windows.Controls, Microsoft.Windows.Controls.Input and Microsoft.Windows.Controls.DataVisualization.
  5. The controls will now appear in your Toolbox.

    Silverlight Toolkit controls in Visual Studio 2008 toolbox

Adding to Expression Blend 2 Asset Library

Adding controls to Blend is even easier, though you do have to repeat this process for each new project. Also because making controls available in Blend requires you to add references to your project, thus increasing your download size, you should only add references to the assemblies you need. Bit of a chicken and egg issue. To help you decide which assemblies to add I included a breakdown of which controls are in what assembly after these instructions.

  1. In your Project pane right-click on References, select Add Reference….
  2. Add references to Microsoft.Windows.Controls, Microsoft.Windows.Controls.DataVisualization, Microsoft.Windows.Controls.Input.

    Blend 2 Project Pane

  3. The controls will now appear in the Custom Controls section of the Asset Library.

    Blend 2 Asset Library

What’s In Each Assembly?

Microsoft.Windows.Controls

  • AutoCompleteBox
  • DockPanel
  • Expander
  • HeaderedContentControl
  • HeaderedItemsControls
  • Label
  • TreeView
  • TreeViewItem
  • Viewbox
  • WrapPanel

Microsoft.Windows.Controls.Input

  • ButtonSpinner
  • NumericUpDown

Microsoft.Windows.Controls.DataVisualization

  • Charting (with associated Axis, DataPoint and Series).

Getting Support, Offering Feedback

As always the best place to get support for the Silverlight Toolkit is to post in our forum on Silverlight.net. If you have a feature request or bug please file it in our Issue Tracker and get some votes behind it. We look carefully at those numbers when we decide how to prioritize the bug fixes.

(Updated to include warning about adding assemblies you don’t need in Blend and what controls are in each assembly, plus fixed the title tag on a few images)