×
Namespaces

Variants
Actions
(Difference between revisions)

Auto-scrolling ListBox for Windows Phone

From Nokia Developer Wiki
Jump to: navigation, search
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix metadata)
hamishwillee (Talk | contribs)
m (Hamishwillee - Subedited)
Line 1: Line 1:
[[Category:Silverlight]][[Category:Windows Phone]][[Category:Code Examples]][[Category:Code Snippet]][[Category:UI]]
+
[[Category:Windows Phone]][[Category:UI]][[Category:Silverlight]][[Category:Code Examples]]
{{Abstract|This article explains how to build auto scroll List Box }}
+
{{Abstract|This code example explains how to create a [http://msdn.microsoft.com/en-us/library/ms611062(v=vs.95).aspx ListBox] which automatically scrolls through and highlights its items.}}
  
 
{{ArticleMetaData <!-- v1.2 -->
 
{{ArticleMetaData <!-- v1.2 -->
Line 27: Line 27:
 
== Introduction ==
 
== Introduction ==
  
This article explains how to scroll a list box programmatically and that seems it is circular scroll list box in Windows Phone application. When you want to show dynamic data and it is added as a new list item to a list control at the last item of list control and it will automatically scroll and show on the screen. This concept can be use in multiple domains to represent dynamic data on the phone screen such as banking, stock market, feeds, social network status/data update etc.
+
Auto scrolling lists are useful for displaying information that is regularly updated, but where there is also value in showing historical and trend information (for example, stock market updates, data feeds, social network status/data update etc.
In Windows Phone list box control contain [http://msdn.microsoft.com/en-us/library/system.windows.controls.listbox.scrollintoview(v=vs.95).aspx ScrollIntoView()] method that allows you to scroll particular list box item.
+
  
'''Require component for this solution:'''
+
The auto-scrolling {{Icode|ListBox}} provided by this article is displayed in the animated gif below. The box navigates to each item in turn (ensuring it is visible) using [http://msdn.microsoft.com/en-us/library/system.windows.controls.listbox.scrollintoview(v=vs.95).aspx ListBox:ScrollIntoView()] and highlights the item by setting it as ''Selected''. At the end of the list the selection returns to the first item and continues. A [http://msdn.microsoft.com/en-us/library/system.windows.threading.dispatchertimer.aspx DispatcherTimer] is used to control the rate of movement through the items.
  
#Custom List Control with XAML
+
[[File:Wmdev-0000autoscroll.gif|frame|none|Auto scrolling list]]
#Sample Data Class
+
#Sample Data Load
+
#Dispatcher Timer API
+
  
=== Development ===
+
== Architectural overview==
  
'''Design Custom List using XAML''': It’s totally depended on the requirement how data will be represent on the screen. In this example a list component item will contain an image, user name and group.
+
The main components of this solution are listed below:
 +
#Custom List Control (XAML) - definition of the List and appearance of its list items in XAML
 +
#Sample List Data  - C# class defining the ''format'' of data to be displayed in the {{Icode|ListBox}} along with instances of the class that are bound to the {{Icode|ListBox}}
 +
#Dispatcher Timer API - C# code for iterating through the list items.
  
[[File:List Item Structure.png]]
+
These are discussed in the following sections
  
'''XAML Code'''
+
== Custom List Box definition (in XAML) ==
 +
 
 +
The XAML definition for the {{Icode|ListBox}} is given below:
 
<code xml>
 
<code xml>
 
<!--ContentPanel - place additional content here-->
 
<!--ContentPanel - place additional content here-->
Line 65: Line 66:
 
</code>
 
</code>
  
=== Sample Data Class ===
+
The {{Icode|ListBox}} has the name {{icode|lstSample}}, and is defined in terms of a [http://msdn.microsoft.com/en-us/library/system.windows.datatemplate(v=vs.95).aspx DataTemplate]. The template describes the appearance of each item and includes named bindings for each element of those items. In this example a a list component item will contain an image, user name and group as shown below:
This class contains only required data members.
+
 
'''C# Code:'''
+
[[File:List Item Structure.png|frame|none|List item template]]
 +
 
 +
== Sample List Data ==
 +
The sample list data is defined in the C# code behind, as shown below. Note that as required in the XAML binding definition above the properties are named {{Icode|Name }}, {{Icode|Group}}, and {{Icode|ImagePath}},
 +
 
 
<code csharp>
 
<code csharp>
 
  public class SampleData
 
  public class SampleData
Line 77: Line 82:
 
</code>
 
</code>
  
=== Sample Data Load ===
+
We then create instances of this data class for the list items, and set them as the source for the {{Icode|ListBox}}.  
Call the following code snippet in the constructor to load a Sample Data List and set item source of List Item Control with SimpleItems object of sample data.
+
'''C# code:'''
+
 
<code csharp>
 
<code csharp>
 +
//SimpleItems is a list containing items of class SampleData
 
SimpleItems = new List<SampleData>()  
 
SimpleItems = new List<SampleData>()  
 
{  
 
{  
Line 88: Line 92:
 
};
 
};
  
// set data Source to list  
+
//Bind the list data to the ListBox (note that lstSample is the name of the list defined in the XAML)
 
this.lstSample.ItemsSource = SimpleItems;
 
this.lstSample.ItemsSource = SimpleItems;
 
</code>
 
</code>
  
=== Dispatcher Timer API ===
+
== Dispatcher Timer API ==
Finally we will call the [http://msdn.microsoft.com/en-us/library/system.windows.threading.dispatchertimer.aspx DispatcherTimer] API to Scroll list item certain time of period.
+
Finally we will call the [http://msdn.microsoft.com/en-us/library/system.windows.threading.dispatchertimer.aspx DispatcherTimer] API to iterate through the items.
'''C# code:'''
+
  
 
<code csharp>
 
<code csharp>
Line 103: Line 106:
 
</code>
 
</code>
  
'''DispatcherTimer Event Handler'''
+
When the timer triggers we call the {{Icode|timer_Tick}} event handler, which scrolls to the current index and marks it as selected, and then updates the index. After the last item is highlighted the index is reset to the first item.
 
+
 
<code csharp>
 
<code csharp>
 
void timer_Tick(object sender, EventArgs e)
 
void timer_Tick(object sender, EventArgs e)
Line 124: Line 126:
 
</code>
 
</code>
  
=== Run it using F5 key ===
+
Run it using F5 key  
 
+
'''Output Screen'''
+
 
+
[[File:Wmdev-0000autoscroll.gif]]
+
  
=== References ===
+
== References ==
 
# [http://msdn.microsoft.com/en-us/library/system.windows.controls.listbox.scrollintoview(v=vs.95).aspx ScrollIntoView()]
 
# [http://msdn.microsoft.com/en-us/library/system.windows.controls.listbox.scrollintoview(v=vs.95).aspx ScrollIntoView()]
 
# [http://msdn.microsoft.com/en-us/library/6sh2ey19(v=vs.95).aspx List<T> Class]
 
# [http://msdn.microsoft.com/en-us/library/6sh2ey19(v=vs.95).aspx List<T> Class]
 
# [http://msdn.microsoft.com/en-us/library/system.windows.threading.dispatchertimer.aspx DispatcherTimer Class]
 
# [http://msdn.microsoft.com/en-us/library/system.windows.threading.dispatchertimer.aspx DispatcherTimer Class]
# [[Application Bar for Windows Phone|Application Bar for Windows Phone]]
+
# [[Application Bar for Windows Phone]]
  
  

Revision as of 05:31, 3 October 2012

This code example explains how to create a ListBox which automatically scrolls through and highlights its items.

WP Metro Icon UI.png
SignpostIcon XAML 40.png
SignpostIcon WP7 70px.png
Article Metadata
Code ExampleTested with
SDK: Windows Phone 7.1
Devices(s): Nokia Lumia 710,800
Compatibility
Platform(s): Windows Phone 7.5 (mango)
Windows Phone 7.5
Article
Created: pavan.pareta (02 Oct 2012)
Last edited: hamishwillee (03 Oct 2012)

Contents

Introduction

Auto scrolling lists are useful for displaying information that is regularly updated, but where there is also value in showing historical and trend information (for example, stock market updates, data feeds, social network status/data update etc.

The auto-scrolling ListBox provided by this article is displayed in the animated gif below. The box navigates to each item in turn (ensuring it is visible) using ListBox:ScrollIntoView() and highlights the item by setting it as Selected. At the end of the list the selection returns to the first item and continues. A DispatcherTimer is used to control the rate of movement through the items.

Auto scrolling list

Architectural overview

The main components of this solution are listed below:

  1. Custom List Control (XAML) - definition of the List and appearance of its list items in XAML
  2. Sample List Data - C# class defining the format of data to be displayed in the ListBox along with instances of the class that are bound to the ListBox
  3. Dispatcher Timer API - C# code for iterating through the list items.

These are discussed in the following sections

Custom List Box definition (in XAML)

The XAML definition for the ListBox is given below:

<!--ContentPanel - place additional content here-->
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
<StackPanel Orientation="Horizontal">
<ListBox x:Name="lstSample">
<ListBox.ItemTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal">
<Image Source="{Binding ImagePath}" Stretch="None"/>
<StackPanel Orientation="Vertical">
<TextBlock Text="{Binding Name}" FontSize="45"/>
<TextBlock Text="{Binding Group}" FontSize="25"/>
</StackPanel>
</StackPanel>
</DataTemplate>
</ListBox.ItemTemplate>
</ListBox>
</StackPanel>
</Grid>

The ListBox has the name lstSample, and is defined in terms of a DataTemplate. The template describes the appearance of each item and includes named bindings for each element of those items. In this example a a list component item will contain an image, user name and group as shown below:

List item template

Sample List Data

The sample list data is defined in the C# code behind, as shown below. Note that as required in the XAML binding definition above the properties are named Name , Group, and ImagePath,

 public class SampleData
{
public string ImagePath { get; set; }
public string Name { get; set; }
public string Group { get; set; }
}

We then create instances of this data class for the list items, and set them as the source for the ListBox.

//SimpleItems is a list containing items of class SampleData
SimpleItems = new List<SampleData>()
{
new SampleData(){Name = "User1:", ImagePath="/Images/user.png", Group ="wiki"},
new SampleData(){Name = "User2:", ImagePath="/Images/user.png", Group="froum"},
new SampleData(){Name = "User3:", ImagePath="/Images/user.png", Group ="nokia"}
};
 
//Bind the list data to the ListBox (note that lstSample is the name of the list defined in the XAML)
this.lstSample.ItemsSource = SimpleItems;

Dispatcher Timer API

Finally we will call the DispatcherTimer API to iterate through the items.

// DispatcherTimer object declaration in constructor
timer = new DispatcherTimer();
timer.Interval = TimeSpan.FromMilliseconds(1500); //delayed for 1.5 seconds
timer.Tick += new EventHandler(timer_Tick);

When the timer triggers we call the timer_Tick event handler, which scrolls to the current index and marks it as selected, and then updates the index. After the last item is highlighted the index is reset to the first item.

void timer_Tick(object sender, EventArgs e)
{
lstSample.ScrollIntoView(lstSample.Items[index]); //scroll to the current item
lstSample.SelectedIndex = index; //highlight the selected item in the list box scroller
SampleData item = (SampleData)lstSample.Items[index]; // getting the current item
 
if (index < lstSample.Items.Count - 1)
{
index++;
}
else
{
lstSample.ScrollIntoView(lstSample.Items[0]); //scroll to the first item
index = 0; //reset the index when it reaches to the last item
}
}

Run it using F5 key

References

  1. ScrollIntoView()
  2. List<T> Class
  3. DispatcherTimer Class
  4. Application Bar for Windows Phone


~ Happy Coding ~

Sample Code

You can download sample code from File:WmDevAutoScrollListBox.zip.

467 page views in the last 30 days.
×