Custom Formatting
- 7 minutes to read
The Custom Formatting feature allows you to:
- format values that are not numeric nor date/time;
- implement complex formatting of numeric or date/time values.
This topic explains how to implement a custom formatter.
Custom Formatting Concepts
Implementing a custom formatter means creating a method that will return formatted strings, taking the original value and the format string as the parameters. Thus, it is up to you to produce the formatting logic, but this does give you unlimited capabilities. To enable custom formatting, set the FormatInfo.FormatType property to FormatType.Custom and the FormatInfo.Format property to your custom formatter object.
To create a custom formatter object, you will need to follow the steps below.
- Create a class implementing the IFormatProvider interface. The interface declares a single GetFormat method that must return a reference to the object implementing the ICustomFormatter interface. Note that it is common practice to provide a single class that implements both the IFormatProvider and ICustomFormatter interfaces. In this case, the GetFormat method must simply return a reference to the current class instance.
- Implement the Format method of the ICustomFormatter interface. This method takes the format string, the value and the format provider as parameters and must return the formatted string. The formatting logic must be implemented in this method.
- Initialize the FormatInfo.Format property with an object that implements the IFormatProvider interface. See the Members that Support the Formatting Mechanism topic for information on how to access this property.
The outline of the code that needs to be written to provide a custom formatter is given below.
// implementing a custom formatter object
class CustomFormatter : IFormatProvider, ICustomFormatter {
// implementing the GetFormat method of the IFormatProvider interface
public object GetFormat(System.Type type) {
return this;
}
// implementing the Format method of the ICustomFormatter interface
public string Format(string format, object arg, IFormatProvider formatProvider) {
// implement formatting logic here - this method must return the formatted string
// format and args parameters specify the format string and the original value respectively
// ...
}
}
// assigning the custom formatter
textEdit1.Properties.DisplayFormat.Format = new CustomFormatter();
textEdit1.Properties.DisplayFormat.FormatType = FormatType.Custom;
The following two sub-sections provide examples on creating custom formatter classes: a simple upper/lower case example followed by decimal numbers displayed in binary.
Note
Only use custom formatters when necessary, as performance is not as good as standard formatting.
Example - Changing the Case of String Values
This sample creates a custom formatter that modifies the case of an editor’s text. The editor’s display text will obey the specified format string (the FormatInfo.FormatString property value). This string is passed to the Format method as the format parameter. If this parameter value is ‘u‘, the display value is converted to upper case, if the format string is ‘l‘, it is converted to lower case.
The following image shows the text editors’ appearance before and after sample code execution.
// A custom formatter object.
class CustomFormatter : IFormatProvider, ICustomFormatter{
// The GetFormat method of the IFormatProvider interface.
// This must return an object that provides formatting services for the specified type.
public object GetFormat(System.Type type){
return this;
}
// The Format method of the ICustomFormatter interface.
// This must format the specified value according to the specified format settings.
public string Format(string format, object arg, IFormatProvider formatProvider){
string formatValue = arg.ToString();
if (format == "u")
return formatValue.ToUpper();
else if (format == "l")
return formatValue.ToLower();
else return formatValue;
}
}
// ...
// Assign the custom formatter to the editors.
textEdit1.Properties.DisplayFormat.FormatType = FormatType.Custom;
textEdit1.Properties.DisplayFormat.FormatString = "u";
textEdit1.Properties.DisplayFormat.Format = new CustomFormatter();
textEdit2.Properties.DisplayFormat.FormatType = FormatType.Custom;
textEdit2.Properties.DisplayFormat.FormatString = "l";
textEdit2.Properties.DisplayFormat.Format = new CustomFormatter();
See also: RepositoryItemTextEdit.CharacterCasing.
Example - Display Decimal Values in Binary
This example demonstrates a way of creating a custom formatter object to display decimal values in binary, but only if the format string is supplied as “B”.
The result is shown in the image below.
// A custom formatter object.
public class BaseFormatter : IFormatProvider, ICustomFormatter {
// The GetFormat method of the IFormatProvider interface.
// This must return an object that provides formatting services for the specified type.
public object GetFormat(Type format) {
if (format == typeof (ICustomFormatter)) return this;
else return null;
}
// The Format method of the ICustomFormatter interface.
// This must format the specified value according to the specified format settings.
public string Format (string format, object arg, IFormatProvider provider) {
if (format == null) {
if (arg is IFormattable)
return ((IFormattable)arg).ToString(format, provider);
else
return arg.ToString();
}
if (format == "B")
return Convert.ToString(Convert.ToInt32(arg), 2);
else
return arg.ToString();
}
}
// ...
// Assign the custom formatter to the editor.
spinEdit1.Properties.DisplayFormat.FormatType = FormatType.Custom;
spinEdit1.Properties.DisplayFormat.FormatString = "B";
spinEdit1.Properties.DisplayFormat.Format = new BaseFormatter();
spinEdit1.Properties.IsFloatValue = false;
spinEdit1.EditValue = 10;