×
Namespaces

Variants
Actions
(Difference between revisions)

Auto-scrolling ListBox for Windows Phone

From Nokia Developer Wiki
Jump to: navigation, search
pavan.pareta (Talk | contribs)
(Pavan.pareta - - Development)
hamishwillee (Talk | contribs)
m (Text replace - "[[Category:Silverlight" to "[[Category:XAML")
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Silverlight]][[Category:Windows Phone]][[Category:Code Examples]][[Category:Code Snippet]][[Category:UI]]
+
[[Category:Windows Phone]][[Category:UI]][[Category:XAML]][[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 -->
|sourcecode= [[File:WmDevAutoScrollListBox.zip]]
+
|sourcecode= [[Media:WmDevAutoScrollListBox.zip]]  
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|devices= Nokia Lumia 710,800
 
|devices= Nokia Lumia 710,800
Line 9: Line 9:
 
|platform= Windows Phone 7.5 (mango)
 
|platform= Windows Phone 7.5 (mango)
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->  
+
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
+
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
|translated-from-title= <!-- Title only -->  
+
|translated-from-title= <!-- Title only -->
 
|translated-from-id= <!-- Id of translated revision -->
 
|translated-from-id= <!-- Id of translated revision -->
|review-by=<!-- After re-review: [[User:username]] -->
+
|review-by= <!-- After re-review: [[User:username]] -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
|creationdate= <!-- Format YYYYMMDD -->
+
|creationdate= 20121002
|author= <!-- Display as link [[User:username]] -->
+
|author= [[User:Pavan.pareta]]
 
}}
 
}}
  
 
== Introduction ==
 
== Introduction ==
  
This article explains how to scroll list box programmatically that seem circular scroll, a list box in Windows Phone application. When you want to show dynamically added list item will automatically 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, social network status/data update etc.
+
Auto scrolling lists are not only useful for displaying informations that is regularly updated, but also where some meaningful information may be displayed. It can be a pattern, trend or some historical information (for example, stock market updates, data feeds, flight information display systems, 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}} illustrated in this article is displayed in the animated gif image 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 repeats the iteration. 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
 +
 
 +
== Custom List Box definition (in XAML) ==
 +
 
 +
The XAML definition for the {{Icode|ListBox}} is given below:
  
'''XAML Code'''
 
 
<code xml>
 
<code xml>
 
<!--ContentPanel - place additional content here-->
 
<!--ContentPanel - place additional content here-->
Line 65: Line 67:
 
</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 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 83:
 
</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 93:
 
};
 
};
  
// 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 107:
 
</code>
 
</code>
  
'''DispatcherTimer Event Handler'''
+
When the timer is triggerd, 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 127:
 
</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]
# [http://www.developer.nokia.com/Community/Wiki/Application_Bar_for_Windows_Phone| Application Bar for Windows Phone]
+
# [[Application Bar for Windows Phone]]
  
  
Line 140: Line 139:
  
 
== Sample Code==
 
== Sample Code==
You can download sample code from [[File:WmDevAutoScrollListBox.zip]].
+
You can download sample code from [[Media:WmDevAutoScrollListBox.zip]].[[Category:Windows Phone 7.5]]

Revision as of 04:29, 10 April 2013

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 (10 Apr 2013)

Contents

Introduction

Auto scrolling lists are not only useful for displaying informations that is regularly updated, but also where some meaningful information may be displayed. It can be a pattern, trend or some historical information (for example, stock market updates, data feeds, flight information display systems, social network status/data update etc).

The auto-scrolling ListBox illustrated in this article is displayed in the animated gif image 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 repeats the iteration. 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 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 is triggerd, 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 Media:WmDevAutoScrollListBox.zip.

410 page views in the last 30 days.