XamInputs and XamEditors

Damyan Petev / Thursday, November 10, 2011

The added in 11.2 new XamInputs (group of controls) are meant to guide the users during data entry and give you an opportunity to check if the entered data meets some predefined criteria and can be used as standalone or in combination with other controls – just like the XamEditors. There are a lot of similarities between them but also a few key differences. The biggest is of course that the new controls are cross-platform by design therefore you can use them in Silverlight or WPF interchangeably. There are also a few changes (besides names of the controls) that were made either in order to accommodate the XAML cross-platform portability or to enhance functionality. This article's goal is to provide short summary of some of the important differences you should know about.


Since both platforms had their own (non-compatible) versions of XamEditors so will be the comparisons separated.

The main reason to still use the WPF specific versions it to be used with as editors in the XamDataGrid (also WPF specific mind you). The XamInputs can be used in a grid – the XamGrid which has been ported from Silverlight and is now also cross-platform. For most other intents and purposes those groups of controls behave in very similar manner – the major properties are available in both:

  • Mask – this is what the control uses to guide end user input.
  • Value - gets or sets the value displayed/edited by the input control.
  • ValueType - specifies the type of values that are displayed/edited by the input.
  • InvalidValueBehavior – defines the action the control will take when incorrect input occurs.
  • And also many familiar properties like ValueConstraint, ValueToTextConverter,, ValueToDisplayTextConverter, FlowDirection, Pad and Prompt chars, Null Text and more.

However, things like Default Editors Repository and Default Masks Repository (mapping of editors and masks to use by default for each known data type) are not available as their goal was to be used by WPF specific controls such as xamDataGrid™ and xamDataPresenter™.

The XamInputs don’t offer the option to stay always in edit mode and related events. On the upside they do give a way to define the way data is stored or displayed (Data and Display Mode properties) which can create the same user experience.


XamInpus don’t rely on the Silverlight data validation you might be used to, but they still provide the ability to set the behaviour of the control on validation error ( keep or discard the wrong data or simply show a message) and an event to use for further customized handling to fit your needs. This leads to the logical absence of ‘VlidationMode’ property and they now use a Boolean ‘AlwaysValidate’ which specifies whether to validate the editor's value even if the user doesn't modify the value. Default value is False where the editor only validates the value if the user modifies it.

Some other properties they share:

  • Masks -  defining the way the control will guide data input is pretty mandatory and therefore always present. The XamInputs also support some new rule-like masks such as “{chars:10:01}” that would accept up to 10 digits of binary code (zeros and ones).
  • The also basic Value and ValueType described above.
  • As well as Pad and Prompt chars, Null Text, Data and Display Mode (also mentioned above).

Localization: Some special characters like a currency symbol or date separator in the XamInputs are not automatically localized (unlike the new {currency} mask for example) as you would be used to with XamEditors – they are localized by escaping the mask with {LOC} character sequence to indicate that symbols in the following table should be mapped to the associated symbols in the underlying culture settings. Thus there is no Culture property for XamInputs.

So lets say you currently use a XamNumericEditor and want to use XamNumericInput instead. First you would know the numeric editor only accepts *one* mask {double:-i.f} while the numeric input masks can include various literals and rules, but it does support the same mask too. Lets see that in code:

  1. <ig:XamNumericEditor ShowButtons="True"
  2.                      Increment="2"
  3.                      Mask="{}{double:-4.6}"
  4.                      DisplayMode="IncludeLiteralsWithPadding"
  5.                      DataMode="IncludeLiteralsWithPadding"/>

The XamNumericEditor will accept a number with a sign, four digits before and 6 after the separator. It will also have a spin button available which would add or subtract 2 from the value. Now the very same thing using the new input:

  1. <ig:XamNumericInput SpinButtonDisplayMode="MouseOver"
  2.                     SpinIncrement="2"
  3.                     Mask="{}{double:-4.6}"
  4.                     DisplayMode="IncludeLiteralsWithPadding"
  5.                     DataMode="IncludeLiteralsWithPadding"/>

As you can tell the properties set correspond to the first line for line. There is however a difference as the spin button option has been enhanced and instead of a simple true/false now also has options to show on mouse over or in edit mode only. And the Increment property is named SpinIncrement for clarity.

What the new controls bring

Considering the example above it’s worth to note the XamNumericInput supports much greater variety of masks and instead of defining two separate properties for min and max values you can set that along with all else in the mask, like so:

  1. Mask="{}{number:0-100} %"

Which would cause the control to only accept values between 0 and 100 and place a ‘%’ literal in the end.

One new brought for both platforms is the ability to control what can be copied from the input – the Clip Mode property lets you control what goes to the clipboard – the raw input or also include padding or include literals or even both. This comes along the mentioned above Data and Display mode and they let you control the way data would be handled in three different levels.

Then there’s the XamDateTimeInput that up to speed with what a user would expect when asked to enter a date – not just the proper mask but a really smart calendar to pick it from.

And last but not least to remind again that anything set in XAML or code behind can be copied over from Silverlight project to WPF and vice versa.