XamInputs – a Cross-platform Editing Experience

Damyan Petev / Wednesday, October 26, 2011

It has been a part of the company strategy to create a common experience while using our controls across all XAML platforms – something here at Infragistics we call the Unified XAML Product Strategy. Controls build on top of it are meant for rich Line of Business applications while providing the flexibility of being able to pick a platform and maintain similar code and features.

This article will cover one of the newest members of the cross-platform team – the xamInputs. It’s really a group of controls:

  • xamCurrencyInput™
  • xamDateTimeInput™
  • xamNumericInput™
  • xamMaskedInput™

The Masks

Numerous and diverse, those are mask you 'put’ on xamInput controls not to make them look prettier but to make them work. Admittedly one of the most basic yet the most outstanding feature of these controls, masks provide an easy way to give some meaningful hint to the user on how the required data should be formatted and in the same time restrict entry of unnecessary characters. They range from stings consisted of Mask characters and literals to pretty much setting up rules. Let me give you an example:

  • You can make a phone number mask with required (‘#’) or non-required (‘9’) digits like so – “(###)####-###” or just “(999)9999-9999”.


  • You can have text consisting of required (‘A’) or not (‘a’) characters, you can enforce upper (‘>’) or lower (‘<’) case and make a name template–

“>A<Aaaaaa  >A<Aaaaaaaa  >A<Aaaaaaa”

  • Then you have the masks that look like so – {char:n:s} where you can pretty much set number of placeholders and acceptable characters –

“{chars:10:01}” would accept up to 10 digits of binary code (zeros and ones)

  • There’s also things like {date} and {time} masks that would correspond to the system’s culture they are on and a {LOC} escape that can be used to localize date separators in “dd/mm/yyyy” or the thousands/decimal separators.

The list goes on and documentation will provide a nice table with descriptions and suggested xamInputs where each mask is relevant. Oh and the controls can still be styled to be prettier

The Inputs

All of the controls share a basic set of properties - the Mask for one, a behaviour setting when the value entered is not valid, text to display when there is no value and a char to use for placeholder hints. There are Spin buttons to use with numeric-based inputs. There are 3 separate modes you can set in terms of how the Input handles data – whether it should be just the raw user input, or should it include literals or prompt chars or both:

- DataMode - controls the actual value (Value property) stored in the xamInputs

- DisplayMode – controls what is displayed

- ClipMode – controls what will be copied to the clipboard

You can also set the value type which in terms will automatically restrict the input rejecting incorrect characters and also parses the data to the correct object type.

Setting up the project to use is really easy – you will need to add references to the XAML platform base assembly and the ones for the controls (e.g. ‘InfragisticsSL4.v11.2 ‘ and ‘InfragisticsSL4.Controls.Editors.XamMaskedInput.v11.2’), then add the namespace in XAML,

  1. xmlns:ig="http://schemas.infragistics.com/xaml"

and make a few common settings (in this example XamMaskedInput can be replaced with xamCurrencyInput, etc. ):

  1. <ig:XamMaskedInput InvalidValueBehavior="DisplayErrorMessage"
  2.                    InvalidChar="XamMaskedInput_InvalidChar"
  3.                    DataMode="Raw"
  4.                    DisplayMode="IncludeBoth"
  5.                    ClipMode="IncludeLiteralsWithPadding"
  6.                    NullText="Enter phone number here :)"
  7.                    PromptChar="_"
  8.                    Mask="(###)###-####"/>


This control is rather simplistic textbox that can be utilized when in need of numeric values for currency. While not all that sophisticated it does come with all of the above options to toy with, but its usefulness comes from the fact it’s ready to use right on the spot – it will enforce numeric input with 2 positions after the separator and display the entry with localized by the system culture currency sign:


You could of course specify the currency sign and as it is made obvious above you can enable spin buttons.


Along with all else again like the xamCurrencyInput, this one will restrict entry of all but digits and will default a date mask with localized date format. Also it will not accept only zeros for days/months/year or values greater than 31 for days and 12 for months. The spin buttons are available here too and there’s an auto-fill option that can enter the year or month along with it if the user skips them.

The xamDateTimeInput also comes with one outstanding feature – a dropdown calendar that lets users pick the date right there and have it entered for them. And it’s smart enough to show days of the month with standard date mask and just months view when set to just “mm/yyyy” or even not show it at all if mask is a time.



The xamNumericInput as the name suggest also accepts only digits and they can be restricted not only via a mask but by a minimum and maximum values. Again it’s useable with spin buttons.


The examples above uses masks like "{}{number:0-100} %" (restricts the number entered to maximum 100) and "55 \+ 33 \= {number:80-88}" (makes it impossible to enter number higher than 88 and below 80 a message informs value must be greater).


This is the control all others derive from and as such offers the widest variety of masks and values types and providing all the common functionality mentioned. This is the editor of choice when it comes to assisting end users when it comes to data input other than numbers.


The xamInputs while offering *many* masks and options to narrow down behaviour, also fire quite a few events to handle and add a bit of personal touch or just fine-tune the experience. Handles are declared in XAML as seen above and here’s a sample method too:

  1. private void XamCurrencyInput_InvalidChar(object sender, Infragistics.Controls.Editors.InvalidCharEventArgs e)
  2.         {
  3.             MessageBox.Show("The character '" + e.Char + "' is not valid!");
  4.             //do other stuff here, log wrong entry attempts, color it red , etc.
  5.         }

This is of course an addition to the behaviour the controls have on invalid input - like displaying messages, reverting the value or even keeping it no matter what.

One other nice thing is they can be used to edit values for cells inside a XamGrid™!

And the last but not least is you can grab the code from, say, a Silverlight project and copy it in a WPF one just like I did. What I did was make a fresh WPF project, add the references and… Well copy-paste the *.xaml files over, rename the MainPage to MainWindow and hit run – it is that simple


The xamInputs are here to enhance data input wherever you may need it - be it a Silverlight or WPF application - online or on a desktop; or even mobile on a Windows Phone app. They provide diverse options to ease the user and the check if the entered data meets the application’s requirements and can do that while being used as standalone textbox controls or even as cells inside a XamGrid.

A demo showing most of the main features used in both Silverlight and WPF is available here. Keep in mind assemblies from the 11.2 Release (can be trial) are required.