Top  | Previous | Next

Easy Chart

charts_EasyChart

Description

This component is used to make powerful and runtime-configurable timeseries charts. It is configured by defining a set of pens and axes. Each pen represents a series of data. Pens can be many different styles, such as line, area, bar, and shape. This chart automatically creates controls for picking the time range and for hiding or displaying pens.

 

Features

Easy configuration
User-selectable set of pens
Automatic time-selection controls
SQL Query and/or SQLTags Historian data sources
Automatic SPC and calculated pen support
Zoom, Pan, X-Trace modes
Any number of Y-axes and subplots
Realtime or Historical

 

Pens

The are three kinds of pens in the Easy Chart:

1.SQLTags Historian Pens. These pens pull their data from the SQLTags Historian system.
2.Database Pens. These pens will automatically create SQL SELECT queries to pull data from a database table. Typically, this is a table that is the target of a Historical Transaction Group.
3.Calculated Pens. These pens display a calculated dataset based off another pen, such as a moving average or an SPC function such as the UCL (Upper  Control Limit).

 

Modes: Realtime vs Historical

The Easy Chart can operate in 3 different modes. These modes affect the range of data that is displayed, the controls the user is shown, and whether or not the chart polls for data.

1.Historical Mode. In this mode, the user is shown a Date Range component to pick the range of data to fetch and display. The initial values of this component are set through properties on the chart. In historical mode, the chart does not poll.
2.Realtime Mode. In this mode, the user is given the opportunity to pick the amount of time in the past to display. For example, the last 5 minutes or the last 2 hours. The chart will poll at a rate according to the Poll Rate parameter.
3.Manual Mode. In this mode, the chart will use the values if its Start Date and End Date parameters to govern what data is displayed. Polling is controlled by having the Poll Rate at zero (polling off) or greater than zero.

 

Basic Chart Configuration

The Easy Chart has many properties, like other components, that control its behavior. Things like its Mode, Polling Rate, etc are configured via the properties. All of the setup for adding pens, axes, subplots, etc is its Customizer. You can also drag and drop Historian-enabled SQLTags onto the chart directly in the Designer to add those tags as chart pens.

 

Y-Axes

The easy chart supports any number of Y-axes. To add an axis, go to the Axes tab of the chart customizer. When adding an axis, you get a number of options such as the type (numeric or logarithmic), label, color, autorange vs fixed range, and auto-ticks vs fixed ticks. You can also modify the position of the axis, but note that by default the Chart's Auto Axis Positioning property is enabled, which means that the chart will balance the axes automatically between left and right depending on demand. As pens are turned on and off by the user, only the axes that are used by visible pens are shown.

 

After you add your axes, you edit any pens that you want to use your new axes. Simply choose the new axis in the axis dropdown of the pen editing window.

 

Subplots

The Subplots feature lets you break up the chart's plot area into multiple distinct subplots that share the X axis, but have their own Y axes. This is often useful for digital data, as shown in the screenshot above. By default the chart has 1 subplot (the main plot). To add a new subplot, simply hit the add button in the Subplots tab of the chart customizer.

 

Subplots have relatively few options. The Weight option determines how much room the subplot gets relative to the other subplots. For example, in the screenshot above subplot #1's weight is 5, and subplot #2's weight is 1, leading to a 5-to-1 distribution of space. Just like axes, once you add your subplots you should go back to your pens and modify you pens' subplot property for any pens you want to appear on the subplot.

 

Pen Groups

You can put your pens in groups to break up the pens into some logical separation. For instance, in the screenshot above there are three pen groups: C1, C2, and Valves. The group name is used as the titled border for the pens' grouping container. Groups also have another purpose, but it is more advanced and most people won't have to worry about it. For more, read the Dynamic Pens section below.

 

Advanced Configuration

Dynamic Pens

In is often the case that you'll want to make one chart window that services many similar pieces of equipment. For instance, if you have 30 tanks and they all have the same datapoints, you want to be able to use one window for all 30 of them and simply pass the tank number into the chart window as a parameter. There are actually a number of ways to accomplish this, each method suitable for different scenarios.

 

Database pens have 2 ways to be made dynamic. The first is the Chart's Where Clause property. This is a snippet of SQL where clause syntax, like "machine_num = 28" that will be included for all database pens in their queries. The second is to use a dynamic group. Any group can be made a dynamic group in the customizer. For each dynamic group, the easy chart will get a special dynamic property associated with that group. That property is another snippet of SQL where clause that will be applied to all database pens in that group.

 

The other way to make your pens (and anything else about the chart) dynamic at runtime is to use dynamic configuration. Read on...

 

Dynamic Configuration

The Easy Chart is not just meant to be easy to configure, but also very powerful. In particular, there is an emphasis on the ability to make any configuration change dynamically in a client - not just statically in the Designer. While a bit of scripting or clever property binding may be required, the technique is very powerful. This is achieved by storing all of the settings that you alter in the customizer in a set of expert-level dataset properties. So altering the datasets alters the chart configuration. You can inspect these various datasets, which hold the pens, axes, and subplot information, to see their format. They all look up information by column name (case-insensitive). So, if you have pen configuration stored in a database, you can bind an indirect SQL Query binding to alter the chart's pen set at runtime.

Properties

Appearance

Foreground Color

The foreground color of the component.

Scripting name

foreground

Data type

Color

Background Color

The background color of the component.

Scripting name

background

Data type

Color

Plot Background

The background color for all plots, unless they override it

Scripting name

plotBackground

Data type

Color

Plot Outline

The color to use for the plot outline.

Scripting name

plotOutlineColor

Data type

Color

Date Editor Foreground

The foreground color for the date editor.

Scripting name

editorForegroundColor

Data type

Color

Date Editor Background

The background color for the date editor.

Scripting name

editorBackgroundColor

Data type

Color

Gridline Color

The color of the gridlines.

Scripting name

gridlineColor

Data type

Color

Gridline Width

The width (thickness) of the gridlines.

Scripting name

gridlineWidth

Data type

float

Gridline Dash Pattern

The dash pattern for the gridlines.

Scripting name

gridlineDashPattern

Data type

String

Border

The border surrounding the entire chart component.

Scripting name

border

Data type

Border

Chart Border

The border for the chart itself

Scripting name

chartBorder

Data type

Border

Pen Control Border

The border for the pen control panel, if visible

Scripting name

penBorder

Data type

Border

Date Range Border

The border for the date range control, if visible

Scripting name

dateRangeBorder

Data type

Border

Chart Title

Sets an optional title to be displayed above the chart

Scripting name

title

Data type

String

Title Font

The font for the optional chart title.

Scripting name

titleFont

Data type

Font

X Axis Label

The label shown on the X Axis (time axis)

Scripting name

xAxisLabel

Data type

String

X Axis Visible

Should the x-axis be displayed?

Scripting name

xAxisVisible

Data type

boolean

Flags

expert

Font

Font of text of this component

Scripting name

font

Data type

Font

Axis Font

The font for axis labels

Scripting name

axisLabelFont

Data type

Font

Tick Font

The font for tick labels

Scripting name

axisTickLabelFont

Data type

Font

X-Trace Large Number Format

The large decimal format for the x-trace value in the easy chart.

Scripting name

xTraceLargeNumberFormat

Data type

String

X-Trace Small Number Format

The small decimal format for the x-trace value in the easy chart.

Scripting name

xTraceSmallNumberFormat

Data type

String

X-Trace Number Format Threshold

If the magnitude of the to-be-formatted value is below this threshold, then the X-Trace Small Number Format will be used.

Scripting name

xTraceNumberFormatThreshold

Data type

double

Behavior

Chart Mode

Affects the mode that the chart operates in.Manual Mode: the data selected is determined by the values of the Start Date and End Date properties, which must be set manually.Historical Mode: a date range component will be displayed by the chart, allowing the user to select the time period they are interested inRealtime Mode: the user will be given the change to choose a span of time, like 15 minutes, and that span will be updated at the poll rate as the data scrolls across

Scripting name

chartMode

Data type

int

Flags

bindable

Values

0

Manual

1

Historical

2

Realtime

Pen Control?

Controls whether or not end-users can turn on and off pens.

Scripting name

allowPenManipulation

Data type

boolean

Pen Control Mode

The style in which the pen control panel alters the chart configuration. In heavyweight mode, unchecked pens are not queried, but checking and unchecking pens refreshes the chart. In lightweight mode, all pens are queried, but checking and unchecking pens is quick.

Scripting name

penControlMode

Data type

int

Values

0

Heavyweight

1

Lightweight

Auto Apply

If true, user changes to pen visibility will occur immediately.

Scripting name

autoApply

Data type

boolean

Poll Rate

The rate (in milliseconds) at which this chart's queries poll. Historical charts don't use this property.

Scripting name

pollRate

Data type

int

X Axis AutoRange?

If true, the X axis will automatically fit the range of available data, if false, it will display a fixed range based on the start date and end date.

Scripting name

xAxisAutoRange

Data type

boolean

X Axis Margin

A margin for the upper and lower ends of the x axis, expressed as a percentage of the total range.

Scripting name

xAxisMargin

Data type

double

Empty Group Name

The group name to use for pens that are not in a pen group.

Scripting name

emptyGroupName

Data type

String

Group Pens

If true, pens will be grouped by their group name

Scripting name

penGrouping

Data type

boolean

Auto Axis Positioning

If true, axes alternate automatically between left and right, rather than being placed explicitly.

Scripting name

autoPositionAxes

Data type

boolean

Flags

expert

Auto Pen Coloring

If true, pens are assigned different colors automatically.

Scripting name

autoColorPens

Data type

boolean

Flags

expert

Auto Color List

The list of colors to use if auto pen coloring is enabled

Scripting name

autoColorList

Data type

Color[]

Flags

expert

Show Loading

If true, an animated indicator will be shown when data is loading

Scripting name

showLoading

Data type

boolean

Show Warnings

If true, warnings generated during chart configuration will be printed to the console.

Scripting name

showWarnings

Data type

boolean

Flags

expert

Show Popup?

If true, a popup menu will be shown on right-click that allows the user to change mode, print, save, etc.

Scripting name

showPopup

Data type

boolean

Flags

expert

Show Tooltips?

If true, tooltips showing point values will be displayed on the chart.

Scripting name

tooltips

Data type

boolean

Chart Configuration

DB Pens

This Dataset defines all of the database pens for the chart.

Scripting name

pens

Data type

Dataset

Flags

bindable | expert

Tag Pens

This Dataset defines all of the SQLTag History pens for the chart.

Scripting name

tagPens

Data type

Dataset

Flags

bindable | expert

Calculated Pens

This Dataset defines the calculated pens for the chart.

Scripting name

calcPens

Data type

Dataset

Flags

bindable | expert

Axes

This Dataset defines all axes that can be used by the pens.

Scripting name

axes

Data type

Dataset

Flags

expert

Subplots

This Dataset defines all subplots' relative size and color.

Scripting name

subplots

Data type

Dataset

Flags

expert

Common

Name

The name of this component.

Scripting name

name

Data type

String

Flags

bindable

Visible

If disabled, the component will be hidden.

Scripting name

visible

Data type

boolean

Flags

bindable

Mouseover Text

The text that is displayed in the tooltip which pops up on mouseover of this component.

Scripting name

toolTipText

Data type

String

Cursor

The mouse cursor to use when hovering over this component.

Scripting name

cursorCode

Data type

int

Flags

expert

Values

0

Default

1

Crosshair

2

Text

3

Wait

12

Hand

13

Move

4

SW Resize

5

SE Resize

6

NW Resize

7

NE Resize

8

N Resize

9

S Resize

10

W Resize

11

E Resize

Data

Selected X Value

The selected domain axis value for X-Trace and Mark modes.

Scripting name

selectedXValue

Data type

String

Flags

bindable | read-only

Tag History Resolution

The number of datapoints to request for tag history pens. -1 means automatic, which uses the width of the chart.

Scripting name

tagHistoryResolution

Data type

int

Flags

expert

Where Clause

A snippet of where clause that will be applied to all pens, like "TankNum = 2"

Scripting name

globalWhereClause

Data type

String

Start Date

For manual-mode. The start date to use for selecting pen data

Scripting name

startDate

Data type

Date

Flags

bindable

End Date

For manual-mode. The end date to use for selecting pen data

Scripting name

endDate

Data type

Date

Flags

bindable

Historical Range

Startup Range

For historical-mode date range. If startup mode is Automatic, this will be the starting range of time available for selection.

Scripting name

startupRange

Data type

String

Startup Selection

For historical-mode date range. If startup mode is Automatic, this will be the starting selected range.

Scripting name

startupSelection

Data type

String

Max Selection

For historical-mode date range. The maximum size of the selected date range.

Scripting name

maxSelectionSize

Data type

String

Outer Range Start

For historical-mode date range. The start date for the outer range.

Scripting name

outerRangeStart

Data type

Date

Flags

expert

Outer Range End

For historical-mode date range. The end date for the outer range

Scripting name

outerRangeEnd

Data type

Date

Flags

expert

Date Style

The style to display dates in. For international support.

Scripting name

dateStyle

Data type

int

Flags

expert

Values

0

Auto

1

MDY

2

DMY

3

YMD

Time Style

The style to display times of day. For international support.

Scripting name

timeStyle

Data type

int

Flags

expert

Values

15

Auto

16

12 HR

17

24 HR

Show Density

For historical-mode date range. If true, a data density histogram will be shown in the date range.

Scripting name

showHistogram

Data type

boolean

Today Color

For historical-mode date range. The color of the "Today Arrow" indicator

Scripting name

todayIndicatorColor

Data type

Color

Flags

expert

Box Fill

For historical-mode date range. The fill color for the selection box.

Scripting name

boxFill

Data type

Color

Flags

expert

Selection Highlight

For historical-mode date range. The focus highlight color for the selection box

Scripting name

selectionHighlight

Data type

Color

Flags

expert

Track Margin

For historical-mode date range. The amount of room on either side of the slider track. May need adjusting of default font is changed.

Scripting name

trackMargin

Data type

int

Flags

expert

Tick Density

For historical-mode date range. This is multiplied by the width to determine the current ideal tick unit.

Scripting name

tickDensity

Data type

float

Flags

expert

High Density Color

For historical-mode date range. The color used to indicate high data density.

Scripting name

highDensityColor

Data type

Color

Flags

expert

Layout

Plot Orientation

The plot orientation for all plots.

Scripting name

plotOrientation

Data type

int

Values

1

Horizontal

0

Vertical

Invert Time Axis

If true, the time axis values will increase from the right to left or from top to bottom depending on the Plot Orientation.

Scripting name

invertTimeAxis

Data type

boolean

Date Range

Affects the position of the date range control.

Scripting name

dateRangeLocation

Data type

int

Values

1

Top

2

Bottom

Legend

Where the legend should appear, if any.

Scripting name

legend

Data type

int

Values

0

None

1

Top

2

Bottom

3

Left

4

Right

Horiz Gap

The horizontal spacing to use for the pen checkboxes

Scripting name

hGap

Data type

int

Flags

expert

Vert Gap

The vertical spacing to use for the pen checkboxes

Scripting name

vGap

Data type

int

Flags

expert

Alphabetize Pens

If true, pens visibility checkboxes will be alphabetized.

Scripting name

alphabetizePens

Data type

boolean

Flags

expert

Subplot Gap

The gap between subplots

Scripting name

subplotGap

Data type

double

Flags

expert

Pen Style Options

Bar Margin

The margin to use for the 'Bar' pen style

Scripting name

barMargin

Data type

double

Flags

expert

Gap Threshold

The relative threshold to use for determining continuity breaks for the 'Discontinous Line' pen style

Scripting name

gapThreshold

Data type

double

Flags

expert

3D X Offset

The offset to use in the x direction for the '3D Line' pen style

Scripting name

xOffset3D

Data type

int

Flags

expert

3D Y Offset

The offset to use in the y direction for the '3D Line' pen style

Scripting name

yOffset3D

Data type

int

Flags

expert

Digital Gap

The size of the gap to use between digital pens

Scripting name

digitalGap

Data type

double

Flags

expert

Realtime Range

Unit Count

For realtime-mode date range. The number of units back to display

Scripting name

unitCount

Data type

int

Unit

For realtime-mode date range. The selected unit of the realtime date control

Scripting name

unit

Data type

int

Values

1

Seconds

60

Minutes

3600

Hours

86400

Days

Realtime Text

For realtime-mode date range. The text to display on the realtime date control.

Scripting name

rtLabel

Data type

String

Uncategorized

Properties Loading

The number of properties currently being loaded

Scripting name

propertiesLoading

Data type

int

Flags

bindable | read-only

Total Datapoints

The number of datapoints being displayed by the graph.

Scripting name

datapoints

Data type

int

Flags

bindable | read-only

Utility Buttons

Show Maximize Button?

If true, a small maximize button will be displayed next to the chart.

Scripting name

showMaximize

Data type

boolean

Show Print Button?

If true, a small print button will be displayed next to the chart.

Scripting name

showPrint

Data type

boolean

Show Save Button?

If true, a small save button will be displayed next to the chart.

Scripting name

showSave

Data type

boolean

Button Size

The size of the utility button icons.

Scripting name

utilityButtonSize

Data type

int

Flags

expert

Scripting

Events

The following event sets are fired by this component. See Component Event Handlers to learn more.

mouse
mouseMotion
propertyChange

 

Scripting Functions

This component has no special scripting functions.