Nateo Home
  
Concepts
  
Tutorials
  
API Docs

API Documentation -> NtTimeChartControl

NtTimeChartControl

NtTimeChartControl is one of the core classes of the Nateo namespace. It is the central control component that displays your data elements in an almost endless scrollable time range. It handles inserting, deleting and dragging of data elements, allows to change views, and fires several events in context of user interaction.
In general you use the Form designer of your IDE to place this control within your Form, along with other controls like one NtHeaderControl, one or more NtFlankControls, and scroll bars (NtHScrollBar and NtVScrollBar).

While initializing your Form, you will adjust the settings of this control:

Although the activities are quite simple, it makes sense to go through a few tutorials in order to find out about the right order and way of doing it.

Class Hierarchy:

System.Windows.Forms.Panel

NtTimeChartControl

Constructors:

Modifier Name and Parameters Description

public

NtTimeChartControl ( )

 The only constructor. It initializes certain members.

Methods and Properties:

Modifier / Return Value Name and Parameters Description
public void ActivateCondensedView ( bool activate ) Call this method with activate set to true or false to activate or deactivate the condensed view. If the condensed view is currently acitve due to a huge amount of visible objects (more than 100000) the condensed view will stay active.
static public DateTime CalculateSheetRightDt ( DateTime sheetLeftDt, TimeDisplayMode timeDisplayMode, int cols ) Given the left edge of the scrollable area, the desired column definition (that is the time display mode: months, days, hours etc.), this method calculates the DateTime of the right edge. It is static as this is a simple mathematical calculation.
public bool ClearData ( ) Remove all data objects from the Time Chart
public int Cols Read only property. The number of columns in this control. In case of an NtTimeChartControl a column might be an 15min interval or a day etc. depending on the time scale you set. Typically this value is constant throughout the use of the control, once you initialized it.
public bool CondensedViewEnforced This read only property tells if the so called 'condensed view' is currently enforced due to an extremely high amount of data objects visible at the same time.
public CultureInfo CultureInfo Gets or sets the CultureInfo that is being used (mostly by the NtRowHeaderControl assigned to this NtTimeChartContro) to draw dates and texts (like week day names or months) in the appropriate format and language.
public void DeleteDataObject ( ulong objId ) Delete the data object with the specified id from the Time Chart. Note: If you want to delete more than one object, better call DeleteDataObjects() instead of calling this method repetitively.
public void DeleteDataObjects ( List<ulong> objIdList ) Delete a set of data objects from the Time Chart by providing a list of ids. This might change the list. If you need it to remain unchanged, provide a copy of that list.
public void DeleteDisplayDef ( int dataTypeId ) Delete the NtDisplayDef for the specified data type from the Time Chart.
protected virtual void DrawLines ( Graphics, Rectangle, Point ) The cells of the chart control are separated by thin lines drawn by this method. Override it to create your own way of drawing the lines.
public void DoCategoryOpenCloseAnimation ( int row ) Opening and closing of categories is done by an animation initiated by double clicking on category rows. But you can also initiate this animation programatically by calling this method.
public bool FillBackground
 
 There are two ways to draw the Time Chart: Either the background is all the same color for all rows or each row inherits the color of the row header. To fill the background with the color determined by the row header, set this property to true. Default ist false.
public virtual String GetColHeaderStr ( int ) Gets the string for the specified column header. This method is used by a header control like NtHeaderControl in oder to create column header texts.
public virtual double GetColWidth ( int ) While a row's height is measured in full pixels and thereby is an int, the column widths are double values. The reason is that the columns represent time areas like hours, days or others. And as internally the time is handled by the DateTime object, which resolves time into ticks of 100 Nanoseconds each, a certain time frame like a day may not fit into a specific integer value of pixels. For one column this is rounded to draw the vertical separator lines on whole pixels. But when summing up hours into days or days into months, double values are the better choice to be precise.
public virtual int GetColX ( int ) Returns the abscisse (X-coordinate) of a column's left edge.
public NtDisplayDef GetDisplayDefByDataTypeId ( int dataTypeId ) Returns the NtDisplayDef for a certain data type. Every data object in the Time Chart contains a data type id, that determines the type of this object. Different data types are being displayed in different ways: As curves, images, texts, different colors etc. This is defined by the NtDisplayDef for each of the types. When initializing the Time Chart, you provide all the NtDisplayDefs for all data types that can be found in your data set, so the control knows how to show your data.
public NtDisplayObject GetDisplayObjectByXY ( int x,
int y, int inflate ) 		Returns the NtDisplayObject at a certain location of the sheet. x and y are measured in sheet coordinates. inflate enlarges this point. So even if the coordinates miss a certain object by the given amout of pixels it is still counted a hit. This makes sense, if you create display objects, that are very small and thereby for example hard to hit with the mouse.
public virtual NtPerspective GetNtPerspective ( ) Returns a clone of the NtPerspective currently in use.
public virtual int GetRowHeight ( int ) Data is being shown in rows. Different rows have their special row height each. This can be retrieved by this method.
public virtual int GetRowY ( int ) Returns the ordinate (Y-coordinate) of the top edge of a row.
public List<NtDataObject> GetSelectedDataObjects ( ) Returns a list with the currently selected data objects. If not object is selected an empty list will be returned.
public TimeDisplayMode GetTimeDisplayMode ( ) Returns the currently used TimeDisplayMode, which is the meaning of a column in the Time Chart.
public void Init ( int colCount, int colWidth,
TimeDisplayMode timeDisplayMode ) 		Initializes the control. You typically call this in the Load method of your Form. You can call this method later again, whenever you want to change the settings and thereby reinitialize the control at any time.
public void InsertDataObject ( NtDataObject dataObject ) Insert a data object into the Time Chart. Note: If you want to insert more than one object, better call InsertDataObjects() instead of calling this method repetitively.
public void InsertDataObjects ( List<NtDataObject> insertList ) Insert data objects to the Time Chart.
public void InvalidateDisplayObject ( NtDisplayObject ntdo ) A NtDisplayObject is the graphical representation of one data object within the Time Chart. Call this member whenever you want to initiate the redraw of one of those.
public void InvalidateRow ( int row ) Invalidates a row.
protected override void OnPaint ( PaintEventArgs pe ) Inherited from System.Windows.Forms.Control.
protected override void OnPaintBackground ( PaintEventArgs pe ) Inherited from System.Windows.Forms.Control.
public int Rows Read only property. The number of rows in this control.
public void ScrollToPos ( int, int ) Scroll to a certain location given by two values in sheet coordinates.
public void ScrollToDt ( DateTime dt, int fixX )
 
ScrollToDt ( DateTime dt, int fixX, int y ) 		Call this member to move a certain point in time into the visible area. fixX defines where (in client coordinates) the time point will be placed: Provide 0 to let dt be the left edge of the visible area or ClientRect.Width / 2 to let it be in the middle of the visible area.
It is also possible to also provide a vertical scroll value (y).
public void SelectDataObject ( ulong objId ) Select an object that is identified by objId.
public void SelectDataObjects ( List<ulong> objIdList ) Select multiple data objects that are identified by their object ids stored in List<ulong> objIdList.
public void SetData ( List<NtDataObject> dataObjects ) This method is used to load the data set into the NtTimeChartControl. Any existing data will be replaced. The control will create its own list using the data objects contained in the List<NtDataObject>. For this reason you can change this list afterwards without affecting the contents of the control. But keep in mind: Changing the data items (that are in the list) themselves will change the data contents of your Time Chart.
public void SetDisplayDef ( NtDisplayDef displayDef ) Set a NtDisplayDef to be used by the Time Chart.
public void SetNtApplication ( NtApplication ntApplication ) Sets your implementatio of the NtApplication Interface. The NtTimeChartControl will call the various member functions of this interface in order to retreive certain information from your program code: Tooltip texts, or if a certain date is a holiday or weekend. You do not need to implement this but it is recommended to do so.
public void SetNtPerspective ( NtPerspective ntPerspective ) The NtPerspective used in the NtTimeChartControl defines the row order, categories, and row heights. It also defines the assignment of row headers to the flank controls. You can change the current NtPerspective at any time by setting another one by calling this method.
public void SetRowHeader (int dataTypeId, NtRowHeader rh ) A NtRowHeader object defines how a row header for a certain row looks like. It either defines a text, color etc. or a bitmap for a certain row header.
public void SetScrollBars (NtHScrollBar hScrollbar, NtVScrollBar vScrollbar) Typically in your Form's Load method you assign a horizontal and a vertical scroll bar to your chart control by calling this method.
public void SetTimeDisplayMode ( TimeDisplayMode timeDisplayMode )
 
SetTimeDisplayMode ( TimeDisplayMode timeDisplayMode, long fixpointX )
 
SetTimeDisplayMode ( TimeDisplayMode timeDisplayMode, int colWidth, long fixpointX ) 		The time display mode defines what a column is: A column can be a month, a day, six hours, one hour, fifteen minutes or five minutes (see enum TimeDisplayMode). In addition you can specify the column width in the range from 30 to 450 pixels. The fixpointX defines which point on the time axis remains steady while changing the mode. This is because the scale of the time axis changes. So you might want to define, if you want the left edge of the visible area to remain fixed (fixpointX = 0) or the center (fixpointX = ClientRect.Width / 2).
public int SheetHeight Read only. Returns the vertical extension of the scrollable area of the control.
public DateTime SheetLeftDt The left end of the currently active sheet (as a date). The sheet is the virtual surface which holds the grid and the currently visible data elements. It can be moved around by scrolling horizontally and vertically.
After scrolling horizontally, the sheet will automatically be adjusted according to the new position.
public DateTime SheetRightDt The right end of the currently active sheet (as a date). The sheet is the virtual surface which holds the grid and the currently visible data elements. It can be moved around by scrolling horizontally and vertically.
After scrolling horizontally, the sheet will automatically be adjusted according to the new position.
public int SheetWidth Read only. Returns the horizontal extension of the scrollable area of the control.
public bool ShowLinesOnCategoryRows Determine if line marks of data objects are shown on closed categories.
public void UnselectAll ( ) Unselects all selected data objects.

Members:

Type Name Description
public bool allowMultiSelect Users can hold the Ctrl-Key and click on Data items to select them. When allowMultiSelect is set to true (which is the default), more than one item can be selected at a time.
public Brush[] categoryTextBrushes An array of brushes. The category organization of the Time Chart can be seen as a tree. This tree can have different levels. With this array you might provide a brush for each category level to draw the category title text.
public Font[] categoryFonts An array of fonts. The category organization of the Time Chart can be seen as a tree. This tree can have different levels. With this array you might provide a font for each category level to draw the category title text.
public Brush columnBrushDefault The background brush for regular columns in all time display modes. This is used by the NtHeaderControl to draw its columns' backgrounds. Important: When changing this member later than initialization phase, then call SetTimeDisplayMode() to refresh on the changes.
public Brush columnBrushHoliday The background brush for columns in time display mode 'Days', if the column represents a holiday. This is used by the NtHeaderControl to draw its columns' backgrounds. Holidays are defined by the interface NtApplication. Important: When changing this member later than initialization phase, call SetTimeDisplayMode() to refrehs on the changes.
public Brush columnBrushWeekend The background brush for columns in time display mode 'Days', if the column represents a week end day. This is used by the NtHeaderControl to draw its columns' backgrounds. Weekend days are defined by the interface NtApplication. Important: When changing this member later than initialization phase, call SetTimeDisplayMode() to refresh on the changes.
public bool highQuality Determines how lines and fonts are being rendered. Default value is false; Whenever changing after initialization, please call Invalidate() in order to update the entire client area in order to let this property take effect for the whole control.
public int mouseWheelStep The vertical scroll step per mouse wheel event.
public bool noHScrollShifting When scrolling horizontally to the end of the scroll range, the control rearranges the scroll range in a way that the current position in time is kept but the scrollbar flips back to the center of the scroll bar. This way, the user can repetitevly scroll to the left for exampe, while the scroll bar keeps jumping back to the center. Thereby the user can walk seamlessly through the almost endless area of time without stopping to scroll. You can prohibit this behaviour by setting this member to true. In this case, the user can sroll to the right or left but then reaches the end and can not go further. By this means you can limit the time range the user can view. This makes sense if your data is centered around a certain point of time and endless scrolling is not wanted.
public bool solidDragRows When dragging rows or categories vertically, the dragged rows overlay other rows. Setting this member to false will avoid drawing the background of the dragged rows, so that the rows and data beneath can be seen through. This might be convenient, if you want users to better see what is behind. Generally this behaviour is poor usability due to a confused display, so the default value is true.
public bool useOptimizedUpdateRegion In case of complex update regions (due to several windows overlapping each others) rendering is optimized to improve display performance. In rare cases this might lead to areas staying black for a short while like a second. If this happens try setting this value to false. Default is true.

Events:

Event Name Event Arguments Description
beginObjectDragging NtObjectDraggingEventArgs This Event is fired when horizontal dragging of data objects is about to occur. You can catch and cancel this event to prevent the dragging. This is useful if you want to allow dragging for certain objects, only: The NtObjectDraggingEventArgs argument you receive, contains a list with all data objects participating the dragging operation. This allows you to decide if the drag operation is to be permittet or not.
beginTimeZooming NtTimeZoomEventArgs The horizontal zoom factor (time scale) of the NtTimeChartControl can be adjusted by holding the Ctrl-Key and then using the mouse wheel. On each mouse wheel move, a beginTimeZooming event is being fired. You can catch and cancel this event in order to prohibit this user action.
beginCategoryClosing NtCategoryEventArgs When double clicking on an open category row, that category will close. You will be informed about this by catching this event. You can also cancel the event and thereby prohibit the action and keep the category open.
beginCategoryOpening NtCategoryEventArgs When double clicking on a closed category row, that category will open. You will be informed about this by catching this event. You can also cancel the event and thereby prohibit the action and keep the category closed.
continueObjectDragging NtObjectDraggingEventArgs This Event is fired when horizontal dragging of data objects is going on. You can catch and cancel this event if you want to limit the dragging. For example if you do not want to allow users to drag objects beyond a certain limit (e.g. a day's limits) you can cancel this event. On the screen it then looks as if the objects can not be moved any further. Canceling this event does not interrupt the dragging procedure itself. Instead, when the next mouse move takes place the dragging can possibly go on.
displayObjectDblClick NtDisplayObjectEventArgs This Event is fired when a display object is being doubleclicked.
displayObjectClick NtDisplayObjectEventArgs This Event is fired when a display object is being clicked on.
displayObjectRightClick NtDisplayObjectEventArgs This Event is fired when a display object is being clicked on with the right mouse button.
displayObjectSelect NtDisplayObjectEventArgs This Event is fired when a display object is about to be selected. You can catch and cancel this event to prevent the selection.
endObjectDragging NtObjectDraggingEventArgs This Event is fired when horizontal dragging of data objects is about to complete. You can catch and cancel this event to prevent the dragging. This is useful if you initially allowd the dragging but then certain drag limits are exceeded (for example users dragged too far). Once you cancel this event all data objects flip back to their original position.
timeZoomed NtTimeZoomEventArgs The horizontal zoom factor (time scale) of the NtTimeChartControl can be adjusted by holding the Ctrl-Key and then using the mouse wheel. After each step of zooming, a timeZoomed event is being fired. Cancelling this event has no effect.

Top API Documentation -> NtTimeChartControl © 2016 Bassaly