Data Objects

Overview

The NtTimeChartControl can store huge numbers of data objects depending on the available memory. Any object that you want to store in the NtTimeChartControl has to be of the type NtDataObject or derived type, because the NtTimeChartControl internally maintains various lists of NtDataObjects for high performance access.

The NtDataObject class looks like this:

public class NtDataObject
{
public ulong objId;
public int dataTypeId;
public DateTime dt;
public DateTime dtEnd;
public string text;
}

Field description:

objId: The object ID. This member is a unique identifier for data objects that are stored in the NtTimeChart. No two objects with the same objId are allowed to exist within the NtTimeChart's data storage at the same time. It is up to your application to set the objId properly when creating NtDataObjects. The objId must not be zero.

dataTypeId: The dataTypeId can be any number between 1 and 9999. Most important thing here: All NtDataObjects that represent the same type of data must have the same dataTypeId. This is for two reasons:
1. Based on the dataTypeId the so called 'Perspective' of the NtTimeChart defines which type of data is to be displayed in which row. So in order to group data correctly with the help of the Perspective all data of the same type should share the same dataTypeId, but no others.
2. For every data type you store in your data set (means at least one data object with that dataTypeId) you have to create a NtDisplayDef object with the same dataTypeId to let the NtTimeChart know how to draw your data.

dt: If the data object represents a single event, this is the time stamp when the event takes place (like a customer order e.g.). If the data ojbect represents a time period, this is the start of the period (like a car rental, that starts when the customer takes the car and ends when he returns it).
Important: Internally the NtTimeChart works on Universal Time. Time stamps given in local time can be converted to Universal Time by calling ToUniversalTime().

dtEnd: If the data object represents a time period then this value differs from dt. This can be used for drawing the object in the NtTimeChart, for example. Suppose a certain data type is to be drawn as a horizontal line within the Time Chart starting from the beginning of the event and ending at its end. In this situation the dtEnd information is used.

text: This is the value of the data object. It can be used as textual representation of the data by drawing this string to the Time Chart. Or if the data type is configured to be shown as icon or bitmap this string can be used as a key to obtain the appropriate image. Or in case of courves this string might contain a numeric value that is parsed.
It is quite obvious that this simple string is not suitable to store more complex data. Please see the following sections to read more about how to store complex data within one NtDataObject.

Storing data in the NtTimeChart control

Storing data has nothing to do with displaying data. For example the data item might be simple while displaying it might be complex. Think of a simple string which is the path to a PDF file. Displaying that is a complex process. Vice versa think of a complex data structure like a customer order in an online shop (consisting of customer data, product data, contract info etc.) while your application simply wants to create an overview of orders listing the item names, only.

Storing data in the NtTimeChartControl consists of two steps:

Create one NtDataObject per data object you want to store and show in the NtTimeChartControl. This may result in a huge list of NtDataObjects.
Add these NtDataObjects to the NtTimeChartControl.

This section is just about these two steps of storing data in the NtTimeChart control. How this data is then being displayed is covered by the next chapter.

1. Creating NtDataObjects

Suppose your application's data consists of 'customer orders'. Each order is a fairly complex structure containing the customer, the article, adresses etc. So for each customer order you later want to show in the Time Chart you create one NtDataObject and store the order data in it.

In this situation you can choose among the following three alternatives of storing data in NtDataObjects:

A) Direct use of NtDataObject class

If your data is a simple text, number or key you can store it as a string in the text field of the NtDataObject. In this case you can use the NtDataObject class as it is by filling all its fields.
Drawing your data then is done either by the NtTimeChart's built in drawing mechanism for texts, icons, bitmaps or curves. Or you choose to use the NtTimeChartControl's easy 'Custom Object Drawing' mechanism to implement drawing on your own.

B) Derive from NtDataObject and add fields

If your data is more complicated but not aggregated in a class or struct you can simply enhance the NtDataObject by deriving your own class type from NtDataObject and enrich it with additional fields.
In this case you will have to make use of the NtTimeChartControl's 'Custom Object Drawing' mechanism to draw your data (please see next section).

C) Derive from NtDataObject and add a reference to your own data type

If the data you want to place in the NtTimeChart is already aggregated in a predefined class type you can not create a class that is derived from both NtDataObject and your predefined class. Instead you derive a new class from NtDataObject that has a reference to an instance of your predefined class. Then you still fill all the fields of the NtDataObject base call as described above and additioally set the reference.
In this case you also will have to make use of the NtTimeChartControl's 'Custom Object Drawing' mechanism to draw your data (please see next section).

2. Adding NtDataObjects to the NtTimeChartControl

Assume you created a huge list of NtDataObjects. It will be of the type List<NtDataObject>, even if it contains a rich variaty of NtDataObjects and your custom made derivates of that. In this situation there are two ways of putting that data to the NtTimeChart:

A) Call the NtTimeChart's member SetData() that takes your list of NtDataObjects as an argument. This replaces any data previously stored in the NtTimeChart.
B) Call the NtTimeChart's member InsertDataObjects() that takes your list of NtDataObjects as an argument. This adds new NtDataObjects to the NtTimeChart or updates existing ones.

Note: The List<NtDataObject> must not contain any null references and no two entries with the same objId. Further more no object must have the objId zero.

Please note that the list is being changed by calls to these member fucntions.

The entry process is a little quicker if the list is sorted by objId and it is even quicker if the order of objIds is the same as for dt, meaning that the order of ids is the same as the order of time. This is because several sorting operations take place during data entry to the Time Chart.
On the other hand side it does not make sense to do any additional effort upfront to sort the lists because this is what the NtTimeChart does anyway when calling SetData().

If you want to add only one single NtDataObject you can also call the member function InsertDataObject().

<< Prev.: Ticks and Pixels Next: Data Display >>