Custom Formatting

Oct 29, 2020
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.

C#
VB.NET

csharp

// 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;

' implementing a custom formatter object
Class CustomFormatter : Implements IFormatProvider, ICustomFormatter
    ' implementing the GetFormat method of the IFormatProvider interface
    Public Function GetFormat(ByVal type As Type) As Object Implements IFormatProvider.GetFormat
        Return Me
    End Function
    ' implementing the Format method of the ICustomFormatter interface
    Public Function Format(ByVal formatString As String, ByVal arg As Object, _
      ByVal formatProvider As IFormatProvider) As String Implements ICustomFormatter.Format
        ' implement formatting logic here - this method must return the formatted string
        ' format and args parameters specify the format string and the original value respectively
        ' ...
    End Function
End Class

' 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.

C#
VB.NET

csharp

// 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();

' A custom formatter object.
Class CustomFormatter : Implements IFormatProvider, ICustomFormatter
    ' The GetFormat method of the IFormatProvider interface.
    ' This must return an object that provides formatting services for the specified type.
    Public Function GetFormat(ByVal type As Type) As Object _
    Implements IFormatProvider.GetFormat
        Return Me
    End Function
    ' The Format method of the ICustomFormatter interface.
    ' This must format the specified value according to the specified format settings.
    Public Function Format(ByVal formatString As String, ByVal arg As Object, _
    ByVal formatProvider As IFormatProvider) As String Implements ICustomFormatter.Format
        Dim formatValue As String = arg.ToString()
        If (formatString = "u") Then
            Format = formatValue.ToUpper()
        ElseIf formatString = "l" Then
            Format = formatValue.ToLower()
        Else
            Format = formatValue
        End If
    End Function
End Class
' ...
' 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()

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.

C#
VB.NET

csharp

// 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;

' A custom formatter object.
Public Class BaseFormatter : Implements IFormatProvider, ICustomFormatter
    ' The GetFormat method of the IFormatProvider interface.
    ' This must return an object that provides formatting services for the specified type.
    Public Function GetFormat(ByVal format As Type) As Object _
    Implements IFormatProvider.GetFormat
        If format.ToString() = GetType(ICustomFormatter).ToString() Then
            GetFormat = Me
        Else
            GetFormat = Nothing
        End If
    End Function

    ' The Format method of the ICustomFormatter interface.
    ' This must format the specified value according to the specified format settings.
    Public Function Format(ByVal formatString As String, ByVal arg As Object, _
    ByVal provider As IFormatProvider) As String Implements ICustomFormatter.Format
        If (formatString = Nothing) Then
            If TypeOf arg Is IFormattable Then
                Format = CType(arg, IFormattable).ToString(formatString, provider)
            Else
                Format = arg.ToString()
            End If
            Exit Function
        End If
        If (formatString = "B") Then
            Format = Convert.ToString(Convert.ToInt32(arg), 2)
        Else
            Format = arg.ToString()
        End If
    End Function
End Class

' ...
' 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