Part 31: Multiple Selection with the LongListMultiSelector
Our ultimate vision for the app is to allow the user to select one or more photos.
- We'll add a reference to the Windows Phone toolkit so that we can utilize the LongListMultiSelector, an improved version of the LongListSelector we've been using that allows a user to make multiple selections in the list.
- We'll convert our LongListSelector to a LongListMultiSelector and add attributes to its definition to enable its unique functionality
1. Install the Windows Phone toolkit package and review the samples
The Windows Phone Toolkit extends what we get out of the box with the Windows Phone 8 API, adding new components and functionality. I'm going to download the toolkit and samples just to see what this can do for us.
And click on the Downloads link.
NOTE: THIS CHANGED SINCE THE SCREENSHOT ... Download the solution from the Source Code tab!
There's a single download that contains a solution for both Windows Phone 7 and 8 toolkits, as well as sample apps containing all the controls and features. I download it, right-click the zip file and Extract All:
I'll put it in a temporary spot on my hard drive:
And I'll open up the Solution folder, agreeing to the dialogs that warn me about downloading things from the Internet.
To run the Sample app:
- Right-click the project in the Solution Explorer named: PhoneToolkitSample.WP8.
- Select "Set as StartUp Project" from the context menu.
Now, run the Solution in debug mode (F5).
There are dozens of samples featuring the controls and animations / transitions available in the toolkit:
I love the date picker:
... and the HubTile control which is strangely calming if you watch it for a few minutes:
We're most interested in the LongListMultiSelector sample. It demonstrates several different modes that can be used to enable multi-selectable lists.
Click the "Select" button at the bottom:
... and that puts the list into selection mode. Now, you can select the checkmarks next to each item, then click the icon in the App Bar which has changed to a Delete button:
That's great, however not exactly what we need for our AroundMe project. Fortunately, the control's appearance and functionality can be configured in multiple ways.
If you swipe over to the Grid mode panel, there's another example that involves image thumbnails. If you click on an image, it shows a larger version in a light box. However, when you click the icon in the App Bar at the bottom, you can switch to Grid Selection Mode. This allows you to select one or more images. Each thumbnail that's selected will show a red triangle with a white checkmark icon in the upper-right-hand corner.
That's what we'll want for the results of our Flickr API call results. This will allow the user to select multiple images to be saved to the phone and randomly used for the lock screen every 30 minutes.
2. Install the NuGet package into the project
To use the Windows Phone Toolkit package in our existing AroundMe project, the easiest way is to add it with NuGet.
Navigate to: https://nuget.org/packages/WPtoolkit/
I love the obvious package installation instructions on the NuGet site.
If the Package Manager Console is not already open, go to Visual Studio's Tools menu, select Library Package Manager, then the Package Manager Console sub menu option.
At the Package Manager command prompt, type: install-package WPToolkit
Assuming you typed it correctly and it encountered no problems, you should see this:
... and you should now see a reference to the Microsoft.Phone.Controls.Toolkit in the References section of the Solution Explorer for the AroundMe project:
This NuGet package included some additional content ... a folder called Toolkit.Content with a few icon files, and a README_FIRST.txt file:
The README_FIRST.txt file explains the purpose of the icons:
3. Implement the LongListMultiSelector
Ok, so now we're ready to modify our SearchResults.xaml page. We'll be upgrading the LongListSelector control to the LongListMultiSelector control, changing a few attributes to enable the enhanced features we'll utilize:
Before we can use it, we'll need to create an XML Namespace entry in the PhoneApplicationPage element at the very top of the page. See line 9:
This XAML Namespace basically says this ... when you see an XAML element prefixed with toolkit, then look in the following assembly and the following CLR namespace for that class' definition. Somewhere in the Windows Phone Toolkit code, there's a namespace defined as Microsoft.Phone.Controls.Toolkit, and it has a class named LongListMultiSelector, among others. So, the compiler parses the element <toolkit:LongListMultiSelector />, and it knows to create an instance of that specific class.
In a nutshell, that's all there is to it, but you can learn even more about XAML Namespaces and mapping to custom classes and assemblies here: http://msdn.microsoft.com/en-us/library/ms747086.aspx#Mapping_To_Custom_Classes_and_Assemblies
Now that we have the XAML Namespace defined, we'll be able to reference the LongListMultiSelector like so:
We can salvage most of the code, however we'll ...
- Change from <phone:LongListSelector to <toolkit:LongListMultiSelector as well as the closing element (line 51).
- Add the EnforceIsSelectionEnabled="True" attribute and setting. This property is important: it's what actually allows for the multi-selection behavior.
- Change from <phone:LongListSelector.ItemTemplate to <toolkit:LongListMultiSelector.ItemTemplate as well as the closing element (line 50).
Finally, we'll test to make sure we can actually multi-select:
Just to recap, the big take away from this lesson is the Windows Phone toolkit ... what it is, what additional features it supplies, how to incorporate it into our app through NuGet and adding the XAML namespace, and so on. In most cases, all we have to do is think about the features we want to support and focus on those ... most of the heavy lifting has been done by someone else. Nonetheless, we need to be aware that these resources exist and know how to add them into our project.