WinForms - Upcoming v20.1 API Changes

This blog post contains breaking change information that may impact those using two undocumented methods in our WinForms Data Editors namespace. We apologize in advance for this change.

With our v20.1 release, DoFormatEditValue and DoParseEditValue (in the XtraEditors namespace) will no longer be virtual and can no longer be overridden. Both methods were undocumented and never intended for direct use. Unfortunately, we did demonstrate use of these virtual methods in our own code examples (E1491 and E2482) – and suspect that some of our users may have relied upon this incorrect technical guidance.

We have updated both technical examples. If you’re using this API in your app, we ask that you make equivalent changes in your code should you decide to upgrade to v20.1.

Previous implementation

protected override ConvertEditValueEventArgs DoFormatEditValue(object val)
protected override ConvertEditValueEventArgs DoParseEditValue(object val)

Current implementation

protected override object DoFormatEditValue(object val, out bool handled)
protected override object DoParseEditValue(object val, out bool handled)

Note that we do not recommend that you override these new methods. Please use RaiseFormatEditValue and RaiseParseEditValue instead. These methods raise corresponding editor events and are unlikely to be changed again.

//version 19.2 and older
protected override ConvertEditValueEventArgs DoFormatEditValue(object val) {
    ConvertEditValueEventArgs result = base.DoFormatEditValue(val);
    result.Value = MyFormatEditValue(result.Value);
    result.Handled = true;
    return result;
}
 
protected override ConvertEditValueEventArgs DoParseEditValue(object val) {
    ConvertEditValueEventArgs result = base.DoParseEditValue(val);
    result.Value = MyParseEditValue(result.Value);
    result.Handled = true;
    return result;
}

//version 20.1 and newer
protected override void RaiseFormatEditValue(ConvertEditValueEventArgs e) {
    base.RaiseFormatEditValue(e);D
    e.Value = MyFormatEditValue(e.Value);
    e.Handled = true;
}
 
protected override void RaiseParseEditValue(ConvertEditValueEventArgs e) {
    base.RaiseParseEditValue(e);
    e.Value = MyParseEditValue(e.Value);
    e.Handled = true;
}

//Version 19.2 and older
protected override ConvertEditValueEventArgs DoFormatEditValue(object val) {
    if(val is int) {
        switch((int)val) {
            case 0: return new ConvertEditValueEventArgs("zero");
            case 1: return new ConvertEditValueEventArgs("one");
            case 2: return new ConvertEditValueEventArgs("two");
            case 3: return new ConvertEditValueEventArgs("three");
        }    
    }
    return base.DoFormatEditValue(val);
}
protected override ConvertEditValueEventArgs DoParseEditValue(object val) {
    if(val is string) {
        switch((string)val) {
            case "zero": return new ConvertEditValueEventArgs(0);
            case "one": return new ConvertEditValueEventArgs(1);
            case "two": return new ConvertEditValueEventArgs(2);
            case "three": return new ConvertEditValueEventArgs(3);
        }
    }
    return base.DoParseEditValue(val);
}

//Version 20.1 and newer
protected override void RaiseFormatEditValue(ConvertEditValueEventArgs e) {
    base.RaiseFormatEditValue(e);
    if(e.Value is int) {
        e.Handled = true;
        switch((int)e.Value) {
            case 0: e.Value = "zero"; break;
            case 1: e.Value = "one"; break;
            case 2: e.Value = "two"; break;
            case 3: e.Value = "three"; break;                            
        }
    }            
}

protected override void RaiseParseEditValue(ConvertEditValueEventArgs e) {
    base.RaiseParseEditValue(e);
    if(e.Value is string) {
        e.Handled = true;
        switch((string)e.Value) {
            case "zero": e.Value = 0; break;
            case "one": e.Value = 1; break;
            case "two": e.Value = 2; break;
            case "three": e.Value = 3; break;
        }
    }
}

And since we’re discussing a breaking change, I'd be remiss if I did not mention two more things you should considering as you begin use of v20.1. As you may know, we’ve made our DevExpress.Data assembly platform-independent in this release cycle. This generated two changes that were announced in the following BCs:

• Methods of the IKeyboardHandlerService and IMouseHandlerService interfaces have changed their parameter types
• API changes in WinForms components resulting from support for .NET Standard by DevExpress.Data library

For custom implementations of the IRangeControlClient, , you will need to manually replace System.Windows.Forms.Orientation type with DevExpress.XtraEditors.RangeControlClientOrientation.

For the Scheduler Control, replace all occurrences of System.Windows.Forms.KeyEventArgs and System.Windows.Forms.MouseEventArgs types with their appropriate counterparts: DevExpress.Portable.Input.PortableKeyEventArgs and DevExpress.Portable.Input.PortableMouseEventArgs.

// Version 19.2 and earlier
public class MyKeyboardHandlerService : KeyboardHandlerServiceWrapper {
    public override void OnKeyDown(KeyEventArgs e) {
        ...
    }
}
 
public class MyMouseHandlerService : MouseHandlerServiceWrapper {
    public override void OnMouseWheel(MouseEventArgs e) {
        ...
    }
}
 
// Version 20.1 and newer
 
public class MyKeyboardHandlerService : KeyboardHandlerServiceWrapper {    
    public override void OnKeyDown(PortableKeyEventArgs e) {
        ...
    }        
}

public class MyMouseHandlerService : MouseHandlerServiceWrapper {
    public override void OnMouseWheel(PortableMouseEventArgs e) {
        ...
    }
}

Should you have any questions about this post, please submit a support ticket via the DevExpress Support Center.