Data Formats

In This Topic

Data Formats Overview

A data format is represented by the NDataFormat class, for which you must only create singleton instances, if you need to define custom data formats. A data format is associated with each type of data that you want to publish or consume via a data object. A data format is a binary contract between the publisher and the consumer, that specifies how a binary data stream is converted into an object instance of some type and vice-versa.

Predefined Data Formats

NOV comes with the following predefined data formats:

NDataFormat.TextFormat - associated with an object of System.String type. This represents a simple Unicode string.
NDataFormat.RasterFormat - associated with an object of Nevron.GraphicsCore.NRaster type. NRaster is the NOV native format for imaging. It represents a two dimensional array of pixel color values, encoded in a specific pixel format. Because a NRaster can be obtained from byte streams in .PNG, .BMP and .JPG image formats and because a NRaster can also be encoded in binary streams in these formats, NRaster successfully integrates with most OS specific data exchange formats related to images.
NDataFormat.RTFFormat - associated with a byte array that contains RTF (Microsoft Rich Text Format) content. Support for RTF and HTML reading and writing to/from a managed objects structure is implemented by the Nevron.TextFormats.XXX.dll that is also used by the NOV Rich Text widget, but because RTF and HTML are "heavy" data formats, they are not part of the Nevron.Presentation.XXX.dll. Since RTF is anyway a binary specification, as data format for data exchange, it is only necessary to transport this binary data and tag it with the native OS format for RTF, if such exists.

Because NOV hosts have knowledge of the predefined data formats, they automatically convert to-from native data exchange formats when such conversions are possible. For Microsoft Windows hosts such conversions are generally possible and this means that you can cut-copy-paste and drag-and-drop images, text and RTF content between NOV and other applications and vice versa (and yes you can cut-copy-paste from/to Microsoft Word).

Custom Data Formats

Besides the predefined data formats, you can also define custom formats, that can possibly exchange information between two different NOV application instances. To do so when declaring a data format you always need to provide a pair of serialize/deserialize delegates that serialize/deserialize your object instance to/from a byte array. The following code example declares a custom data format and implements a simple object, that can cross the application/process boundaries:

Example Title	Copy Code
public class MyFirstDataExchangeObject { // make some sample fields public int IntValue; public float FloatValue; public MyFirstDataExchangeObject() { FloatValue = 0; IntValue = 0; } static MyFirstDataExchangeObject() { // create the Data Format associated with MyFirstDataEchangeObject DataFormat = NDataFormat.Create("MyFirstDataEchangeFormat", new SerializeDataObjectDelegate(SerializeDataObject), new DeserializeDataObjectDelegate(DeserializeDataObject)); } // Serialization function for the data format private static byte[] SerializeDataObject(NDataFormat format, object obj) { MyFirstDataExchangeObject myObject = (MyFirstDataExchangeObject)obj; Nevron.IO.NByteWriter byteWriter = new Nevron.IO.NByteWriter(); byteWriter.WriteInt32LE(myObject.IntValue); byteWriter.WriteSingleLE(myObject.FloatValue); return byteWriter.ToArray(); } // Deserialization function for the custom data format private static object DeserializeDataObject(NDataFormat format, byte[] bytes) { MyFirstDataExchangeObject myObject = new MyFirstDataExchangeObject(); Nevron.IO.NByteReader reader = new Nevron.IO.NByteReader(bytes); myObject.IntValue = reader.ReadInt32LE(); myObject.FloatValue = reader.ReadSingleLE(); return myObject; } // reference to the singleton NDataFormat created by the static constructor of this type public static readonly NDataFormat DataFormat; } ... // publish a custom data exchange object to the clipboard // make a custom data exchange object and assign arbitrary values MyFirstDataExchangeObject obj = new MyFirstDataExchangeObject(); obj.FloatValue = 20.5f; obj.IntValue = 10; // make a data object and store the data exchange object in it NDataObject dataObject = new NDataObject(); dataObject.SetData(MyFirstDataExchangeObject.DataFormat, obj); // place the data object on the clipboard NClipboard.SetDataObject(dataObject); ... // consume the custom data exchange object from the clipboard // get a data object from the clipboard NDataObject dataObject = NClipboard.GetDataObject(); // try get our custom data exchange object from the data object MyFirstDataExchangeObject obj = (MyFirstDataExchangeObject)dataObject.GetData(MyFirstDataExchangeObject.DataFormat); if (obj != null) { // successfully obtained data exchange object from the clipboard } else { // failed to obtained data exchange object from the clipboard }

Example Title

Copy Code

public class MyFirstDataExchangeObject
{
    // make some sample fields
    public int IntValue;
    public float FloatValue;
    public MyFirstDataExchangeObject()
    {
        FloatValue = 0;
        IntValue = 0;
    }
    static MyFirstDataExchangeObject()
    {
        // create the Data Format associated with MyFirstDataEchangeObject
        DataFormat = NDataFormat.Create("MyFirstDataEchangeFormat",
        new SerializeDataObjectDelegate(SerializeDataObject),
        new DeserializeDataObjectDelegate(DeserializeDataObject));
    }
    // Serialization function for the data format
    private static byte[] SerializeDataObject(NDataFormat format, object obj)
    {
        MyFirstDataExchangeObject myObject = (MyFirstDataExchangeObject)obj;
        Nevron.IO.NByteWriter byteWriter = new Nevron.IO.NByteWriter();
        byteWriter.WriteInt32LE(myObject.IntValue);
        byteWriter.WriteSingleLE(myObject.FloatValue);
        return byteWriter.ToArray();
    }
    // Deserialization function for the custom data format
    private static object DeserializeDataObject(NDataFormat format, byte[] bytes)
    {
        MyFirstDataExchangeObject myObject = new MyFirstDataExchangeObject();
        Nevron.IO.NByteReader reader = new Nevron.IO.NByteReader(bytes);
        myObject.IntValue = reader.ReadInt32LE();
        myObject.FloatValue = reader.ReadSingleLE();
        return myObject;
     }
     // reference to the singleton NDataFormat created by the static constructor of this type
    public static readonly NDataFormat DataFormat;
}
...
// publish a custom data exchange object to the clipboard
// make a custom data exchange object and assign arbitrary values
MyFirstDataExchangeObject obj = new MyFirstDataExchangeObject();
obj.FloatValue = 20.5f;
obj.IntValue = 10;
// make a data object and store the data exchange object in it
NDataObject dataObject = new NDataObject();
dataObject.SetData(MyFirstDataExchangeObject.DataFormat, obj);
// place the data object on the clipboard
NClipboard.SetDataObject(dataObject);
...
// consume the custom data exchange object from the clipboard
// get a data object from the clipboard
NDataObject dataObject = NClipboard.GetDataObject();
// try get our custom data exchange object from the data object
MyFirstDataExchangeObject obj = (MyFirstDataExchangeObject)dataObject.GetData(MyFirstDataExchangeObject.DataFormat);
if (obj != null)
{
    // successfully obtained data exchange object from the clipboard
}
else
{
    // failed to obtained data exchange object from the clipboard
}

Are you tempted to use .NET serialization to serialize/deserialize the object? We strongly advise to never use the built-in .NET serialization, because of too many reasons, which are not a subject of this topic. NOV implements its own serialization engine, that you can use to serialize objects - see Serialization Overview for more info.