Windows Phone Toolkit MultiselectList in depth | Part1: key concepts and API

原文地址：http://windowsphonegeek.com/articles/Windows-Phone-Toolkit-MultiselectList-in-depth--Part1-key-concepts-and-API

Windows Phone Toolkit MultiselectList in depth | Part1: key concepts and API

published on: 10/24/2011 | Views: 7622 | Tags: WP7Toolkit

1

2

3

4

5

Rate Now!

by WindowsPhoneGeek

One of the new components which comes with the latest update of the Windows Phone Toolkit - August 2011 (7.1 SDK)is MultiselectList . Basically, it is an advanced ItemsControl that has a multiple selection mode that allows users to select multiple items from a list. This is usually used in scenarios where the same action has to be applied over multiple items.

I will continue our "Toolkit in Depth" series  with two more posts that cover all about the Windows Phone MultiselectList control in details. In Part1 I am going to talk about key properties, methods, events and the main features of the Windows Phone MultiselectList control.

• Windows Phone Toolkit MultiselectList in depth| Part1: key concepts and API
• Windows Phone Toolkit MultiselectList in depth| Part2: databinding

Getting Started

To begin using MultiselectList first add a reference to the Microsoft.Phone.Controls.Toolkit.dll assembly in your Windows Phone application project.

NOTE: Microsoft.Phone.Controls.Toolkit.dll assembly is installed with the toolkit and you can find it in:

For 32-bit systems:

C:\Program Files\Microsoft SDKs\Windows Phone\v7.1\Toolkit\Aug11\Bin\Microsoft.Phone.Controls.Toolkit.dll

For 64-bit systems:

C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.1\Toolkit\Aug11\Bin\Microsoft.Phone.Controls.Toolkit.dll

Alternatively you can select it directly from the "...\Silverlight for Windows Phone Toolkit Source & Sample - Aug 2011\Bin\" if you have downloaded the "Silverlight for Windows Phone Toolkit Source & Sample - Aug 2011.zip" instead.

You can create an instance of the MultiselectList control either in XAML or with C#/VB.

• · Define an instance of the MultiselectList control in XAML: you have to add the following namespace declaration:    

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

?

1

2

3

4

5

<toolkit:MultiselectList>

    <toolkit:MultiselectItemContent="Item1"/>

    <toolkit:MultiselectItemContent="Item2"/>

    <toolkit:MultiselectItemContent="Item3"/>

</toolkit:MultiselectList>

NOTE: Make sure that your page declaration includes the "toolkit" namespace! You can do this by using Visual Studio Toolbox, Expression Blend Designer or just include it on your own.

• · Define an instance of the MultiselectList control in C#: just add the following using directive:

using Microsoft.Phone.Controls;

?

1

2

3

4

MultiselectList list = newMultiselectList();

list.Items.Add(newMultiselectItem() { Content = "Item1"});

list.Items.Add(newMultiselectItem() { Content = "Item2"});

list.Items.Add(newMultiselectItem() { Content = "Item3"});

Key Properties

• IsSelectionEnabled

IsSelectionEnabled is a dependency property of type bool. It gets or sets the flag that indicates whether the list is in selection mode or not.

• ItemInfoTemplate

ItemInfoTemplate is a dependency property of type DataTemplate. It gets or sets the data template that is to be used on the item information field of the MultiselectItems.

• ItemContainerStyle

ItemContainerStyle is a dependency property of type Style. It determines the Style that is applied to the MultiselectList control items.

• SelectedItems

SelectedItems is a read only property of type IList. It gets the collection of items that are currently selected.

Key Events

• SelectionChanged

Occurs when there is a change in the SelectedItems collection.

?

1

2

3

multiselectList.SelectionChanged += newSelectionChangedEventHandler(multiselectList_SelectionChanged);

voidmultiselectList_SelectionChanged(objectsender, SelectionChangedEventArgs e)

{//...}

• IsSelectionEnabledChanged

Occurs when the value of the IsSelectionEnabled property has changed.

?

1

2

3

multiselectList.IsSelectionEnabledChanged += newDependencyPropertyChangedEventHandler(multiselectList_IsSelectionEnabledChanged);

voidmultiselectList_IsSelectionEnabledChanged(objectsender, DependencyPropertyChangedEventArgs e)

{//...}

MultiselectItem

MultiselectItem represents a selectable item inside a MultiselectList.

NOTE: A MultiselectList contains a collection of MultiselectItem objects. To select a MultiselectItem in a MultiselectList, set the IsSelected property to true. Bind a MultiselectItem to data by binding the ItemsSource property of a MultiselectList to a data source.

MultiselectItem Key Properties & Events

• IsSelected

IsSelected is a dependency property of type bool. It gets or sets the flag that indicates if the item is currently selected.

• HintPanelHeight

HintPanelHeight is a dependency property of type double. It gets or sets the height of the hint panel.

• ContentInfo

ContentInfo is a dependency property of type object. It gets or sets the content information for the corresponding MultiselectItem.

• ContentInfoTemplate

ContentInfoTemplate is a dependency property of type DataTemplate. It gets or sets the data template that defines how the content information for the corresponding MultiselectItem is displayed.

• Selected

Occurs when the MultiselectItem is selected.

Example:

?

1

2

3

4

5

6

7

multiselectItem.Selected += newRoutedEventHandler(multiselectItem_Selected);

//...

 

voidmultiselectItem_Selected(objectsender, RoutedEventArgs e)

{

//...

}

• Unselected

Occurs when the MultiselectItem is unselected.

Example:

?

1

2

3

4

5

6

7

multiselectItem.Unloaded += newRoutedEventHandler(multiselectItem_Unloaded);

//..

 

voidmultiselectItem_Unloaded(objectsender, RoutedEventArgs e)

{

//...

}

That was all about the basic usage of MultiselectList from the Windows Phone Toolkit - August 2011 (7.1 SDK)  in depth.  In the next post I will talk about using the MultiselectList with data binding, so stay tuned.

NOTE: This article is based on our latest FREE e-book "Silverlight for Windows Phone Toolkit In Depth" which you can download here: http://windowsphonegeek.com/WPToolkitBook

You may also find interesting the following articles:

• Windows Phone Toolkit LockablePivot in depth
• Windows Phone Toolkit PhoneTextBox in depth
• Windows Phone HubTile in depth| Part1: key concepts and API
• Windows Phone HubTile in depth| Part2: Data Binding
• 21 WP7 Toolkit in Depth articles covering all controls

You can also follow us on Twitter @winphonegeek

Comments

Disable scrolling

posted by: theCake on 11/10/2011 5:14:52 PM

hey there, I'm having some trouble w/ a MultiselectList inside an ExpanderView inside a MultiselectList (yes, the same way as in the Email app...) The thing is, that you can scroll the lower-level-MultiselectList-Items up and down, which is very bad for the UI experience.. I tried to put: ScrollViewer.VerticalScrollBarVisibility="Disabled" in the MultiselectList but it won't help.

Do you have any ideas? ~theCake

How to disable the scrolling on multiselectcontrol

posted by: Fabian on 1/30/2012 5:49:58 PM

If you look into the Windows Phone Toolkit source code, in Generic.xaml, you would see this code:

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

<Style TargetType="controls:MultiselectList">

    <Setter Property="Background"Value="Transparent"/>

    <Setter Property="Foreground"Value="{StaticResource PhoneForegroundBrush}"/>

    <Setter Property="ScrollViewer.HorizontalScrollBarVisibility"Value="Disabled"/>

    <Setter Property="ScrollViewer.VerticalScrollBarVisibility"Value="Auto"/>

    <Setter Property="BorderThickness"Value="0"/>

    <Setter Property="BorderBrush"Value="Transparent"/>

    <Setter Property="Padding"Value="0"/>

    <Setter Property="Template">

        <Setter.Value>

            <ControlTemplate TargetType="controls:MultiselectList">

                <ScrollViewer x:Name="ScrollViewer"BorderBrush="{TemplateBinding BorderBrush}"

                              BorderThickness="{TemplateBinding BorderThickness}"

                              Background="{TemplateBinding Background}"

                              Foreground="{TemplateBinding Foreground}"

                              Padding="{TemplateBinding Padding}">

                    <ItemsPresenter/>

                </ScrollViewer>

            </ControlTemplate>

        </Setter.Value>

    </Setter>

    <Setter Property="ItemsPanel">

        <Setter.Value>

            <ItemsPanelTemplate>

                <VirtualizingStackPanel/>

            </ItemsPanelTemplate>

        </Setter.Value>

    </Setter>

</Style>

The scrollviewer is placed in the template definition.

So, you can disable the multiselect scrollviewer just placing this code inside your MultiSelect tag.

?

1

2

3

4

5

<toolkit:MultiselectList.Template>

    <ControlTemplate TargetType="toolkit:MultiselectList">

        <ItemsPresenter/>

    </ControlTemplate>

</toolkit:MultiselectList.Template>

Enjoy =D

display checkbox by default

posted by: Oliver on 7/3/2012 6:09:16 AM

How can the checkboxes for multiselectlist be displayed by default?

Add comment to 'Windows Phone Toolkit MultiselectList in depth | Part1: key concepts and API'