WP7 LongListSelector in depth | Part1: Visual structure and API

In the "WP7 LongListSelector in depth" series of two posts I am going to talk about the key properties, methods, events and the main features of the windows phone 7 LongListSelector in details. In the first "Part1: Visual structure and API " I will explain the visual structure of the control and all abut the available public API. In "Part2: Data binding scenarios" I will talk about using the API and populating LongListSelector in different ways.

One of the new components in the November update of the Silverlight Toolkit is the LongListSelector which is actually an advanced ListBox that supports full data and UI virtualization, flat lists and grouped lists. It helps users to scroll through long lists of data. Basically a quick jump grid overlays the list when the user select one of the group headers after that when an item is selected from the grid the user is automatically redirected back to the long list at the selected point.

(For more information about all new controls in the updated version of the toolkit please visit the previous article.)

To begin using LongListSelector first add a reference to the Microsoft.Phone.Controls.Toolkit.dll assembly which is installed with the toolkit and you can find it in : C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Toolkit\Nov10\Bin\Microsoft.Phone.Controls.Toolkit.dll.

You will also need to add the "toolkit" prefix declaration. Make sure that your page declaration includes the "toolkit" namespace:

Note:Part1 is focused on explaining the structure and the api in details so I will use the example given in the toolkit demos. You can get is from here. In "Part2: Data binding scenarios"I will give more examples and the full source code will be available for download. Generally when talking about the LongListSelector and populating it with data you have two chaises:

to use it as a standard ListBox with flat lists.

to use it as an advanced ListBox with grouped lists.

Visual structure

Flat List scenario

When using LongListSelector in flat mode it behaves as a ListBox with header and footer(without any groups). In the following schemes you can see the basic visual elements:

Grouped List scenario

In the following schemes you can see the basic visual elements:

Now lets focus on some of the most specific and important properties of the LongListSelector.

Key Properties

BufferSizeBufferSize is a dependency property of type double. It controls the number of "screens" (as defined by the ActualHeight of the LongListSelector) above and below the visible items of the list that will be filled with items. The default value is "1.0".

DisplayAllGroupsDisplayAllGroups is a dependency property of type bool. It displays all groups whether or not they have items.The default is false.

GroupFooterTemplateGroupFooterTemplate is a dependency property of type DataTemplate. It provides the template for the groups in the items view.

GroupItemsPanelGroupItemsPanel is a dependency property of type ItemsPanelTemplate. It specifies the panel that will be used in group view mode. Example:
<toolkit:LongListSelector.GroupItemsPanel>
<ItemsPanelTemplate>
<toolkit:WrapPanel Orientation="Horizontal"/>
</ItemsPanelTemplate>
</toolkit:LongListSelector.GroupItemsPanel>

IsBouncyIsBouncy is a dependency property of type bool. It controls whether the list can be (temporarily) scrolled off of the ends.

IsFlatList IsFlatList is set to true when the list is flat instead of a group hierarchy.

IsScrollingIsScrolling is a dependency property of type bool. It returns true if the user is manipulating the list, or if an inertial animation is taking place.This property has a private seter so you can only get its value.

ItemTemplateItemTemplate is a dependency property of type DataTemplate. It provides the template for the items in the items view.

StretchingTopRaised when IsBouncy is true and the user has dragged the items down from the top as far as they can go. Example:
selector.StretchingTop += new EventHandler(selector_StretchingTop);
void selector_StretchingTop(object sender, EventArgs e)
{...}

UnlinkIndicates that the ContentPresenter with the item is being recycled and is becoming "un-realized".

Animate the scrolling of the list to the specified item. Scrolling speed is capped by MaximumFlickVelocity. (The item to scroll to).

DisplayGroupViewC#:
public void DisplayGroupView()

Will invoke the group view, if a GroupItemTemplate has been defined.

GetItemsInViewC#:
public ICollection<object> GetItemsInView()

Returns all of the items that are currently in view. This is not the same as the items that have associated visual elements: there are usually some visuals offscreen. This might be an empty list if scrolling is happening too quickly.Returns The items in view.

ScrollTo(object item)C#:
public void ScrollTo(object item)

Instantly jump to the specified item(The item to scroll to).

That was all about the windows phone 7 LongListSelector structure, key properties, methods and events and the end of Part1 of this article. In the next "Part2: Data binding scenarios" I will talk about using the API and populating LongListSelector in different ways.

Comments

Really veryuseful info

The sample in Toolkit is not self explanatory, these details are very nice and Thanks for it...

List item selection

posted by: Leny on 11/26/2010 10:05:14 AM

Is it possible to highlight the currently selected item like the standard listbox?

RE:List item selection

posted by: winphonegeek on 11/26/2010 3:06:02 PM

In the default implementation of LongListSelector you can not highlight the currently selected item. The only available VisualStates are:

Scrolling

NotScrolling

which are in the "ScrollStates" VisualStateGroup.

flat list crash

posted by: Rick P on 11/30/2010 9:30:16 PM

Thanks for the great description and example!

I figured that I would share the one minor issue that I ran into when working with this. I was trying to use the LongListSelector as a flat list, and I did not explicitly set IsFlatList="true" (which seems to default to false). That was causing me to get a NullReferenceException in my data model constructor... I figured that I would share my experience since I did not immediately associate that exception with that control setting.

Can't get ScrollTo to work

posted by: Ian on 12/15/2010 10:24:46 PM

Thank you for your great article.

Can you tell me how I go about scrolling to a specific item when a page containing a longlistselector is first loaded?

The reason I ask is I get a null exception on using ScrollTo(). On looking in the source code I noticed that when I call it is before the LongListSelector method OnApplyTemplate() is called - which means it hasn't yet initialized _panningTransform (used by the ScrollTo method).

If I modify the toolkit source code (which obviously I don't want to make a habit of ! ;) so that I can subscribe to a sort of ListBoxNowLoaded event (so that I call ScrollTo after _panningTransform has been intialised), it doesn't throw any errors, but it just turns my longlistselector blank (where my items used to be).

Any help much appreciated as I'm quite confused now and really need to be able to auto scroll to an initial point in the list.

RE:Can't get ScrollTo to work

posted by: Ian on 12/20/2010 2:50:56 PM

Thanks a lot for getting back to me on that - much appreciated. All working now :)

Extremely slow scrolling

posted by: C on 3/22/2011 4:23:10 PM

Has anyone else had issues with initiating scrolling of a LongListSelector? I'm having this problem right now, where once it begins scrolling it's just fine.. but it's very difficult for the user to get a 'grip' on the longlist to scroll it. I have to touch the screen for at least half a second before I can move my finger, otherwise it won't scroll when I move my finger.

Scolling issue

posted by: Brandon on 3/31/2011 4:26:39 AM

@C I am experiencing the exact same issue, furthermore, it seems that touching on any 'whitespace' between or beyond the records fails to initiate the scroll altogether.

Scrolling issue

posted by: C on 3/31/2011 6:57:58 PM

@Brandon - I found a solution to the problem, although it's extremely distasteful.

I also noticed that the problem was that the "whitespace" was not hit-testable (even though I marked it to be in the XAML code). My LongListSelector was transparent, so I changed the background color so that its alpha color was one notch away from fully transparent. This fixed the problem of not being grabbable, but it makes the LongListSelector slightly darker looking than everything else since I really wanted it to be fully transparent.

SDE

posted by: Rukai on 6/6/2011 1:01:11 PM

Hi

Do you guys know how I can let the longlistselector present a behavior like listbox?
(i.e have a click effect on it with TiltEffect)..

Re SDE

add toolkit:TiltEffect.IsTiltEnabled="True" in end of phone:PhoneApplicationPage

how to get a group info

posted by: ding on 10/14/2011 6:44:52 AM

now i can get a item info of group by LongListSelector.SelectionChanged event.but how to get a group info?
thanks

RE: how to get a group info

posted by: winphonegeek on 10/19/2011 1:17:28 PM

with the current implementation of the LongListSelector it seems that the easiest way to get a reference to the group item of the selected item would be to have a property in the item class that will hold the reference to the corresponding group item

WP7 LongListSelector : customized

posted by: anoop on 12/13/2011 4:23:54 PM

When we scroll through the list of items, the boxed letter(list header) stays on the top of the list and is then replaced with the next letter when you get to it?
how it is possible?

How to chage selectItem color

posted by: Moreira on 2/7/2012 7:06:01 PM

What its the default style to costumize the LongListSelector? And how i can change the color od the selected item?

setting the selected item

posted by: mayhem software on 3/1/2012 5:25:24 AM

Great article this list works well. I cannot seem to set the selecteditem to my default item and scroll to when my app first starts up.

The following code runs without issue but when I look at my list the selected item is null.

var cityByContinent = from timeZone in timeZoneSource
group timeZone by timeZone.Region into c
orderby c.Key
select new Group(c.Key, c);

setting the selected item

Apparently the problem I described above is a bug in the toolkit. SelectedItem is implemented as a simple property, instead of a Dependency Property.

http://silverlight.codeplex.com/workitem/9360

Chris
www.mayhemsoftware.com

sticky first group header

posted by: vovich on 7/20/2012 9:17:39 PM

Hello. I'm trying to achive the same effect for group headers as in contacts list in wp7 for "a" "b" "c" ... headers.I've used LongListSelector with a group template, but i need a first group header stay at the top of the list, untill it will be pushed out by next header while scrolling. But I do not know how to do it. Could somebody help me with it. I do not know where to start from. Any information would be helpful.

Scrolling not functioning

posted by: Mayur Sirwani on 9/8/2012 4:36:02 PM

Hey,

When i click on any GroupHeader the list of keys comes up. But when i click on any key it doesn't scrolls to that GroupHeader.