CriteriaOperator.UserValueToString Event
Occurs when serializing a criteria operator that references a user object.
Namespace: DevExpress.Data.Filtering
Assembly: DevExpress.Data.v24.1.dll
NuGet Package: DevExpress.Data
Declaration
Event Data
The UserValueToString event's data class is UserValueProcessingEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| Handled | Gets or sets a value that indicates whether the event handler has completely handled the event or whether the system should continue its own processing. Inherited from HandledEventArgs. |
Remarks
The CriteriaOperator.UserValueParse and CriteriaOperator.UserValueToString events provide the capability to serialize and deserialize criteria containing arbitrary user objects via the CriteriaOperator.ToString and CriteriaOperator.Parse methods.
When the ToString method is called to serialize a criteria operator referencing an object, the UserValueToString event is raised. When the resulting string representation needs to be parsed, the UserValueParse event is raised. Both the events use the same event arguments class exposing three fields. When handing the UserValueToString event, the object Value field holds an object reference to serialize. After converting the reference to a string presentation, assign it to the string Data field and specify an appropriate tag by specifying the string Tag field. The tag should be unique for each particular object kind. When handing the UserValueParse, the Data and Tag field contain previously specified values. Parse them and provide a corresponding object reference by setting the Value field. Since the event arguments class is derived from HandledEventArgs, set the Handled argument to true after handling the UserValueToString and UserValueParse events and specifying other arguments.
The eXpress Persistent Objects (XPO) utilize this functionality to serialize persistent objects to strings. When handling the UserValueParse event, XPO assignes the fully qualified type of a persistent object along with its identifier to the Data field. “XpoObject” is assigned to the Tag field. So, a sample serialized criteria containing a persistent object reference can look like this.
[Owner] = ##XpoObject#FeatureCenter.Module.PropertyEditors.CriteriaReferencedObject(54)#
To enable this functionality in your XPO application, use the Session.ParseCriteria method instead of CriteriaOperator.Parse to restore persistent objects serialized into a string. If you already have code that uses the regular CriteriaOperator.Parse method, you can wrap the method call with Session.CreateParseCriteriaSessionScope.
using(mySession.CreateParseCriteriaSessionScope()) {
//...
CriteriaOperator.Parse("...");
//...
}
In this instance, the existing CriteriaOperator.Parse method will correctly restore persistent objects in the “mySession” session.
The cross-platform data library provides similar functionality for serialization of enumeration types without handling the UserValueParse/UserValueToString events. For enumerations registered via the static EnumProcessingHelper.RegisterEnum or EnumProcessingHelper.RegisterEnums method, corresponding criteria values will be serialized in the following way.
[EnumProperty] = ##Enum#FeatureCenter.Module.PropertyEditors.TextAndImageEnum,Normal#
To enable this functionality in your application, you can register all the application enumerations types in the following way.
using DevExpress.Data.Filtering;
//...
EnumProcessingHelper.RegisterEnums(AppDomain.CurrentDomain.GetAssemblies());