Windows Phone Toolkit PhoneTextBox in depth

published on: 8/30/2011 | Views: N/A | Tags: WP7Toolkit Mango

by WindowsPhoneGeek

Recently a new version of the Windows Phone Toolkit was released: Windows Phone Toolkit - August 2011 (7.1 SDK) with some pretty interesting new components. Previously we covered all toolkit components in our 21 WP7 Toolkit in Depth articles covering all controls so it is time to continue this series with a few more posts.

In this post I am going to talk about the new "PhoneTextBox" control in details. Basically, PhoneTextBox is an advanced TextBox control with ActionIcon support, Hints and more. It also exposes a set of properties for rich customization.

Getting Started

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

UPDATE: If you have installed the toolkit via  the .msi  then you will not see the PhoneTextBox in the list with available controls. However this is a known issue and hopefully it will be fixed soon. For now here is the official discussion: http://silverlight.codeplex.com/workitem/9414 .The workaround is to download and rebuild the source code.

You can select Microsoft.Phone.Controls.Toolkit.dll 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 PhoneTextBox control either in XAML or with C#.

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

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

<toolkit:PhoneTextBox Hint="UserName"/>

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

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

using Microsoft.Phone.Controls;

PhoneTextBox textBox = new PhoneTextBox();
textBox.Hint = "UserName";

Key Properties

PhoneTextBox derives from TextBox so it has all properties of the TextBox plus the following new ones:

• Hint

Hint is a dependency property of type string. It gets or sets the Hint of the PhoneTextBox control.

• HintStyle

HintStyle is a dependency property of type Style. It gets or sets the Hint Style of the PhoneTextBox control.

Example:

This example demonstrates how to add a simple HintStyle that changes only the FonFamily, FontSize and Foreground properties without changing the whole ControlTemplate.

<phone:PhoneApplicationPage.Resources>
  <Style TargetType="ContentControl" x:Key="HintCustomStyle">
    <Setter Property="FontFamily" Value="Calibri"/>
    <Setter Property="Foreground" Value="Aqua"/>
    <Setter Property="FontSize" Value="30"/>
  </Style>
</phone:PhoneApplicationPage.Resources>

<!--...-->

<toolkit:PhoneTextBox Hint="Enter UserName" HintStyle="{StaticResource HintCustomStyle}"/>

• ActualHintVisibility

ActualHintVisibility is a dependency property of type Visibility. It gets or sets whether the hint is actually visible.

• LengthIndicatorVisible

LengthIndicatorVisible is a dependency property of type Boolean. It determines whether the length indicator of the PhoneTextBox should be visible.

• LengthIndicatorTheshold

LengthIndicatorTheshold is a dependency property of type int. It determines the threshold after which the length indicator will appear.

Example:

<toolkit:PhoneTextBox Hint="Password" LengthIndicatorVisible="True" LengthIndicatorTheshold="10" />

• DisplayedMaxLength

DisplayedMaxLength is a dependency property of type int. It represents the displayed maximum length of text that can be entered. This value takes priority over the MaxLength property in the Length Indicator display.

Example:

<toolkit:PhoneTextBox Hint="Password" DisplayedMaxLength="4" LengthIndicatorVisible="True"/>

NOTE :In the given example you can enter more than 4 characters, but the length indicator displays the number of characters entered out of 4, even if the length of the text entered is greater than 4.

• ActionIcon

ActionIcon is a dependency property of type ImageSource. It gets or sets the ActionIcon image of the PhoneTextBox control.

Example1:

<toolkit:PhoneTextBox Hint="Search" ActionIcon="/Images/Search.png" ActionIconTapped="Search_ActionIconTapped"/>

private void Search_ActionIconTapped(object sender, EventArgs e)
        {
           //do some action here. I.e open MessageBox, etc.
           MessageBox.Show("The action icon was tapped!");
        }

Example2:

<toolkit:PhoneTextBox Hint="Password" ActionIcon="wpglogo.png"/>

 

Key Events

• ActionIconTapped

Occurs when the ActionIcon is tapped.

Example:

phoneTextBox.ActionIconTapped += new EventHandler(phoneTextBox_ActionIconTapped);
//...
void phoneTextBox_ActionIconTapped(object sender, EventArgs e)
{
    //...
}

That was all about the new "PhoneTextBox" from the Windows Phone Toolkit Aug 2011 in depth. Here is the full source code:

I hope that the post was helpful.

You can also follow us on Twitter @winphonegeek

Comments

Add comment to 'Windows Phone Toolkit PhoneTextBox in depth'

Title Your Name

Comment