API Documentation -> NtDisplayDef

# NtDisplayDef

The NtDisplayDef defines how a certain type of data is to be displayed. This includes the backgraound color of the Header Control, the background color and foreground color ad font of the data object themself as well as the type of drawing like curves, images, icons, text or custom drawn.
The screenshot below shows a NtTimeChartControl that currently shows five different rows: One of type 'curve with cross marks', one 'text', one 'icons', one 'images', and finally another one 'text':

As you can see on Row Headers there are different color schemes for the different types of data. And most important: All data objects of the same type share the same row. For example all data objects of the type 'Oxygen saturation' have the same dataTypeId (for example 100) and thereby are all gruped in one row. And all data objects of type 'Temperature' have another dataTypeId (for example 65) and therefor are all grouped in another row. Which the exact row is for the various data types is determined by the NtPerspective.
To summarize:
1. The NtDisplayDef for one data type defines what the data looks like within its row.
2. The NtPerspective defines which data type is shown in which row and what height (in pixels) the rows have.
About colors and brushes:
When setting up your NtDisplayDefs for your different data types, you will probably read the appropriate info from a settings data base or configuration file. And there you will rather store colors than brushes. Anyway to draw objects, the NtTimeChartControl uses brushes. This does not only support plain areas but also patterns (although patterns are hardly used in real applications).
Anyway there are three different brushes and one pen used to define the appearance of data in the NtTimeChartControl:

- bkBrush defines the background of the object. Interestingly objects should always be drawn without background. Instead the background brush is only defined for the application to know which brush is recommended by this object in order to fill the Row Headers or (if used) the background of the Time Chart.
- textBrush is used to draw texts.
- foregroundBrush is used to paint filled areas of the object. For example if an object is represented by a filled circle, this brush is best to use.
- foregroundPen is used for all drawing operations of data objects that need a pen (like lines).

The built in display types (text, curves, images and icons) can be served by these brushes and the pen. But what if you implement custom drawing to draw the objects of a certain data type by yourself and you need more than one pen? The answer is easy: The NtDisplayDef objects are created by you on startup and then stored into the NtTimeChartControl. At that point you can always create your own subclass of NtDisplayDef that has an additional pen and initialize this pen. Store it along with the other NtDisplayDefs and when your code is called to draw the objects of that respective type, your derived NtDisplayDef will be handed over to your painting routine. Please see the tutorial Custom Object Drawing to see how to derive from NtDisplayDef.

Example:
Looking at the image on the top of this page you will see the line 'Temperature' for example. Please note that in this row the data objects consist of blue rectangles decorated with white text. The textBrush is created with the color white. The foregroundBrush is made of blue. The bkBrush is mid grey, but you can not see it on the object directly (as backgrounds of objects should never been drawn) but it is used to draw the Row Header to the left, making up the legend of this row.

For details on setting up all the members of NtDisplayDef please refer to the tutorial Data Display.

Class Hierarchy:

System.Object

NtDisplayDef

Constructors:

Modifier | Name and Parameters | Description
--- | --- | ---
public | NtDisplayDef ( ) | The default constructor.
public | NtDisplayDef ( int dataTypeId, int preferredRowHeight, string rowHeaderStr ) | This constructor is the minimal initialization. Still more members should be set manually during initialization phase. The dataTypeId is an essential information for the NtDisplayDef because it has to be clear for which data type it is usable. dataTypeIds have to be greater than zero and less than 10000.

Members:

Type | Name | Description
--- | --- | ---
public int | dataTypeId | One NtDisplayDef is responsible for one type of data, only. The dataTypeId must be greater than zero and less than 10000.
public int | displayMethod | The method how data is being drawn. There are four display types predefined: 0: None (object not displayed at all), 1: text, 2: curve with markers, 3: bitmap, 4: icon. But creating your own display types is easy: Simply set displayMethod to anything greater than 4 and override the NtTimeChartControl's NtCustomObjectPaint interface to perform the drawing of the object within the rectangle you receive.
public int | preferredRowHeight | In one and the same row of the NtTimeChartControl there can be more than one data type. For example you want to have a row in your application that shows previews of PDF documents by bitmaps and indicators for customer orders by icons. So there are two data types (PDF documents and customer orders) that have different sizes, as the icons are typically smaller. So the two different NtDisplayDefs have different preferred rowHeights (200 and 30 e.g.). It is your application's task to finally define the row height to set into the NtPerspective. In most cases you will choose the biggest of the preferred heights.
public Brush | bkBrush | The background brush for this data type. It is common technique to use this brush in order to initialize the NtRowHeader's bkBrush member. In most cases the NtRowHeader is the only one to make use of the bkBrush, as typically the background of the Time Chart itself is painted evenly over the full sheet (please see NtTimeChartControl.FillBackground).
public Brush | foregroundBrush | Whenever drawing an object means that areas (like rectangles) have to be filled, this is the appropriate brush to use.
public Pen | foregroundPen | Whenever drawing an object means that lines have to be drawn, this is the appropriate pen to use.
public Brush | textBrush | This brush is used to draw a data object's text.
public Font | font | The Font used to draw the text of objects that are to show text. Can be null.
public StringFormat | stringFormat | The StringFormat used to draw the text of objects that are to show text. This supports the setting of tab stops. Can be null. Whenever this member is not null it will be used to draw texts.
public int | maxStringWidth | Maximum width of a drawn string in pixels. If a text is longer, it will be wrapped into a new line.
public string | rowHeaderStr | The title for naming the data type in the Row Header (which thereby makes up the legend for your data).
public int | iconWidth | The width of the icons (if this data type is being displayed by icons).
public long | lineMaxSeconds | Data plots may consist of data points (data objects) that are linked by lines to form a curve. Linking two points by a line makes sense only if they are not too distant. This member defines the maximum distance in seconds that can be covered by a line.
public int | lineType | By default there are three options on how curves are being drawn within the NtTimeChartControl defined by lineType: 0: Only the objects are drawn, no line inbetween. 1: direct, possibly slope line inbetween objects. 2: objects connected by two segments: horizontal and vertical.
public int | hotspotX | The 'hot spot' of a visual representation of a data object like an icon is normally its top left edge. This means, that the visual representation (e.g. the icons) are aligned with their top edge to a certain Y-Coordinate (typically 2 pixels from top of the row) and with their left edge to the time stamp of the data object. Changing hotspotX moves the hot spot within the object to the right, which results in shifting the object's representation (e.g. icon) to the left. For icons that look like a crossmark e.g. it might be reasonable to move the hot spot to the middle.
public int | hotspotY | The 'hot spot' of a visual representation of a data object like an icon is normally its top left edge. This means, that the visual representation (e.g. the icons) are aligned with their top edge to a certain Y-Coordinate (typically 2 pixels from top of the row) and with their left edge to the time stamp of the data object. Changing hotspotY moves the hot spot within the object downwards, which results in shifting the object's representation (e.g. icon) upwards. For icons that look like a crossmark e.g. it might be reasonable to move the hot spot to the middle.
public int | imageHeightLimit | When drawing data items using bitmaps, this is the maximum height of the images. Images with bigger height are reduced (with the same factor in height and width) to fit this limit. This limitation makes sense if you want to ensure that images always fit into the row. So a recommended value is preferredRowHeight-8 (see preferredRowHeight). Set this parameter to -1 to disable height limitation. This also is the default value.
public int | imageWidthLimit | When drawing data items using bitmaps, this is the maximum width of the images. Images with bigger width are reduced (with the same factor in height and width) to fit this limit. This limit is needed for internal calculations. You should make it as small as possible for performance reasons but still big enough to display all images uncompressed that you want to be shown uncompressed.
public int | tooltipType | The tooltip type. Possible values are 0: no tooltip, 1: simple tooltip (plain text with no formatting except new lines), 2: HTML based tooltip.
public double | scaleMin | Curves are based on numeric data. To scale the data within the height of the row you can define scaleMin and scaleMax. A value that is equal to scaleMin will then be placed exactly on the bottom of the row while one that is equal to scaleMax will be placed on the top. Values exeeding these limits are no problem but of course the display will be clipped.
public double | scaleMax | Curves are based on numeric data. To scale the data within the height of the row you can define scaleMin and scaleMax. A value that is equal to scaleMin will then be placed exactly on the bottom of the row while one that is equal to scaleMax will be placed on the top. Values exeeding these limits are no problem but of course the display will be clipped.

See also:

NtRowPerspective

Top API Documentation -> NtDisplayDef © 2016 Bassaly