NETTutorial19

From Steema Software Reference Wiki
Jump to: navigation, search

Net.png

Contents page
Previous | Next

Tutorial19 - Custom Serialization


Please note.
Custom Serialization is an advanced topic that offers the option to correctly save and recover developer designed custom elements that may be related to but are outside of TeeChart's own functionality set. Steema limits the support that it is able to provide for Custom Serialization to within the scope of the techniques outlined in this tutorial.

Introduction


Automatic Serialization
TeeChart automatically processes all of the necessary Serialization steps to permit save and recall of a TeeChart. That includes all modified elements of a Chart and its Series.

Custom Serialization (serialization of Custom Elements)
You may decide that a TeeChart Series provides most of the functionality you require, but that you would like to modify it to include an additional piece of information of your own for the Series to publish or act upon or to provide reference to other parts of your application when that Series is used. For that purpose you may wish to create your own SeriesType, deriving from a TeeChart Series, adding your own custom elements. TeeChart's Custom Serialization permits the save (serialization) and recovery of those elements.

Please note: Saving of custom elements breaks down into 2 techniques:
- Serialization of known Types (eg. string, int, double)
- Serialization of Custom (unkown) Types

This tutorial explains how that works.


Serializing Custom Series - Serialization of known Types (eg. string, int, double)

Define a Custom Series


Let us assume that you wish to derive a Series from TeeChart's Line Series. The Line Series contains the functionality you require but you wish to add a few elements for tracking purposes or as value-add objects associated with any particular dataset.

The following is an example of how to define a Custom Series derived from Line Series:

public class MyLine : Steema.TeeChart.Styles.Line 
{
public MyLine(Chart c) : base(c)
{
myStrVar = "default";
}

public MyLine() : this((Chart)null) { }

private string myStrVar = "";
private int myIntVar = 0;

public string MyStrProp
{
get { return myStrVar; }
set { myStrVar = value; }
}

public int MyIntProp
{
get { return myIntVar; }
set { myIntVar = value; }
}
}



Save and Import


You can populate your custom variables and save the Chart and they will import when the saved Chart is re-imported. No additional steps are required as long as the variables are of a known System type (eg. String, Integer, Double). TeeChart will handle the serialization and de-serialization.

Eg.
save Chart with modified Series

private void button1_Click(object sender, EventArgs e) 
{
MyLine mLine=new MyLine();

mLine.MyStrProp = "now set";
mLine.MyIntProp = 43;

tChart1.Series.Add(mLine);
mLine.FillSampleValues();

tChart1.Export.Template.Save(@"c:\files\customLine.ten");
}



import Chart with modified Series

private void button2_Click(object sender, EventArgs e) 
{
tChart1.Clear();
tChart1.Import.Template.Load(@"c:\files\customLine.ten");
label1.Text = ((MyLine)(tChart1[0])).MyStrProp;
label2.Text = ((MyLine)(tChart1[0])).MyIntProp.ToString();
}



Label1 and Label2 will show the values set before saving the Chart.


Serialization of Custom (unkown) Types


Define a Custom Series with custom object


The steps to create the Custom Series with elements that use custom objects are similar to those of the the Series with elements of a known type.

The following is an example of a Series derived from Line Series that includes new elements of known and an unknown type (MyObj). As TeeChart does not know how to serialize and deserialize the unknown type we need to provide a mechanism wherein you can write the routine to do so and have it called at serialization/deserialization time. That mechanism is provided by inheriting the class from the Steema.TeeChart.Export.TemplateExport.ICustomSerialization interface. That requires that you add 2 methods to your class:

- public void Serialize(SerializationInfo info)
- public void DeSerialize(SerializationInfo info)


using Steema.TeeChart.Export; 

// Custom Line class
public class MyLine : Steema.TeeChart.Styles.Line, TemplateExport.ICustomSerialization
{
public MyLine(Chart c) : base(c)
{
myStrVar = "default";
}

public MyLine() : this((Chart)null) { }

private string myStrVar = "";
private int myIntVar = 0;
private MyObj myMyObj;

public string MyStrProp
{
get { return myStrVar; }
set { myStrVar = value; }
}

public int MyIntProp
{
get { return myIntVar; }
set { myIntVar = value; }
}

/// <summary>
/// Method to ease population of the myMyObj variable.
/// </summary>
public void setMyObj(int i, string s)
{
myMyObj = new MyObj(i, s);
}

/// <summary>
/// Property of Custom type, MyObj
/// </summary>
public MyObj MyObj
{
get { return myMyObj; }
set { myMyObj = value; }
}

/// <summary>
/// Obligatory method (TemplateExport.ICustomSerialization interface)
/// </summary>
public void Serialize(SerializationInfo info)
{
//save custom elements
info.AddValue("myObjStr", myMyObj.MyString, myMyObj.MyString.GetType());
info.AddValue("myObjInt", myMyObj.MyInt);
}

/// <summary>
/// Obligatory method (TemplateExport.ICustomSerialization interface)
/// </summary>
public void DeSerialize(SerializationInfo info)
{
//recover custom elements into the myMyObj variable
myMyObj = new MyObj(info.GetInt32("myObjInt"), info.GetString("myObjStr"));
}
}

//custom object
public class MyObj
{
private string myString;
private int myInt;

public MyObj(int i, string s)
{
myString = s;
myInt = i;
}

public int MyInt
{
get { return myInt; }
set { myInt = value; }
}

public string MyString
{
get { return myString; }
set { myString = value; }
}
}



Note that serialization uses 'info.AddValue' to save the value of your custom element. Deserialization uses 'info.Getxxxx' according to the type of the variable you are saving.

Save and Import


Once you have populated the routines inside your custom class to serialize and de-serialize your custom elements, Chart save and load may be called in the same way as for an unmodified Chart as shown before.

Eg.
save Chart with modified Series

private void button1_Click(object sender, EventArgs e) 
{
MyLine mLine=new MyLine();

mLine.MyStrProp = "now set";
mLine.MyIntProp = 43;
mLine.setMyObj(43, "set val 43");

tChart1.Series.Add(mLine);
mLine.FillSampleValues();

tChart1.Export.Template.Save(@"c:\files\customLine.ten");
}



import Chart with modified Series

private void button2_Click(object sender, EventArgs e) 
{
tChart1.Clear();
tChart1.Import.Template.Load(@"c:\files\customLine.ten");
label1.Text = ((MyLine)(tChart1[0])).MyStrProp;
label2.Text = ((MyLine)(tChart1[0])).MyIntProp.ToString();
label3.Text = ((MyLine)(tChart1[0])).MyObj.MyInt.ToString();
label4.Text = ((MyLine)(tChart1[0])).MyObj.MyString;
}



Label1, Label2, Label3 and Label4 will show the values set before saving the Chart.


Serializing a Custom Chart


Steps necessary to serialise a Custom Chart vary slightly from those applied to a Custom Series.

Derive your Custom Chart from Steema.TeeChart.Chart. Mark it as Serializable and set it as an ICustomSerialization class (see example below). Known types will serialise without any required steps from you as in the Series example above. For an example of an unknown type we'll use the same object as in the Series example, MyObj.

E.g. Example Chart with Custom variables of known and unknown type

[System.Serializable()] 
public class MyChart : Steema.TeeChart.Chart, TemplateExport.ICustomSerialization
{
private MyObj myMyObj;

public MyChart() : base() { }

//required constructor
protected MyChart(SerializationInfo info, StreamingContext context) : base(info, context) { }

private string myStrVar = "";
private int myIntVar = 0;

public string MyStrProp
{
get { return myStrVar; }
set { myStrVar = value; }
}

public int MyIntProp
{
get { return myIntVar; }
set { myIntVar = value; }
}

public void setMyObj(int i, string s)
{
myMyObj = new MyObj(i, s);
}

public MyObj MyObj
{
get { return myMyObj; }
set { myMyObj = value; }
}

//required method
public void Serialize(SerializationInfo info)
{
object o = myMyObj.MyString;
info.AddValue("myObjStr", o, o.GetType());
info.AddValue("myObjInt", myMyObj.MyInt);
}

//required method
public void DeSerialize(SerializationInfo info)
{
myMyObj = new MyObj(info.GetInt32("myObjInt"), info.GetString("myObjStr"));
}
}



Serialisation is handled automatically when you save the Chart.

Eg. Serialise
private void button1_Click(object sender, EventArgs e)

{ 
MyChart myChart = new MyChart();
myChart.Series.Add(new Steema.TeeChart.Styles.Bar());
myChart[0].FillSampleValues();
myChart.setMyObj(22, "set 22");
myChart.MyStrProp = "set String Prop";
myChart.Export.Template.IncludeData = true;
myChart.Export.Template.Save(@"c:\files\customChart.ten");
}



Deserialisation requires an additional step, telling TeeChart's deserialiser to bind the MyChart type to the serialised Chart, not Chart as would be the default type.

Note the line that sets the binder:

myChart.Import.Template.CustomType = myChart.ToString();



Eg. DeSerialise
private void button2_Click(object sender, EventArgs e)

{ 
MyChart myChart = new MyChart();
myChart.Import.Template.CustomType = myChart.ToString();
myChart = (MyChart)(myChart.Import.Template.Load(@"c:\files\customChart.ten"));
myChart.Header.Text = myChart.MyObj.MyString;
myChart.Footer.Text = myChart.MyStrProp;
myChart.Footer.Visible = true;
myChart.Export.Template.Save(@"c:\files\testCustomChartmodded.ten");
myChart.Export.Image.PNG.Save(@"c:\files\testCustomChart.png");
}

PREVIOUS

NEXT


© 1998-2019 Steema Software SL. All rights reserved.