BARGRAPH display function

(only available for certain programmable terminals)

Overview

Properties of a bargraph

Filling patterns

Syntax for a bargraph in a backslash sequence

See also:

• Manual for the programming tool (general)
• Modifying a display element's colours (etc) at runtime, e.g. depending on a signal

Overview

The bargraph functions are only supported by certain UPT variants with firmware from August 2002 or later.

Bargraphs may look like this:

(Screenshot of a bargraph demo for the old
MKT-View with monochrome display, programs/cdb_tst1.ct )

Every bargraph has a set of properties which must be defined on a special panel on the 'display line property' tab of the programming tool. More properties can be set in a special window which appears when clicking the "more" button (because we ran out of space on the "Bargraph" tab shown below)...

(Bargraph properties as part of a 'display element definition' in the main window)

The general properties like x-pos, y-pos, draw mode, etc are explained somewhere else. They also apply to normal text display.
Properties like 'Access' (access rights: read/write) and the option 'operable via touchscreen' will turn the 'simple Bargraph' into an interactive control element, like a scroll bar or 'value slider'.

Specific properties of a bargraph

The specific bargraph properties should be modified on an extra panel, which can be opened by double-clicking on a bargraph in the graphic editor, or by clicking the 'more' button on the main window's "bargraph" tab.

(Bargraph configuration dialog window, with 'specific' properties)

• Width, Height
  dimensions of a single bargraph display, measured in screen pixels
• Orientation
  Horizontal: bar grows from left to right
  Vertical: bar grows from bottom to top
  With the option 'flip min,max' (under 'Scale Range') the direction of movement can be reversed, i.e. with an increasing value, the bar's end (or needle, or block) moves from right to left, or from top to bottom. This is helpful if a bargraph is used as a 'scroll indikator'.
• Frames
  defines if rectangular frames shall be drawn inside or outside the bar.
  The space between "inner" and "outer" frame is used for the optional tick scale.
• Ticks:
  how many ticks shall be drawn in the tick scale. A value of "2" means the scale is divided into 2 segments, actually 3 small lines will be draw (one tick on the left, one in the middle and one on the right side).
• Scale:
  defines if tick scales shall be drawn somewhere inside the bar area (which is defined by the width+height parameters).
• Filling Pattern:
  a hex-coded pixel pattern used for the "filled" part of the bar. Try $FFFF for 'completely black' or $BBEE for a dark cross hatch.
• Erasing Pattern:
  pixel pattern used for the "empty" part of the bar. Try $0000 for 'completely blank' or $2288 for a weak cross hatch.
  Some examples for other filling and erasing patterns can be found here.
• Scale Range:
  The visible value range will be taken from the UPT's variable definition table (or the CANdb-signal-definition) if the checkmark "from VAR-def" is set. Otherwise, you can enter the value range yourself in the property panel shown above. The "min"-value will be at the left end of the bar, the "max"-value at the right end (or, if its a vertical bar, "min" at the bottom and "max" at the top). More on that here.
• Bar Origin:
  Defines the starting point of the bar. This is usually the minimum scale value, so the bar grows from left to right (if it's a horiziontal bar) or from bottom to top (it it's vertical). Alternatively you can set the origin to the maximum scale value, or any numeric value you want.
• Target / Peak indicator (not for UPT515) :
  This is a small marker in the bar area which indicates a target value, or the peak values from the last detection interval. Several combinations are selectable, and various graphic appearances for the peak/target indicator.
  The peak-detection-interval is 2 seconds by default. If necessary, it can be set via interpreter command 'pktime' to any value between 0.1 and 300 seconds (unit is 100 milliseconds), for example:
  pktime=100   sets the peak-detection-interval-time to 10 seconds.
  We suggest to change the pktime value only in a "page-enter" event of page zero.
  

Filling patterns

Because most terminals only have a simple black- and white display, different filling patterns can be used to fill the inner bargraph areas.

The filling pattern is defined as a 16-bit value (usually in hexadecimal notation). The lower 8 bits are used to fill 8 pixels in EVEN screen lines, the upper 8 bits for ODD lines. This can be used to create a large number of different filling patterns --- 65536 mostly useless combinations. Here just some patterns, generated with the programming tool itself:

(Screenshot with "Filling Patterns" for a monochrome bargraph)

As mentioned before, the hex coded values are actually pixel-masks for monochrome displays. Viewed from the distance, they give different shades of gray. If you have a terminal with a color display, the "foreground" and "background" color values defined on the property panel are also used for the bargraph (not only for normal text). For colour displays, use suitable colours instead, and only use filling patterns 0x0000 (-> background colour) and 0xFFFF (-> foreground colour).

Syntax for a bargraph in a backslash sequence

(only for curious or experienced users)

Internally, the bargraph is coded as a backslash sequence. The UPT's interpreter analyses it just like any other format string in a display command (which allows you to place leading text before the bargraph sequence). If you prefer writing the source code for a display page with a text editor instead of clicking it together with the mouse, this is for you:

Syntax:

\bar(width, height, flags, ticks, filling_pattern, erase_pattern, [scale_min, scale_max] )

where: width,height,ticks,filling and erasing pattern are the same properties as mentioned earlier.

The "flags" parameter is a bitcombination of orientation, frames, scale-style and scale-range-info (two bits per property).

The scale range (scale_min and scale_max) may only be defined in the backslash sequence if the min/max-values are NOT taken from the variable definition.

Important note:

Do not put other text (except the bargraph sequence shown above) in a display line definition which contains a bargraph.
There may be stoneage demo programs or 'gallery pages' floating around on your harddisk which also show the value in numeric form, in the same definition line which also displays a bargraph. SINCE 2009-11-26, THIS WILL NOT WORK ANYMORE !
(Reason: Embedding the width and hight of a display element inside the backslash sequence will be removed soon.)

Using a bargraph in a display definition without leading or trailing text should't be a problem, because (for devices with 32-bit CPU since 2009), a single display page may consist of a very large number of display elements, thanks to the 'flexible' storage of objects in the terminal's FLASH memory.

Details about the scale range

Disadvantage of specifying the scale range here as argument: It makes a display page less "universal". If you programmed a display page with 8 horizontal bars for temperatures in the range -50° ... +200° and want to re-use that page later to display 8 voltages in the range 0..50 Volts, you must adjust the scale range manually. Better: Use variables with a proper min/max-range in the VARIABLE DEFINITION TABLE (or the CANdb-definition) and activate the checkmark "Scale Range from VAR DEF".

This is especially important if you want to put such a display page into the Page Gallery.

Legal Terms

See main manual.

top