PhoneTextBox in the Silverlight Toolkit
Today the Windows Phone and Silverlight teams at Microsoft released an update to the Silverlight Toolkit. The toolkit is an open source collection of controls that Windows Phone 7 developers can use in their applications. In addition, the kit is localized into all 21 languages supported by WP7 “Mango.”
The Windows Phone Developer Blog has a complete list of the new controls:
LongListSelector has been rebuilt and redesigned to take advantage of the new smooth scrolling and off-thread touch input support in ‘Mango’. This is a buttery-smooth control for showing lists, including grouping and jump list support.
MultiselectList control enables multiple selection for easily working with lists of data, similar to the Mail app’s capability.
LockablePivot adds a special mode to the Pivot control where only the current item is shown (often used with multiple selection).
ExpanderView is a primitive items control that can be used for expanding and collapsing items (like the threaded views in the Mail app).
HubTile lets you add beautiful, informative, animated tiles to your application, similar to the new People groups in ‘Mango’.
ContextMenu control has been reworked: performance improvements and visual consistency fixes.
ListPicker now supports multiple selection.
RecurringDaysPicker lets your users select a day of the week.
Date & Time Converters localized to 22 languages. The converters let developers easily display date and time in the user interface in one of the many styles found throughout the phone’s UI, from a short date like ‘7/19’ to relative times like ‘about a month ago’.
Page Transitions have improved performance for a more responsive feel.
PhoneTextBox is an early look at an enhanced text box with action icon support, watermarking, etc.
All error messages and interface elements have been localized to all of the supported languages, making for a great experience for users around the world.
PhoneTextBox
Among these new controls and features is the PhoneTextBox, an addition developed by me during my internship at Microsoft this summer. This simple control adds a lot of new functionality to the Silverlight TextBox and is really easy to use.
To use it in your app, make sure that the toolkit is referenced in your application and that you have added the XML Namespace in your XAML. If you are already using the Toolkit in your app you won’t have to do this again.
After that’s done, you can simply replace any existing references of the Silverlight TextBox with the PhoneTextBox. For example:
<toolkit:PhoneTextBox Text="Hello World!" />Hint Text
One of the three new features in the PhoneTextBox is "Hint Text." It's kind of like the Placeholder in HTML5. While the WP7 Developer Documentation states that there is a Watermark attribute to the TextBox, it was never implemented and is a dead end. The PhoneTextBox implements this feature by adding a couple of new properties:
Hint- A string that will be displayed in the text box when there is no Text and the control is not in focus.
HintStyle- This allows you to customize the style of the Hint.
Action Icon
The second feature of the PhoneTextBox is called the "Action Icon," a small, 26 by 26 pixel icon that sits in the (bottom) right hand corner. Developers can attach events to the icon that will be called when the icon is tapped.
ActionIcon- An ImageSource that will be displayed on the right side of the control. If the text box is multiline or supports wrapping, it will be shown in the bottom right.
ActionIconTapped- An event that is called when the action icon is tapped. The control will not get focus or open the keyboard when the icon is tapped.
Length Indicator
Lastly, there is a length indicator built into the PhoneTextBox that can prevent users from entering more than a certain number of characters, but provide feedback as to how many characters they have already input.
This feature is more complex and flexible because it has a few different "modes" of operation. First, a developer can simply set a MaxLength and set the LengthIndicatorVisibility to true. The length indicator will always be visible and will display the number of characters entered into the text box out of the MaxLength. (ie. 125/140)
Secondly, a developer can set a LengthIndicatorThreshold. This property determines after how many characters the length indicator should pop down. For example, if the threshold is 20, the length indicator will be hidden if there are 18 characters in the text box. However, once 20 characters have been entered into the text box the length indicator will slide down.
Third, a "soft limit" can be imposed on the text box. In this case, a developer does not set a MaxLength, but rather sets a DisplayedMaxLength. In this scenario, the user can enter more than DisplayedMaxLength characters, much like how the Messaging app behaves in "Mango" for text messages.
LengthIndicatorVisibility- A boolean that determines whether the length indicator is visible or not.
LengthIndicatorThreshold- An integer that determines when the length indicator hides or slides down. Note that LengthIndicatorVisibility must be set to true if you ever want the length indicator to be shown.
DisplayedMaxLength- An integer that overrides the default behavior of showing the format N/MaxLength, where N is the number of characters entered. If DisplayedMaxLength is set, the format will be N/DisplayedMaxLength.
You can also check out the sample app included with the Toolkit to see how you can mix and match these different components.
This is a great new update to the Silverlight Toolkit and I am excited to be a part of this release. If you have any feedback, feel free to use the Issue Tracker on CodePlex.
P.S. If you are using the PhoneTextBox in your app, I'd love to hear from you!