Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Tsentry HMI libraries are composed of a set of objects to facilitate the creation and usage of real-time HMI screens on the Tsentry Windows NT/2000/XP platform.

TPRI.BaseScreen

Expand
titleOverview

The TPRI.BaseScreen class is the base class from which all user screens should be inherited. It provides the default functionality to automate communications with TSENTRY controller, access the data dictionary, and navigate between screens.

Expand
titleOperation

The TPRI.BaseScreen class should not be used by itself; it is intended solely for use as a base class for other screens.

The simplest custom user screens need only to inherit from the TPRI.BaseScreen class in order to take advantage of common functionality provided by the BaseScreen class.  However, if a custom screen wishes to perform some initialization as the screen is started (i.e. once the display is active and all contained objects are instantiated) it should override the StartScreen(..) method.  By the same token, if a custom screen wishes to implement some form of security, it should override the SecureScreen(..) method to modify itself for the current security level.

...

titleProperties

...

The Tsentry HMI libraries are composed of a set of objects to facilitate the creation and usage of real-time HMI screens on the Tsentry Windows NT/2000/XP platform.

...

TPRI.BaseScreen

Expand
titleOverview

The TPRI.BaseScreen class is the base class from which all user screens should be inherited. It provides the default functionality to automate communications with TSENTRY controller, access the data dictionary, and navigate between screens.

Expand
titleOperation

The TPRI.BaseScreen class should not be used by itself; it is intended solely for use as a base class for other screens.

The simplest custom user screens need only to inherit from the TPRI.BaseScreen class in order to take advantage of common functionality provided by the BaseScreen class.  However, if a custom screen wishes to perform some initialization as the screen is started (i.e. once the display is active and all contained objects are instantiated) it should override the StartScreen(..) method.  By the same token, if a custom screen wishes to implement some form of security, it should override the SecureScreen(..) method to modify itself for the current security level.

Expand
titleProperties

The following protected properties are exposed by the TPRI.BaseScreen class.

Property Name

Type

Default Value

Description

sHostName

String

""

Host IP address.

sFullPath

String

""

Full path of container page on host.

sPathDir

String

""

Directory of container page on host.

sPageName

String

""

Name of container page on host.

sStartArgs

String

""

Screen arguments used to modify program operation.

Expand
titleMethods

The following public methods are exposed by the TPRI.BaseScreen class.

Code Block
Protected Overridable Function StartFromAsp( _
ByRef vobjWindow As Object _
) As Integer

Description:

Start active operation of the screen from an ASP web page.

Parameters:

vobjWindow

Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container ASP to initiate activity on the screen.

 

Code Block
Protected Overridable Function StartFromForm( _
ByRef vobjForm As Object, _
ByRef host As String, _
ByRef path As String, _
ByRef args As String _
) As Integer

Description:

Start active operation of the screen.

Parameters:

vobjContainer

Form object containing this screen.

host

Name or IP address of the host system to which the screen should connect..

path

Path to page on host.

args

String argument(s) to pass to screen for initialization/customization.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container form to initiate activity on the screen.

 

The following overridable methods are exposed by the TPRI.BaseScreen class.

 

Code Block
Protected Overridable Function StartScreen( _
ByRef vobjContainer As Object _
) As Integer

Description:

Start active operation of the screen.

Parameters:

vobjContainer

Container object.  If screen is started from a web page, this will contain a reference to the Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to provide custom startup functionality.

 

Code Block
Protected Overridable Sub SecureScreen( _
ByVal securityLevel As Integer _
)

Description:

Secure the screen according to the specified security level.

Parameters:

securityLevel

Security level of the user.  This value is a bitmask of rights provided to the user.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to implement security on individual screens.

 

Code Block
Protected Overridable Sub LinkTo( _
ByVal URL As String _
)

Description:

Navigate the current screen to a new page.

Parameters:

URL

URL of the new page.  Alternatively, passing the string '@MENU' links the screen back to the most recent menu and passing the string '@BACK' links the screen back to the previous page.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the most recent menu page.

Remarks:

Calling this method is equivalent to calling LinkTo("@MENU").

 

Code Block
Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the previous page.

Remarks:

Calling this method is equivalent to calling LinkTo("@BACK").

Expand
titleEvents

The following events are exposed by the TPRI.BaseScreen class.

Code Block
Public Event OnLinkTo( _
ByVal page As String _
)

Description:

Indicates screen request to navigate to a different page.

Parameters:

page

Name of the next page to load.

 

Code Block
Public Event ErrorTerminate()

Description:

Indicates the screen has reached a fatal error and must terminate.

TPRI.BaseControl

Expand
titleOverview

The TPRI.BaseControl class is the base class from which all TSENTRY screen component controls are derived. It provides various functions in common use throughout the TSENTRY controls.

Expand
titleOperation

The TPRI.BaseControl class should not be used directly on any user page.  It is intended solely for use as a base class for other active objects.

Expand
titleProperties

The following protected properties are exposed by the TPRI.BaseControl class.

Property Name

Type

Default Value

Description

pMgr

Object

Nothing

Reference to active manager object on parent form.

myIdx

Integer

-1

Index of this object on parent form. This is used to identify this object in calls to methods of active manager object.

bActiveMode

Boolean

True

Indicates whether or not this is an active object.

Expand
titleMethods

The following overridable methods are exposed by the TPRI.BaseControl class.

 

Code Block
Public Overridable Sub OnInitialized()

Description:

Indicates that all control properties have been loaded from the screen.

 

Code Block
Public Overridable Function GetActiveVars( _
ByRef varList() As String, _
ByRef tagList() As String _
) As Integer

Description:

Retrieve the variable/tag pairs to be requested from the data host on behalf of the object.

Parameters:

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with tags associated with each of the variables in the varList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arrays.

Remarks:

Derived classes that wish to request variables from the host system should override this method to fill in the lists of variables and tags.  The method AddActiveVar(..) should be used to build these lists.

 

Code Block
Public Overridable Function UpdActiveVar( _
ByVal tag As String, _
ByVal value As Object, _
ByVal timestamp As Date, _
ByVal quality As Integer _
) As Integer

Description:

Update the value of one of the active variables associated with the control.

Parameters:

tag

Tag of updated variable.

value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

If this method is overridden by a derived class, the default implementation of UpdActiveVar(..) should be called to ensure that the OnActiveUpd(..) event below is raised.

 

Code Block
Public Overridable Function GetModifiedVars( _
ByRef tagList() As String, _
ByRef valList() As Object _
) As Integer

Description:

Retrieve list of variables and corresponding values that have been modified and must be written back to the data host.

Parameters:

tagList()

List to be populated with tags to be updated back to data host.

valList()

List to be populated with values associated with each of the tags in the tagList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned tagList() and valList() arrays.

Remarks:

This function is called by the manager to find all variables and values that should be written back to the server.  Any derived control should fill in the passed arrays with the appropriate variable/value pairs, reset any internal data-changed flags, reset its display to indicate that the variables have been sent to the server, and wait for the next update from the server as a confirmation that the updates took place.

 

Code Block
Public Overridable Sub SetDisconnected()

Description:

Set the object into a disconnected state.

Remarks:

This function is provided as a callback to a derived class to reset the display of the object to indicate that it is no longer connected to live data.

 

The following public methods are exposed by the TPRI.BaseControl class.

 

Code Block
Public Function IsInitialized() As Boolean

Description:

Indicates whether or not all control properties have been loaded from data stored in screen initialization.

Return Value:

Flag indicating whether or not all control properties have been loaded from data stored in screen initialization.

 

Code Block
Public Function InitActiveVars( _
ByRef pManager As Object, _
ByRef iTscIdx As Integer, _
ByRef varList() As String, _
ByRef tagList() As String _
) As Integer

Description:

Initialize the BaseControl object and retrieve all variables and tags that are to be requested from the server on behalf of the object.

Parameters:

pManager

Reference to manager (typically TPRI.OpcMgr) object on parent form.

iTscIdx

Index of this BaseControl object on parent form.  This value is later used to identify this control in calls to various manager methods.

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with fully tags to be associated with each of the variables in the varList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arrays.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

Code Block
Protected Sub AddActiveVar( _
ByRef varList() As String, _
ByRef tagList() As String, _
ByRef count As Integer, _
ByRef var As String, _
ByRef tag As String _
)

Description:

Add the specified variable name and tag to the supplied lists and increment the total count.

Parameters:

varList()

Array to which the variable name should be added.

tagList()

Array to which the variable tag should be added.

count

Total count of variable name/tag pairs in the above lists.

var

Name of variable to add to the list.

tag

Variable tag to add to the list.

Remarks:

Derived classes that wish to request variables from the host system should use this method to add variable/tag pairs to the supplied lists.

Code Block
Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As String _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

String containing type of control to search for.  If type = "*", search all types.

Return Value:

The index of the control in the collection, or -1 if not found.

 

Code Block
Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As Type _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

Type of control to search for.

Return Value:

The index of the control in the collection, or -1 if not found.

Expand
titleEvents

The following events are exposed by the TPRI.BaseControl class.

Code Block
Public Event OnActiveUpd( _
ByVal Sender As Object, _
ByVal tag As String _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

TPRI.TextBox

Expand
titleOverview

The TPRI.TextBox is used for live display and input of a scalar variable in global common.

Image Added
Expand
titleOperation

The TPRI.TextBox control can operate in two modes: display-only mode and input mode.  In display-only mode, the value is continually updated as the value in global common changes, but the user is locked out from modifying the displayed value.  

In input mode, the text box is unlocked to allow the user to modify the displayed value.  Once the user starts to type in a new value, the background color of the display changes color and the active update of the value is put on hold to allow the user to finish changing the value.  Note that this new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when leaving the control or the Enter button is pressed.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Expand
titleProperies

Below are all of the properties of the TPRI.TextBox object.

Property Name

Type

Default Value

Description

tAutoValidateMinMax

Boolean

False

Indicates whether or not the text box should try to validate user-entered data against the min/max values specified in the data dictionary

tBackReadOnlyColor

COLOR

Color.White

Background color of read-only text box

tBackWriteDisplayColor

COLOR

Color.Khaki

Background color of editable text box while in display mode

tBackWriteEditColor

COLOR

Color.SandyBrown

Background color of editable text box while in edit mode

tChanged

Boolean

False

Determines if user has edited the text box

tDataSource

String

Empty string ("")

This is the name of the host variable

tDisconnectedStr

String

"###"

Text in textbox when disconnected from the OPC server. May not be used if tDataSource = ""

tEnabled

Boolean

True

Enables the textbox on the screen

tFocusColor

COLOR

Color.Lime

Sets the color to outline the textbox when it is in focus

tFormat

String

Empty string ("")

Formats how the text is displayed

tLocked

Boolean

False

Toggles between display  and edit mode

tResetStr

String

"@@@"

String to be displayed when waiting for an update from OPC server

tResetToStr

Boolean

True

Determines whether to display the tResetStr string when waiting for an update

tText

String

Empty string ("")

Text displayed in textbox

tToolTipText

String

Empty string ("")

Tooltip text for textbox

AutoSubmit

Boolean

False

Automatically submit changes to the host when leaving the control or the Enter button is pressed if the flag is set to True.

Expand
titleMethods

The following events are exposed by the TPRI.TextBox class.

 

Public Function tTextReset() As String

Description:

If unlocked (tLocked = False), reset the display of the object to indicate that the value has not been modified.  If tResetToStr = True, reset the text displayed to the tResetStr string as well.

Return Value:

The string originally contained in the object.

Remarks:

This function is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next update.

Expand
titleEvents

The following events are exposed by the TPRI.TextBox class.

Code Block
Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

TPRI.Shape

Expand
titleOverview

The TPRI.Shape is used as a basic shape control (similar to the Shape control in VB6).  

Image Added
Expand
titleOperation

The Shape object allows the designer to create the visual shape controls on the screens. It is a basic shape control without the specific logic ties to any other controls. It can be used as a base control to create the specific type of shape control.

The Shape control is configured by modifying the Shape, BorderOption, and FillOption properties.  Shape property provides the outline (shape) of the control. The BorderOption property provides the options of shape control border (width, color...). The FillOption property provides the options of shape control fill (color, style...)

Expand
titleProperties

Below are all of the properties of the TPRI.Shape object.

Property Name

Type

Default Value

Description

BorderOptions.Color

COLOR

Color.Black

 

Color of the border of the shape.  This is only used if the border Width > 0.

BorderOptions.

DashStyle

Drawing2D.DashStyle

Solid

Dash

Dot

DashDot

DashDotDot

Custom

Solid

Style of the border of the shape.  This is only used if the border Width > 0.

 

BorderOptions.Width

Integer

1

Width of the border of the shape.

BorderOptions.

GradientOn

Boolean

False

Specifies if the border should be painted as a gradient from one color to another.

BorderOptions.

GradientStyle

     Drawing2D.

LinearGradientMode

 

BackwardDiagonal

ForfardDiagonal

Horizontal

Vertical

Horizontal

Specifies the style of the gradient border.  This is only used if GradientOn = True.

BorderOptions.

GradientStartColor

COLOR

Empty

Gradient border start color.  This is only used if GradientOn = True.

BorderOption.

GradientEndColor

COLOR

Empty

Gradient border end color.  This is only used if GradientOn = True.

FillOptions.SolidColor

COLOR

Color.Transparent

Solid fill color of the shape.  This is only used if the FillStyle = Solid.

FillOptions.FillStyle

FillStyleConstants

0 - Solid

1 - Hatch

2 - Gradient

0

Fill style for the shape.

FillOptions.HatchColor

COLOR

Color.Black

Hatch color of the shape.  This is only used if FillStyle = Hatch.

FillOptions.HatchStyle

Drawing2D.HatchStyle

 

BackwardDiagonal

Cross

ZigZag

BackwardDiagonal

Hatch style of the shape.  This is only used if FillStyle = Hatch.

FillOptions. GradientStyle

Drawing2D.

LinearGradientMode

 

BackwardDiagonal

ForfardDiagonal

Horizontal

Vertical

Horizontal

Gradient style of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientStartColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientEndColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

Expand
titleMethods

There are no public methods exposed by the TPRI.Shape class.

Expand
titleEvents

There are no public events exposed by the TPRI.Shape class.

TPRI.ActiveShape

Expand
titleOverview

The TPRI.ActiveShape is used to provide a graphical indication of the current value of a variable in global common.  

Image Added
Expand
titleOperation

The TPRI.ActiveShape object allows the designer to divide the real number line into multiple ranges and assign a different shape and color for each range.  As the variable value is automatically updated to the control, the appropriate shape and color is displayed based on the range into which the current value falls.

  • For example, the ActiveShape control can be used to display the current speed of a rolling mill.  If the speed is less than 10 feet per minute, the shape will display a red square with the text Stopped.  If the speed is greater than 10 feet per minute but less than 300 feet per minute, the display is a light blue square with the text Creep.  If the speed is greater than 300 feet per minute the display will be a green circle with the text Run.  Alternatively, the ActiveShape can be configured to display the current value of the speed variable rather than the text descriptions above.

If the current value of the variable is not actively being updated by the server, the ActiveShape will take on a separate display configuration to indicate that there is a communications problem.

The ActiveShape control is configured by modifying the ActiveShapeSetup property.  This property is actually an array of ActiveShapeSetup class objects, where each ActiveShapeSetup class contains all of the properties required to describe the display configuration for a range along the real number line.  

  • Following the mill speed example above, there would be three ActiveShapeSetup objects in this array: one indicating the configuration when the speed variable is less than 10, one for when the speed is greater than 10 but less than 300, and a third for when the speed is greater than 300.

Each ActiveShapeSetup object has a property BoundMax, which defines the maximum value of the range.  The minimum value of the particular range is implied by the maximum value of the previous ActiveShapeSetup object in the array; hence the ranges of the real number line are defined in ascending order with each additional ActiveShapeSetup object in the array.  The two exceptions are the first and last ActiveShapeSetup objects in the array.  First, the minimum value of the range defined by the ActiveShapeSetup(0) object in the array (since there is no ActiveShapeSetup(-1) object in the array) is assumed to be negative infinity.  Second, the BoundMax property of the last ActiveShapeSetup object in the array is ignored and taken to be positive infinity.

Following would be the bounds defined for the speed example given above:

Code Block
ActiveShapeSetup(0) BoundMax = 10
ActiveShapeSetup(1) BoundMax = 300
ActiveShapeSetup(2) BoundMax = 99999 (this is assumed to be +∞)
Screen arguments used to modify program operation
Expand
titleProperties

The ActiveShapeSetup object contains the following properties for configuring the display for a given range.  Note that the display configuration while disconnected (specified by the ActiveShape property DisconnectSetup) is also an ActiveShapeSetup object, so any of these properties can be modified to effect the display when communications are off-line.

Property Name

Type

Default Value

Description

BorderOptions.Color

COLOR

Color.Black

Color of the border of the shape.  This is only used if the border Width > 0.

BorderOptions.

DashStyle

Drawing2D.DashStyle

Solid

Style of the border of the shape.  This is only used if the border Width > 0.

BorderOptions.Width

Integer

1

Width of the border of the shape.

BorderOptions.

GradientOn

Boolean

False

Specifies if the border should be painted as a gradient from one color to another.

BorderOptions.

GradientStyle

Drawing2D. LinearGradientMode

Horizontal

Specifies the style of the gradient border.  This is only used if GradientOn = True.

BorderOptions.

GradientStartColor

COLOR

Empty

Gradient border start color.  This is only used if GradientOn = True.

BorderOption.

GradientEndColor

COLOR

Empty

Gradient border end color.  This is only used if GradientOn = True.

FillOptions.SolidColor

COLOR

Color.Transparent

Solid fill color of the shape.  This is only used if the FillStyle = Solid.

FillOptions.FillStyle

FillStyleConstants

0 - Solid

1 - Hatch

2 - Gradient

0

Fill style for the shape.

FillOptions.HatchColor

COLOR

Color.Black

Hatch color of the shape.  This is only used if FillStyle = Hatch.

FillOptions.HatchStyle

Drawing2D.HatchStyle

BackwardDiagonal

Hatch style of the shape.  This is only used if FillStyle = Hatch.

FillOptions. GradientStyle

Drawing2D.

LinearGradientMode

Horizontal

Gradient style of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientStartColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientEndColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

Font

Font

MS Sans Serif/ Bold/ Size=12

Provides the font for any text shown inside the ActiveShape control.   The text will be centered.  If the font is changed, the height of the label area increases.

Shape

ShapeConstants

0 - Rectangle

1 - Square

2 - Oval

3 - Circle

Rectangle

Specifies the shape displayed.

 

Text

String

Text

Specifies the text to be display.

TextColor

COLOR

Color.Black

ForeColor for the text

TextBlinking

Boolean

False

Indicates if the displayed text should blink.  This is only used if ShapeBlinking = False and BlinkingPeriod > 0.

ShapeBlinking

Boolean

False

Indicates if the entire shape should blink.  This is only used if BlinkingPeriod > 0.

BlinkingPeriod

Integer

0

The blinking frequency (the number of milliseconds between the changes) if either TextBlinking or ShapeBlinking are True.

BoundMax

Integer

0

Maximum value for this range.

BoundIncludeEquals

Boolean

False

Specifies whether or not BoundMax is inclusive.  If True, then values <= BoundMax will fall into this range; otherwise only values < BoundMax will fall into this range.

ValueDisplay

Boolean

False

If the property is set to True, then the text label of the ActiveShape will show the variable value instead of showing Text.

ValueFormat

String

Empty string ("")

Formatting string for the display of the current variable value if ValueDisplay = True.

The remaining properties of the ActiveShape class are as follows:

Property Name

Type

Default Value

Description

sHostName

String

""

Host IP address.

sFullPath

String

""

Full path of container page on host.

sPathDir

String

""

Directory of container page on host.

sPageName

String

""

Name of container page on host.

sStartArgs

String

""

BackColor

COLOR

Color.Red

Provides the "default" color for the shape (in the case that none of the bound conditions is true).

ActiveShapeSetup()

ActiveShapeSetup

 

Display setup for various ranges.

DisconnectSetup

ActiveShapeSetup

 

Display setup when not connection.

tNumTextLines

Short ( >=1 and < 4)

1

Determines (with the font.size) the height of the ActiveShape label.  Cannot be changed if the shape property is oval or circle.

tDataSource

String

Empty string ("")

This is the name of the host variable

tURL

String

Empty string ("")

Assigns a target web page to go to when object is clicked

tValue

Single

0

This property is responsible for the current presentation of the Active Shape

tLocked

Boolean

False

Used to lock the control to prevent updates until the control is unlocked.

Expand
titleMethods

The following public methods are exposed by the TPRI.BaseScreen ActiveShapeArray class.

Code Block
Protected Overridable Function StartFromAsp( _
ByRef vobjWindow As Object _
) As Integer

Description:

Start active operation of the screen from an ASP web page.

Parameters:

vobjWindow

Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container ASP to initiate activity on the screen.

 

Code Block
Protected Overridable Function StartFromForm( _
ByRef vobjForm As Object, _
ByRef host As String, _
ByRef path As String, _
ByRef args As String _
) As Integer

Description:

Start active operation of the screen.

Parameters:

vobjContainer

Form object containing this screen.

host

Name or IP address of the host system to which the screen should connect..

path

Path to page on host.

args

String argument(s) to pass to screen for initialization/customization.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container form to initiate activity on the screen.

 

The following overridable
Expand
titleEvents

The following events are exposed by the TPRI.ActiveShape class.

Code Block
Public Event Click ( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

TPRI.ActiveShapeArray

Expand
titleOverview

The TPRI.ActiveShapeArray provides the methods, properties and events to create and access an array of TPRI.ActiveShape controls.

Expand
titleProperties

The following properties are exposed by the TPRI.ActiveShapeArray class.

Code Block
Default Public ReadOnly Property Item ( _
ByVal index As Integer _
) As TPRI.ActiveShape

Description:

Access TPRI.ActiveShape controls in the collection by index.

Parameters:

index

Index of the ActiveShape object to access.

Return Value:

Indexed ActiveShape object.

Protected Overridable Sub SecureScreen

ActiveShape object to add to the array.

Expand

The following methods are exposed by the TPRI.BaseScreen ActiveShapeArray class.

 

Code Block
ProtectedPublic OverridableSub FunctionAdd StartScreen( _
ByRefByVal vobjContainervalue As ObjectTPRI.ActiveShape _
) As Integer

Description:

Start active operation of the screenAdd a TPRI.ActiveShape control to the collection.

Parameters:

vobjContainervalue

Container object.  If screen is started from a web page, this will contain a reference to the Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to provide custom startup functionality.

 

Code Block
Expand
titleEvents

The following events are exposed by the TPRI.ActiveShapeArray class.

Code Block
Public Event Click ( _
ByVal securityLevelSender As System.Object, _
ByVal index As Integer _
)

Description:

Secure the screen according to the specified security levelTriggered when the control is clicked.

Parameters:

securityLevel

Security level of the user.  This value is a bitmask of rights provided to the user.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to implement security on individual screens.

 

Code Block
Protected Overridable Sub LinkTo( _
ByVal URL As String _
)

Description:

Navigate the current screen to a new page.

Parameters:

URL

URL of the new page.  Alternatively, passing the string '@MENU' links the screen back to the most recent menu and passing the string '@BACK' links the screen back to the previous page.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the most recent menu page.

Remarks:

Calling this method is equivalent to calling LinkTo("@MENU").

 

Code Block
Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the previous page.

Remarks:

Calling this method is equivalent to calling LinkTo("@BACK")

sender

The source of the event (i.e. the entire collection).

index

The index of the item in the collection that raised the event.

TPRI.CmdButton

Expand
titleOverview

The TPRI.CmdButton object provides a button to link one screen to another.

Image Added
Expand
titleOperation

The TPRI.CmdButton object is primarily configured using the tURL property.  This property specifies the name of the desired screen to which the HMI should be navigated following a click of the button.  Alternatively, tURL can also be set to one of the following predefined strings to provide special navigation functions:

  • "@MENU"
    Link to the most recent menu.

  • "@BACK"
    Link to the previous screen.

 

In actuality, when clicked the TPRI.CmdButton simply calls LinkTo(..) method from the TPRI.BaseScreen class, passing tURL as the method parameter.  As an alternative to using the TPRI.CmdButton object, a developer may instead choose simply to place a regular Windows button on his form, add a click handler to the button, and from that handler call one of the TPRI.BaseScreen screen navigation functions, such as LinkTo(..), LinkToMenu(), or LinkBack().

Expand
titleProperties

The following properties are exposed by the TPRI.CmdButton class.

Property Name

Type

Default Value

Description

tText

 

String

Empty String

Text of button

tTooltip

String

Empty String

Tool tip text of button

tURL

String

Empty String

URL for the linked page.

Expand
titleMethods

There are no public methods exposed by the TPRI.CmdButton class.

Expand
titleEvents

The following events are exposed by the TPRI.BaseScreen CmdButton class.

Code Block
Public Event 
OnLinkTo
Click( _
ByVal
page
 Sender As System.Object, _
ByVal e As 
String
System.EventArgs _
)

Description:

Indicates screen request to navigate to a different pageTriggered when the control is clicked.

Parameters:

pageSender

Name The source of the next page to loadevent.

 

Code Block
Public Event ErrorTerminate()

Description:

Indicates the screen has reached a fatal error and must terminatee

The possible argument of the event.

TPRI.

...

CmdButtonArray

Expand
titleOverview

The TPRI.BaseControl class is the base class from which all TSENTRY screen component controls are derived. It provides various functions in common use throughout the TSENTRY controls.

Expand
titleOperation

The TPRI.BaseControl class should not be used directly on any user page.  It is intended solely for use as a base class for other active objectsCmdButtonArray provides the methods, properties and events to create and access an array of TPRI.CmdButton controls.

Indicates whether or not this is an active
Expand
titleProperties

The following protected properties are exposed by the TPRI.BaseControl CmdButtonArray class.

Property Name
Code Block

Type

Default Value

Description

pMgr

Object

Nothing

Reference to active manager object on parent form.

myIdx

Integer

-1

Index of this object on parent form. This is used to identify this object in calls to methods of active manager object.

bActiveMode

Boolean

True

Default Public ReadOnly Property Item ( _
ByVal index As Integer _
) As TPRI.CmdButton

Description:

Access TPRI.CmdButton controls in the collection by index.

Parameters:

index

Index of the CmdButton object to access.

Return Value:

Indexed CmdButton object.

Expand
titleMethods

The following overridable methods are exposed by the TPRI.BaseControl CmdButtonArray class.

 

Code Block
Public Overridable Sub OnInitialized()

Description:

Indicates that all control properties have been loaded from the screen.

 

Code Block
Public Overridable Function GetActiveVars( _
ByRef varList() As String, _
ByRef tagList() As String _
) As Integer

Description:

Retrieve the variable/tag pairs to be requested from the data host on behalf of the object
Sub Add ( _
ByVal value As TPRI.ActiveShape _
)

Description:

Add a TPRI.CmdButton control to the collection.

Parameters:

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with tags associated with each of the variables in the varList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arrays.

Remarks:

Derived classes that wish to request variables from the host system should override this method to fill in the lists of variables and tags.  The method AddActiveVar(..) should be used to build these lists.

 value

CmdButton object to add to the array.

Expand
titleEvents

The following events are exposed by the TPRI.CmdButtonArray class.

Code Block
Public OverridableEvent FunctionClick UpdActiveVar( _
ByVal tagSender As String, _
ByVal value As System.Object, _
ByVal timestampindex As Date, _
ByVal quality As Integer _
) As Integer

Description:

Update the value of one of the active variables associated with the control.

Parameters:

tag

Tag of updated variable.

value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

If this method is overridden by a derived class, the default implementation of UpdActiveVar(..) should be called to ensure that the OnActiveUpd(..) event below is raised.

 

Code Block
Public Overridable Function GetModifiedVars( _
ByRef tagList() As String, _
ByRef valList() As Object _
) As Integer

Description:

Retrieve list of variables and corresponding values that have been modified and must be written back to the data host.

Parameters:

tagList()

List to be populated with tags to be updated back to data host.

valList()

List to be populated with values associated with each of the tags in the tagList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned tagList() and valList() arrays.

Remarks:

This function is called by the manager to find all variables and values that should be written back to the server.  Any derived control should fill in the passed arrays with the appropriate variable/value pairs, reset any internal data-changed flags, reset its display to indicate that the variables have been sent to the server, and wait for the next update from the server as a confirmation that the updates took place.

 

Code Block
Public Overridable Sub SetDisconnected()

Description:

Set the object into a disconnected state.

Remarks:

This function is provided as a callback to a derived class to reset the display of the object to indicate that it is no longer connected to live data.

 

Description:

Triggered when the control is clicked.

Parameters:

sender

The source of the event (i.e. the entire collection).

index

The index of the item in the collection that raised the event.

TPRI.ToggleButton

Expand
titleOverview

The TPRI.ToggleButton is an on/off switch that connects to a Boolean variable in global common.

Image Added
Expand
titleOperation

The active display of the TPRI.ToggleButton object consists of two main states: on (true, non-zero) and off (false, zero).  The display of each of these states is configured by setting the various object properties.

When the button is pressed, the current value of the associated global common variable is changed to the opposite state. For example, if the variable is currently true, its value is changed to false and vice-versa. The button is then disabled until the new variable value is updated back to the screen. This prevents accidental double clicks of the button from changing the variable back to its original value.

Expand
titleProperties

The following properties are exposed by the TPRI.ToggleButton class.

Property Name

Type

Default Value

Description

tColorDisconnected

 

COLOR

Color.Gray

Color of button when disconnected from the data server.

tColorNonZero

COLOR

Color.Lime

Color of button when variable value is non-zero

tColorTransmitting

COLOR

Color.LightGray

Color of button after it has been clicked but before it has been re-updated with latest value from host

tColorZero

COLOR

Color.Red

Color of button when value is zero

tDataSource

String

Empty string ("")

This is the name of the associated host variable

tIncrement

Integer

0

0 = toggle Boolean value

Non-zero =  amount to add to variable for each button click (can be positive or negative)

tTextNonZero

String

Empty string ("")

Text displayed on button when variable value is non-zero

tTextZero

String

Empty string ("")

Text displayed on button when variable value is zero

tValue

Integer

0

Current value of the toggle button

Protected Sub AddActiveVar( _ ByRef varList() As String, _ ByRef tagList() As String, _ ByRef count As Integer, _ ByRef var As String, _ ByRef tag As Stringfunction is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next update.

 

Expand
titleMethods

The following public methods are exposed by the TPRI.BaseControl class.

 

Code Block
Public Function IsInitialized() As Boolean

Description:

Indicates whether or not all control properties have been loaded from data stored in screen initialization.

Return Value:

Flag indicating whether or not all control properties have been loaded from data stored in screen initializationToggleButton class.

 

Code Block
Public Function InitActiveVars( _
ByRef pManager As Object, _
ByRef iTscIdx As Integer, _
ByRef varList(tValueReset() As String, _
ByRef tagList() As String _
) As Integer

Description:

Initialize the BaseControl object and retrieve all variables and tags that are to be requested from the server on behalf Reset the display of the object .

Parameters:

pManager

Reference to manager (typically TPRI.OpcMgr) object on parent form.

iTscIdx

Index of this BaseControl object on parent form.  This value is later used to identify this control in calls to various manager methods.

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with fully tags to be associated with each of the variables in the varList() arrayto indicate that the button has not been clicked.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arraysvalue originally contained in the object.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

Code Block
Code Block
Public Function isClicked() As Boolean

Description:

Indicate whether or not the button is currently clicked.

Return Value:

The current click state.

Expand
titleEvents
Expand
titleProperies

The following events are exposed by the TPRI.ToggleButton class.

Code Block
Public Event Click( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Add the specified variable name and tag to the supplied lists and increment the total countTriggered when the control is clicked.

Parameters:

varList()

Array to which the variable name should be added.

tagList()

Array to which the variable tag should be added.

count

Total count of variable name/tag pairs in the above lists.

var

Name of variable to add to the list.

tag

Variable tag to add to the list.

Remarks:

Derived classes that wish to request variables from the host system should use this method to add variable/tag pairs to the supplied lists.

Code Block
Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As String _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

String containing type of control to search for.  If type = "*", search all types.

Return Value:

The index of the control in the collection, or -1 if not found.

 

Code Block
Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As Type _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

Type of control to search for.

Return Value:

The index of the control in the collection, or -1 if not found.

Expand
titleEvents

The following events are exposed by the TPRI.BaseControl class.

Code Block
Public Event OnActiveUpd( _
ByVal Sender As Object, _
ByVal tag As String _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

TPRI.TextBox

Expand
titleOverview

The TPRI.TextBox is used for live display and input of a scalar variable in global common.

Image Removed
Expand
titleOperation

The TPRI.TextBox control can operate in two modes: display-only mode and input mode.  In display-only mode, the value is continually updated as the value in global common changes, but the user is locked out from modifying the displayed value.  

In input mode, the text box is unlocked to allow the user to modify the displayed value.  Once the user starts to type in a new value, the background color of the display changes color and the active update of the value is put on hold to allow the user to finish changing the value.  Note that this new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when leaving the control or the Enter button is pressed.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Below are all of the properties of the TPRI.TextBox Sender

The source of the event.

e

The possible argument of the event.

 

Code Block
Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

TPRI.BarGraph

Expand
titleOverview

The TPRI.BarGraph is used as a live graphical display of up to two parallel array variables in global common. The arrays are displayed as a set of bars growing up or down from a centerline. For instance, this object is commonly used to display a feedback stress array for flatness control in metal rolling.

Image AddedImage Added
Expand
titleOperation

In general, the bar graph is configured according to the following.  

Number of bars

The horizontal extent of the display is divided into N bar slots, where N is equal to the tNumBars property.  Each of the bar slots is divided into a left and right bar; when active, the heights of each of the left bars correspond to the values in the first (right) array, while the heights of each of the right bars correspond to the values in the second (left) array.

Alternatively, the tNumBars property can be set to the name of a variable in global common.  In this case, the bar graph will retrieve the value of this variable and use it to configure the number of bars displayed.  

Horizontal display configuration

Both sets of bars can be configured to take up some fraction of each bar slot.  The property tLeftBarPercent specifies the percentage of each bar slot that the left bar should consume; the left bar is always assumed to start at the leftmost edge of the bar slot.  The property tRightBarPercent specifies the percentage of the bar slot that the right bar should consume; however, the starting point of the right bar is specified with the tRightBarOffset property.  If the sum of tRightBarOffset and tRightBarPercent exceeds 100, the right bar will be truncated as the rightmost edge of the bar slot.

Vertical display configuration

The displayed heights of each bar are specified relative to three TPRI.BarGraph properties.  The tEngUnitCenterLine property specifies the engineering units of the horizontal centerline of the graph.  This is line from which each of the bars will grow up or down.  If the array element value associated with a given bar is less than tEngUnitCenterLine, the bar will be drawn down from the centerline, and conversely, if the value associated with a bar is higher than tEngUnitCenterLine, the bar will be drawn up from the centerline.  This allows the bar graph to be configured to display deviations from a nominal non-zero value.  The top and bottom vertical limits of the graph are specified by the tEngUnitTop and tEndUnitBottom properties; array element values outside this range will display bars extending to the limits of the display.

If forcing any of these three properties to a fixed value is not appropriate for the display, there are two alternatives.  First, the property can be set to the name of a variable in global common whose value will be retrieved at runtime and used as the associate engineering value.  This allows the display to be programmatically controlled by values in global common.  Second, the property can be set to a special string consisting of an ampersand '@' followed by the name of a text box on the screen; in this case the value entered into the text box will be used as the associate engineering value.  This allows the HMI user to configure the display at runtime as he pleases.

Scale display configuration

The property YTickSpacing is defined as the spacing (in engineering units) between the y-axis ticks annotating the graph.  A tick is a short horizontal line drawn to the left of the graph together with a label indicating the corresponding y-axis position.  A property YTickSpacing value less than or equal to zero indicates that no ticks should be drawn.  A positive value indicates that ticks and labels should be drawn at integer multiples of the spacing value between the lower and upper limits of the graph.  The default value is zero.

Expand
titleProperties

The following properties are exposed by the TPRI.BarGraph object.

tBackReadOnlyColor

Property Name

Type

Default Value

Description

tAutoValidateMinMax

Boolean

False

Indicates whether or not the text box should try to validate user-entered data against the min/max values specified in the data dictionary

Font

Font

MS Sans Serif, Regular, 12

Font for Bar Numbers.

Recommended font is “small fonts” about size 7

tBackColor

COLOR

Color.

White

Black

Background color of read-only text box

tBackWriteDisplayColor

COLOR

Color.Khaki

Background color of editable text box while in display mode

tBackWriteEditColor

The color of the background of the graph control.

tBarNumbersStyle

 

Integer

2

Option for bar number shown directly below bars.

0 - don't show numbers

1 - show numbers from 0 to (N- number of bars) For example: 0 to 30 for 31 bars

2 - show numbers from 1 to (number of) bars.  For example: 1 to 31 for 31 bars

tBorderColor

COLOR

Color.

SandyBrown

White

Background color of editable text box while in edit mode

tChanged

The color for the enclosing border box

tBorderVisible

Boolean

False

Determines if user has edited the text box

tDataSource

String

Empty string ("")

This is the name of the host variable

tDisconnectedStr

String

"###"

Text in textbox when disconnected from the OPC server. May not be used if tDataSource = ""

tEnabled

Boolean

True

Enables the textbox on the screen

tFocusColor

COLOR

Color.Lime

Sets the color to outline the textbox when it is in focus

tFormat

True

Option for displaying the enclosing border box

tBottomLineVisible

Boolean

False

Option for displaying the line above the Box Numbers (like X-axis)

tCenterLineVisible

Boolean

False

Option for displaying the Center line

tEngUnitBottom

Integer

-9999

Value at the bottom of the bar graph area in engineering units

tEngUnitCenterLine

Integer

-9999

Reference value: where the bars in the bar graph will ‘grow’ from.

tEngUnitTop

Integer

-9999

Value at the top of the bar graph area in engineering units

tForeColor

COLOR

Color.White

The color for Bar Numbers, BottomLine and CenterLine

tLeftBarDataSource

String

Empty string ("")

Formats how the text is displayed

tLocked

Boolean

False

Toggles between display  and edit mode

tResetStr

String

"@@@"

String to be displayed when waiting for an update from OPC server

tResetToStr

Boolean

True

Determines whether to display the tResetStr string when waiting for an update

tText

This is the name of the host variable to be graphed.

tLeftBarPercent

Integer

50

Percentage of the allotted space per line to take up

tLeftFillColor

COLOR

Color.Red

Color of the major graph (set of bars)

tNumBars

Integer

2

Number of bars that are to be graphed

tRightBarDataSource

String

Empty string ("")

Text displayed in textbox

tToolTipText

String

Empty string ("")

Tooltip text for textbox

AutoSubmit

Boolean

False

Automatically submit changes to the host when leaving the control or the Enter button is pressed if the flag is set to True

This is the name of the host variable to be graphed.

tRightBarOffset

Integer

50

Amount that the left hand edge of the minor bars is to be shifted to the right

   tRightBarPercent

Integer

50

Percentage of the allotted space per line to take up

tRightFillColor

COLOR

Color.Yellow

Color of the minor graph

   YTickSpacing

Single

0

Indicates the ticks and labels should be shown at integer multiples of the spacing value between the lower and upper limits of the graph.

Expand
titleMethods

The following events methods are exposed by the TPRI.TextBox BarGraph class.

 

Code Block
Public Function
tTextReset() As String
 fSetVals( _
ByRef afValue As Object _
) As Object

Description:

If unlocked (tLocked = False), reset the display of the object to indicate that the value has not been modified.  If tResetToStr = True, reset the text displayed to the tResetStr string as well.

Return Value:

The string originally contained in the object.

Remarks:

This function is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next updateSet new values for all left and right bars (same value for left and right).

Parameters:

afValue

Tag of updated variable.

Return Value:

Zero for success; non-zero for failure.

Expand
titleEvents

The following events are exposed by the TPRI.TextBox BarGraph class.

 

Code Block
Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

TPRI.

...

CoverageBar

Expand
titleOverview

The A TPRI.Shape CoverageBar control is used as a basic shape control (similar to the Shape control in VB6).  

Image Removed
Expand
titleOperation

The Shape object allows the designer to create the visual shape controls on the screens. It is a basic shape control without the specific logic ties to any other controls. It can be used as a base control to create the specific type of shape control.

The Shape control is configured by modifying the Shape, BorderOption, and FillOption properties.  Shape property provides the outline (shape) of the control. The BorderOption property provides the options of shape control border (width, color...). The FillOption property provides the options of shape control fill (color, style...)

...

titleProperties

Below are all of the properties of the TPRI.Shape object.

...

Property Name

...

Type

...

Default Value

...

Description

...

BorderOptions.Color

...

COLOR

...

Color.Black

 

...

Color of the border of the shape.  This is only used if the border Width > 0.

...

BorderOptions.

DashStyle

...

Drawing2D.DashStyle

Solid

Dash

Dot

DashDot

DashDotDot

Custom

...

Solid

...

Style of the border of the shape.  This is only used if the border Width > 0.

 

...

BorderOptions.Width

...

Integer

...

1

...

Width of the border of the shape.

...

BorderOptions.

GradientOn

...

Boolean

...

False

...

Specifies if the border should be painted as a gradient from one color to another.

...

BorderOptions.

GradientStyle

...

     Drawing2D.

LinearGradientMode

 

BackwardDiagonal

ForfardDiagonal

Horizontal

Vertical

...

Horizontal

...

Specifies the style of the gradient border.  This is only used if GradientOn = True.

...

BorderOptions.

GradientStartColor

...

COLOR

...

Empty

...

Gradient border start color.  This is only used if GradientOn = True.

...

BorderOption.

GradientEndColor

...

COLOR

...

Empty

...

Gradient border end color.  This is only used if GradientOn = True.

...

FillOptions.SolidColor

...

COLOR

...

Color.Transparent

...

Solid fill color of the shape.  This is only used if the FillStyle = Solid.

...

FillOptions.FillStyle

...

FillStyleConstants

0 - Solid

1 - Hatch

2 - Gradient

...

0

...

Fill style for the shape.

...

FillOptions.HatchColor

...

COLOR

...

Color.Black

...

Hatch color of the shape.  This is only used if FillStyle = Hatch.

...

FillOptions.HatchStyle

...

Drawing2D.HatchStyle

 

BackwardDiagonal

Cross

ZigZag

...

BackwardDiagonal

...

Hatch style of the shape.  This is only used if FillStyle = Hatch.

...

FillOptions. GradientStyle

...

Drawing2D.

LinearGradientMode

 

BackwardDiagonal

ForfardDiagonal

Horizontal

Vertical

...

Horizontal

...

Gradient style of the shape.  This is only used if FillStyle = Gradient.

...

FillOptions. GradientStartColor

...

COLOR

...

Empty

...

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

...

FillOptions. GradientEndColor

...

COLOR

...

Empty

...

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

Expand
titleMethods

There are no public methods exposed by the TPRI.Shape class.

Expand
titleEvents

There are no public events exposed by the TPRI.Shape class.

TPRI.ActiveShape

Expand
titleOverview

The TPRI.ActiveShape is used to provide a graphical indication of the current value of a variable in global common.  

Image Removed
Expand
titleOperation

The TPRI.ActiveShape object allows the designer to divide the real number line into multiple ranges and assign a different shape and color for each range.  As the variable value is automatically updated to the control, the appropriate shape and color is displayed based on the range into which the current value falls.

  • For example, the ActiveShape control can be used to display the current speed of a rolling mill.  If the speed is less than 10 feet per minute, the shape will display a red square with the text Stopped.  If the speed is greater than 10 feet per minute but less than 300 feet per minute, the display is a light blue square with the text Creep.  If the speed is greater than 300 feet per minute the display will be a green circle with the text Run.  Alternatively, the ActiveShape can be configured to display the current value of the speed variable rather than the text descriptions above.

If the current value of the variable is not actively being updated by the server, the ActiveShape will take on a separate display configuration to indicate that there is a communications problem.

The ActiveShape control is configured by modifying the ActiveShapeSetup property.  This property is actually an array of ActiveShapeSetup class objects, where each ActiveShapeSetup class contains all of the properties required to describe the display configuration for a range along the real number line.  

  • Following the mill speed example above, there would be three ActiveShapeSetup objects in this array: one indicating the configuration when the speed variable is less than 10, one for when the speed is greater than 10 but less than 300, and a third for when the speed is greater than 300.

Each ActiveShapeSetup object has a property BoundMax, which defines the maximum value of the range.  The minimum value of the particular range is implied by the maximum value of the previous ActiveShapeSetup object in the array; hence the ranges of the real number line are defined in ascending order with each additional ActiveShapeSetup object in the array.  The two exceptions are the first and last ActiveShapeSetup objects in the array.  First, the minimum value of the range defined by the ActiveShapeSetup(0) object in the array (since there is no ActiveShapeSetup(-1) object in the array) is assumed to be negative infinity.  Second, the BoundMax property of the last ActiveShapeSetup object in the array is ignored and taken to be positive infinity.

Following would be the bounds defined for the speed example given above:

Code Block
ActiveShapeSetup(0) BoundMax = 10
ActiveShapeSetup(1) BoundMax = 300
ActiveShapeSetup(2) BoundMax = 99999 (this is assumed to be +∞)

The remaining properties of the ActiveShape class are as follows:

Used to lock the control to prevent updates until the control is unlocked

a horizontal bar illustrating the location of a closed section within a wider region.  Typically a TPRI.CoverageBar is tacked on below a bar graph to depict which bars are to be considered ‘valid’.  For example, the CoverageBar may be used on a rolling mill to indicate which zones of a flatness bar display are covered by the strip itself.

Image Added
Expand
titleProperties

The ActiveShapeSetup object contains the following properties for configuring the display for a given range.  Note that the display configuration while disconnected (specified by the ActiveShape property DisconnectSetup) is also an ActiveShapeSetup object, so any of these properties can be modified to effect the display when communications are off-line.

Property Name

Type

Default Value

Description

BorderOptions.Color

COLOR

Color.Black

Color of the border of the shape.  This is only used if the border Width > 0.

BorderOptions.

DashStyle

Drawing2D.DashStyle

Solid

Style of the border of the shape.  This is only used if the border Width > 0.

BorderOptions.Width

Integer

1

Width of the border of the shape.

BorderOptions.

GradientOn

Boolean

False

Specifies if the border should be painted as a gradient from one color to another.

BorderOptions.

GradientStyle

Drawing2D. LinearGradientMode

Horizontal

Specifies the style of the gradient border.  This is only used if GradientOn = True.

BorderOptions.

GradientStartColor

COLOR

Empty

Gradient border start color.  This is only used if GradientOn = True.

BorderOption.

GradientEndColor

COLOR

Empty

Gradient border end color.  This is only used if GradientOn = True.

FillOptions.SolidColor

COLOR

Color.Transparent

Solid fill color of the shape.  This is only used if the FillStyle = Solid.

FillOptions.FillStyle

FillStyleConstants

0 - Solid

1 - Hatch

2 - Gradient

0

Fill style for the shape.

FillOptions.HatchColor

COLOR

Color.Black

Hatch color of the shape.  This is only used if FillStyle = Hatch.

FillOptions.HatchStyle

Drawing2D.HatchStyle

BackwardDiagonal

Hatch style of the shape.  This is only used if FillStyle = Hatch.

FillOptions. GradientStyle

Drawing2D.

LinearGradientMode

Horizontal

Gradient style of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientStartColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

FillOptions. GradientEndColor

COLOR

Empty

Gradient start color of the shape.  This is only used if FillStyle = Gradient.

Font

Font

MS Sans Serif/ Bold/ Size=12

Provides the font for any text shown inside the ActiveShape control.   The text will be centered.  If the font is changed, the height of the label area increases.

Shape

ShapeConstants

0 - Rectangle

1 - Square

2 - Oval

3 - Circle

Rectangle

Specifies the shape displayed.

 

Text

String

Text

Specifies the text to be display.

TextColor

COLOR

Color.Black

ForeColor for the text

TextBlinking

Boolean

False

Indicates if the displayed text should blink.  This is only used if ShapeBlinking = False and BlinkingPeriod > 0.

ShapeBlinking

Boolean

False

Indicates if the entire shape should blink.  This is only used if BlinkingPeriod > 0.

BlinkingPeriod

Integer

0

The blinking frequency (the number of milliseconds between the changes) if either TextBlinking or ShapeBlinking are True.

BoundMax

Integer

0

Maximum value for this range.

BoundIncludeEquals

Boolean

False

Specifies whether or not BoundMax is inclusive.  If True, then values <= BoundMax will fall into this range; otherwise only values < BoundMax will fall into this range.

ValueDisplay

Boolean

False

If the property is set to True, then the text label of the ActiveShape will show the variable value instead of showing Text.

ValueFormat

String

Empty string ("")

Formatting string for the display of the current variable value if ValueDisplay = True.

Property Name

Type

Default Value

Description

BackColor

COLOR

Color.Red

Provides the "default" color for the shape (in the case that none of the bound conditions is true).

ActiveShapeSetup()

ActiveShapeSetup

 

Display setup for various ranges.

DisconnectSetup

ActiveShapeSetup

 

Display setup when not connection.

tNumTextLines

Short ( >=1 and < 4)

1

Determines (with the font.size) the height of the ActiveShape label.  Cannot be changed if the shape property is oval or circle.

tDataSource

String

Empty string ("")

This is the name of the host variable

tURL

String

Empty string ("")

Assigns a target web page to go to when object is clicked

tValue

Single

0

This property is responsible for the current presentation of the Active Shape

tLocked

Boolean

False

Expand
titleOperation

At run-time, the TPRI.Coverage bar is a display-only object representing a contiguous range of values on the real number line.  The left and right edges of the horizontal bar represent the lower (or most negative) and the upper (or most positive) limits of this range.  Within this displayed range there is assumed to be a single range of values that are to be considered valid; these values are drawn in a different color to visually indicate the span of values that is valid.  In the image above, this valid range is drawn in blue, while the total displayed range is drawn in gray.

At design time, each of the four limits of the two ranges (left and right limits of displayed range, left and right limits of valid range) is set as a property of the object and can be specified in one of three ways.  First, the property can be hard-coded to the actual numeric value.  Second, the property can be set to the name of a variable on the host system that contains this value; at run-time this value will be actively retrieved and updated from the server.  Third, the property can be set to the name of a TPRI.TextBox object elsewhere on the screen prepended with an ampersand ('@') character that contains the specified value; this allows the HMI user to configure the display himself at run-time.

Expand
titleProperties

The following properties are exposed by the TPRI.CoverageBar class.

Property Name

Type

Default Value

Description

tColorData

COLOR

Color.Blue

Fore color of graph

tColorNoData

COLOR

Color.Gray

Back color of graph

tLeftData

String

"-9999"

Value of the left edge of the valid data.  This can also be set to the name of a host variable containing this value or to the name of a TPRI.TextBox object containing this value prepended with an '@' character.

tLeftEdge

String

"-9999"

Value of the left edge of the displayed data.  This can also be set to the name of a host variable containing this value or to the name of a TPRI.TextBox object containing this value prepended with an '@' character.

tRightData

String

"-9999"

Value of the right edge of the valid data.  This can also be set to the name of a host variable containing this value or to the name of a TPRI.TextBox object containing this value prepended with an '@' character.

tRightEdge

String

“-9999”

Value of the right edge of the displayed data.  This can also be set to the name of a host variable containing this value or to the name of a TPRI.TextBox object containing this value prepended with an '@' character.

Expand
titleMethods

The following public methods are exposed by the TPRI.CoverageBar class.

 

Code Block
Public Sub SetLeftData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the covered section.

Parameters:

afValue

Value to be associated with the left side of the covered section.

 

Code Block
Public Sub SetLeftEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the entire bar.

Parameters:

afValue

Value to be associated with the left side of the entire bar.

 

Code Block
Public Sub SetRightData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right side of the covered section.

Parameters:

afValue

Value to be associated with the right side of the covered section.

 

Code Block
Public Sub SetRightEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right edge of the entire bar.

Parameters:

afValue

Value to be associated with the right edge of the entire bar.

Expand
titleEvents

There are no events exposed by the TPRI.CoverageBar class.

TPRI.LogMsg

Expand
titleOverview

The TPRI.LogMsg object actively displays all messages that are logged to a TSENTRY log message queue.  For instance, the bottom half of the NtRtMgr screen uses this object to display messages from the default ‘LogMsg’ queue.

Image Added
Expand
titleOperation

Active operation of the TPRI.LogMsg object is fully automated by the screen framework provided that the user screen is derived from the TPRI.BaseScreen class and that it contains a TPRI.OpcMgr object.  

Configuration of a TPRI.LogMsg control consists mainly of setting the desired LogMsg queue name in the LogMsgName property.  This string must match one of the LogMsg queues defined in the system logs initialization file .  Once configured, the TPRI.LogMsg object will display all messages logged to the specified queue.

Expand
titleProperties

Below is a list of all the properties that are exposed by the TPRI.LogMsg class.

Property Name

Type

Default Value

Description

LogMsgName

String

"LogMsg"

Name of desired queue from which to retrieve messages.

histStart

Long

32

This number indicates how many historical messages to retrieve upon startup before waiting for new messages to be queued.

histLength

Long

512

This is the maximum number of messages to store in the list box at any given time.  Additional messages will cause the oldest entries to drop out of the top of the message box.

Expand
titleMethods

There are no public methods exposed by the TPRI.LogMsg class.

Expand
titleEvents

There are no public events exposed by the TPRI.LogMsg class.

TPRI.ComboBox

Expand
titleOverview

The TPRI.ComboBox is used as a live display and input of global common variables that are defined only to have a finite set of allowable values.  

Image Added
Expand
titleOperation

The TPRI.ComboBox is similar to the TPRI.TextBox in that it displays the current value of a variable in global common and operates in two possible modes, read-only mode and input mode.  However, whereas the TextBox is a text-entry box that allows the user to enter any new value, the ComboBox is a drop down list that allows the user only to select a new value from the presented list of choices.  Moreover, since many times the HMI user does not think of the list of choices in terms of numerical values but instead in conceptual possibilities, the ComboBox allows the designer to associate a text string with each of the possible variable values; these strings can be displayed at run-time instead of the actual values themselves.

For example, suppose there is a variable in global common representing the current mode of a controller: automatic, manual, or off.  The variable itself is an integer, and is defined such that automatic = 2, manual = 1, and off = 0.  The TPRI.ComboBox object therefore limits the user choices in the drop down box to ‘Auto’, ‘Manual’, or ‘Off’, though it internally manages updating the variable value on the host to a 2, 1, or 0, respectively.

When the TPRI.ComboBox object is initially connected to the host, it displays the descriptive string associated with the current value of the variable in global common.  If this value is changed by some other process, the display will be updated accordingly to display the new descriptive string.  If the user makes a new selection from the drop down list, however, the background color of the display changes color and the active update of the value is put on hold while the user finalizes his selection.  The new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

In the case where the current value of the variable on the host is not in the list of available values defined in the TPRI.ComboBox object, the object will display “{XXX}” where XXX is the current value of the variable.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when a new item is selected from the list.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Expand
titleProperties

Below are all of the properties of the TPRI.ComboBox object.

Property Name

Type

Default Value

Description

tAutoValidateMinMax

Boolean

False

Indicates whether or not the text box should try to validate user-entered data against the min/max values specified in the data dictionary.

tBackReadOnlyColor

Color

Color.White

Background color of read-only text box.

tBackWriteDisplayColor

Color

Color.Khaki

Background color of editable text box while in display mode.

tBackWriteEditColor

Color

Color.SandyBrown

Background color of editable text box while in edit mode.

tChanged

Boolean

False

Determines if user has edited the text box.

tDataSource

String

Empty string ("")

This is the name of the host variable.

tDisconnectedStr

String

"###"

Text in text box when disconnected from the OPC server.

tEnabled

Boolean

True

Enables the text box on the screen.

tFocusColor

Color

Color.Lime

Sets the color to outline the text box when it is in focus.

tFormat

String

Empty string ("")

Formats how the text is displayed.

tLocked

Boolean

False

Toggles between display  and edit mode.

tResetStr

String

"@@@"

String to be displayed when waiting for an update from OPC server.

tResetToStr

Boolean

True

Determines whether to display the tResetStr string when waiting for an update.

tText

String

Empty string ("")

Text displayed in text box.

tToolTipText

String

Empty string ("")

Tooltip text for text box.

tValueList

String

Empty string ("")

Each item is separated by delimiter “|”. The index and value of each item is separated by delimiter “,”. Example:

1, Yes | 2, No | 3, Very Good.

AutoSubmit

Boolean

False

Automatically submit changes to the host when a new item is selected from the list if the flag is set to True.

Expand
titleMethods

The following public methods are exposed by the TPRI.ActiveShapeArray ComboBox class.

Expand
titleEvents
Expand
titleOverview

The following events are exposed by the TPRI.ActiveShape class.

 

Code Block
Public EventFunction Click ConvertStrToNum( _
ByVal SenderStrText As System.Object,String _
ByVal e) As System.EventArgs _
)String

Description:

Triggered when the control is clickedRetrieve the value associated with the specified descriptive string.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

TPRI.ActiveShapeArray

The TPRI.ActiveShapeArray provides the methods, properties and events to create and access an array of TPRI.ActiveShape controls.

StrText

Descriptive string.

Return Value:

Variable value associated with the descriptive string.

 

Code Block
Public Function ConvertNumToStr( _
ByVal StrNum As String _
) As String

Description:

Retrieve the descriptive string associated with the specified variable value.

Parameters:

StrNum

Variable value.

Return Value:

Descriptive string associated with the passed value.

Expand
titlePropertiesEvents

The following properties events are exposed by the TPRI.ActiveShapeArray ComboBox class.

 

Code Block
Default Public ReadOnly Property Item Event Change( _
ByVal indexSender As IntegerSystem.Object, _
)ByVal e As TPRI.ActiveShapeSystem.EventArgs _
)

Description:

Access TPRI.ActiveShape controls in the collection by indexIndicates the selected value has been changed.

Parameters:

indexSender

Index The source of the ActiveShape object to accessevent.

Return Value:

Indexed ActiveShape object.

Expand

The following methods are exposed by the TPRI.ActiveShapeArray class.e

Event argument.  This will always be nothing.

 

Code Block
Public SubEvent Add OnValidate( _
ByVal valueSender As TPRI.ActiveShapeSystem.Object, _
ByRef Cancel As Boolean _
)

Description:

Add a TPRI.ActiveShape control to the collection.

Parameters:

value

ActiveShape object to add to the array.

Expand
titleEvents

The following events are exposed by the TPRI.ActiveShapeArray class.

The current selection is being validated.

Parameters:

Sender

The source of the event.

Cancel

Flag indicating whether or not the selection is valid.

Remarks:

This event will be raised when the current selection must be validated.  The event handler should set the Cancel parameter according to whether or not the current selection is valid.

 

Code Block
Public Event Click ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal indexe As IntegerSystem.EventArgs _
)

Description:

Triggered when The event is raised when a serious error has occurred in the control is clicked.

Parameters:

senderSender

The source of the event (i.

e. the entire collection).

index

The index of the item in the collection that raised the event

Event argument. This will always be nothing.

TPRI.

...

OpcMgr

Expand
titleOverview

The TPRI.CmdButton object provides a button to link one screen to another.

Image Removed

OpcMgr object is responsible for automating all active variables on a screen.  On initialization it searches for any objects on the screen that are derived from TPRI.BaseControl and requests from each of them a list of variables that should be retrieved from the host system.  Then as these variables are updated from the server to the client, the OpcMgr object passes these updates back to each of the associated BaseControl objects.

Image Added

The following properties are exposed by the TPRI.ToggleButton class.

[TABLE]

The following properties are exposed by the TPRI.CmdButton class.

Expand
titleOperation
Expand
titleProperties
Expand
titleMethods

The In most cases, all operation of the TPRI.CmdButton OpcMgr object is primarily configured using the tURL property.  This property specifies the name of the desired screen to which the HMI should be navigated following a click of the button.  Alternatively, tURL can also be set to one of the following predefined strings to provide special navigation functions:

  • "@MENU"
    Link to the most recent menu.

  • "@BACK"
    Link to the previous screen.

 

In actuality, when clicked the TPRI.CmdButton simply calls LinkTo(..) method from the TPRI.BaseScreen class, passing tURL as the method parameter.  As an alternative to using the TPRI.CmdButton object, a developer may instead choose simply to place a regular Windows button on his form, add a click handler to the button, and from that handler call one of the TPRI.BaseScreen screen navigation functions, such as LinkTo(..), LinkToMenu(), or LinkBack().

Expand
titleProperties

Property Name

Type

Default Value

Description

tText

 

String

Empty String

Text of button

tTooltip

String

Empty String

Tool tip text of button

tURL

String

Empty String

URL for the linked page.

Expand
titleMethods

There are no public methods exposed by the TPRI.CmdButton class.

Expand
titleEvents

The following events are exposed by the TPRI.CmdButton class.

Code Block
Public Event Click( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

TPRI.CmdButtonArray

Expand
titleOverview

The TPRI.CmdButtonArray provides the methods, properties and events to create and access an array of TPRI.CmdButton controls.

Expand
titleProperties

The following properties are exposed by the TPRI.CmdButtonArray class.

Code Block
Default Public ReadOnly Property Item ( _
ByVal index As Integer _
) As TPRI.CmdButton

Description:

Access TPRI.CmdButton controls in the collection by index.

Parameters:

index

Index of the CmdButton object to access.

Return Value:

Indexed CmdButton object.

Expand
titleMethods

The following methods are exposed by the TPRI.CmdButtonArray class.

Code Block
Public Sub Add ( _
ByVal value As TPRI.ActiveShape _
)

Description:

Add a TPRI.CmdButton control to the collection.

Parameters:

value

CmdButton object to add to the array.

Expand
titleEvents

The following events are exposed by the TPRI.CmdButtonArray class.

Code Block
Public Event Click ( _
ByVal Sender As System.Object, _
ByVal index As Integer _
)

Description:

Triggered when the control is clicked.

Parameters:

sender

The source of the event (i.e. the entire collection).

index

The index of the item in the collection that raised the event.

TPRI.ToggleButton

Expand
titleOverview

The TPRI.ToggleButton is an on/off switch that connects to a Boolean variable in global common.

[PICTURE]

Expand
titleOperation

The active display of the TPRI.ToggleButton object consists of two main states: on (true, non-zero) and off (false, zero).  The display of each of these states is configured by setting the various object properties.

When the button is pressed, the current value of the associated global common variable is changed to the opposite state. For example, if the variable is currently true, its value is changed to false and vice-versa. The button is then disabled until the new variable value is updated back to the screen. This prevents accidental double clicks of the button from changing the variable back to its original value.

The following public methods are exposed by the TPRI.ToggleButton class.fully automated by the TPRI.BaseScreen framework. While connected to the data host, the OpcMgr object will display green and indicate the date/time of the most recent variable update from the host.  Before the initial connection and any time the OpcMgr object disconnects from the host, the display will turn orange and will indicate the date/time of the most recent connection attempt; the OpcMgr object should attempt to reconnect every 3-5 seconds.  Finally, there are two cases in which the OpcMgr object will turn red:

If the OpcMgr object is unable to find any variables configured on the screen for retrieval from the server, the object will turn red and display a message indicating that there are no OPC items configured.

If the OpcMgr object encounters an unrecoverable error the object will turn red and display an error indication.  Details of the error can be viewed by holding down the control key and left clicking on the object.

 

There are some situations where a screen may want to receive variable updates for data that it wishes to use for its own purposes rather than for display in one of the existing active objects.  To accomplish this, the screen should do the following:

Add an event handler for OnRestart(..).  Inside this handler make appropriate calls to the AutoAddItem() method to add all variables that the screen would like to receive directly.

Add an event handler for OnDataUpdate(..).  Inside this handler process individual variable updates.

Optionally add an event handler for OnDisconnect(..).  Place any code to reset the visual display of the screen to indicate that the screen is not connected to the data host.

Expand
titleProperties

The following public properties are exposed by the TPRI.OpcMgr object.

Property Name

Type

Default Value

Description

tAutoStart

Boolean

True

True if the operation of the object should be automatically started by the TPRI.BaseScreen parent; if false, then the StartComm(..) method must be manually called by the screen.

tFwdDataUpdates

Boolean

False

If true, all variable updates will raise the event OnDataUpdate(..); if false, only those variable updates that are not otherwise handled by other controls will raise the OnDataUpdate(..) event.

defServerName

String

GsmOpcSvr

Default server name for variable requests.

Expand
titleMethods

The following methods are exposed by the TPRI.OpcMgr object.

 

Code Block
Public Function StartComm( _
ByRef hostName As String _
) As Integer

Description:

Start communications with a host.

Parameters:

hostName

Name or IP address of the data host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

By default, the TPRI.BaseScreen implementation looks for all TPRI.TrendCom objects and calls this method to automatically initialize trending.  This is disabled if the tAutoStart property is set to False.

 

Code Block
Public Function AutoAddItem( _
ByRef fullItemName As String, _
ByRef tagName As String _
) As Integer

Description:

Add a variable to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function tValueReset(WriteItem( _
ByRef tagName As String, _
ByRef value As Object _
) As Integer

Description:

Reset the display of the object to indicate that the button has not been clickedWrite a value back to the specified variable on the host.

Parameters:

tagName

Tag of variable to be written.

value

New value of variable.

Return Value:

The value originally contained in the object.

Remarks:

This function is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next updateZero for success; non-zero for failure.

 

Public Function WriteModified( _

) As Integer

Description:

Find and write all modified variables on the screen back to the host.

Return Value:

Zero if no error, nonzero if error.

 

Code Block
Public Function isClicked(RemoveItem( _
ByRef tagName As String _
) As BooleanInteger

Description:

Indicate whether or not the button is currently clickedRemove an existing variable from the list of variables retrieved from the host.

Parameters:

tagName

Tag of variable to be written.

Return Value:

The current click state.

Expand
titleEvents

The following events are exposed by the TPRI.ToggleButton class.Zero for success; non-zero for failure.

 

Code Block
Public 
Event
Function 
Click
RefreshAll( _
ByVal
) 
Sender
As 
System.Object, _ ByVal e As System.EventArgs _ )
Integer

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the eventRequest the server to refresh all data values back to the client.

Return Value:

Zero for success; non-zero for failure.

 

 

The following methods should not be called from an application screen.  They are used by other active controls to configure variables associated only with those controls.

 

Code Block
Public EventFunction ErrorTerminateAutoAddTscItem( _
ByVal SenderByRef fullItemName As String, _
ByRef tscIdx As System.ObjectInteger, _
ByValByRef etag As System.EventArgsString _
) As Integer

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

TPRI.BarGraph

Expand
titleOverview

The TPRI.BarGraph is used as a live graphical display of up to two parallel array variables in global common.  The arrays are displayed as a set of bars growing up or down from a centerline.  For instance, this object is commonly used to display a feedback stress array for flatness control in metal rolling.

[PICTURE]

[PICTURE]

Expand
titleOperation

In general, the bar graph is configured according to the following.  

Number of bars

The horizontal extent of the display is divided into N bar slots, where N is equal to the tNumBars property.  Each of the bar slots is divided into a left and right bar; when active, the heights of each of the left bars correspond to the values in the first (right) array, while the heights of each of the right bars correspond to the values in the second (left) array.

Alternatively, the tNumBars property can be set to the name of a variable in global common.  In this case, the bar graph will retrieve the value of this variable and use it to configure the number of bars displayed.  

Horizontal display configuration

Both sets of bars can be configured to take up some fraction of each bar slot.  The property tLeftBarPercent specifies the percentage of each bar slot that the left bar should consume; the left bar is always assumed to start at the leftmost edge of the bar slot.  The property tRightBarPercent specifies the percentage of the bar slot that the right bar should consume; however, the starting point of the right bar is specified with the tRightBarOffset property.  If the sum of tRightBarOffset and tRightBarPercent exceeds 100, the right bar will be truncated as the rightmost edge of the bar slot.

Vertical display configuration

The displayed heights of each bar are specified relative to three TPRI.BarGraph properties.  The tEngUnitCenterLine property specifies the engineering units of the horizontal centerline of the graph.  This is line from which each of the bars will grow up or down.  If the array element value associated with a given bar is less than tEngUnitCenterLine, the bar will be drawn down from the centerline, and conversely, if the value associated with a bar is higher than tEngUnitCenterLine, the bar will be drawn up from the centerline.  This allows the bar graph to be configured to display deviations from a nominal non-zero value.  The top and bottom vertical limits of the graph are specified by the tEngUnitTop and tEndUnitBottom properties; array element values outside this range will display bars extending to the limits of the display.

If forcing any of these three properties to a fixed value is not appropriate for the display, there are two alternatives.  First, the property can be set to the name of a variable in global common whose value will be retrieved at runtime and used as the associate engineering value.  This allows the display to be programmatically controlled by values in global common.  Second, the property can be set to a special string consisting of an ampersand '@' followed by the name of a text box on the screen; in this case the value entered into the text box will be used as the associate engineering value.  This allows the HMI user to configure the display at runtime as he pleases.

Scale display configuration

The property YTickSpacing is defined as the spacing (in engineering units) between the y-axis ticks annotating the graph.  A tick is a short horizontal line drawn to the left of the graph together with a label indicating the corresponding y-axis position.  A property YTickSpacing value less than or equal to zero indicates that no ticks should be drawn.  A positive value indicates that ticks and labels should be drawn at integer multiples of the spacing value between the lower and upper limits of the graph.  The default value is zero.

...

titleProperties

The following properties are exposed by the TPRI.BarGraph object.

[TABLE]

Expand
titleMethods

The following methods are exposed by the TPRI.BarGraph class.

 

Code Block
Public Function fSetVals( _
ByRef afValue As Object _
) As Object

Description:

Set new values for all left and right bars (same value for left and right).

Parameters:

afValue

Tag of updated variable.

Return Value:

Zero for success; non-zero for failure.

Expand
titleEvents

The following events are exposed by the TPRI.BarGraph class.

 

Code Block
Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

TPRI.CoverageBar

Expand
titleOverview

A TPRI.CoverageBar control is a horizontal bar illustrating the location of a closed section within a wider region.  Typically a TPRI.CoverageBar is tacked on below a bar graph to depict which bars are to be considered ‘valid’.  For example, the CoverageBar may be used on a rolling mill to indicate which zones of a flatness bar display are covered by the strip itself.

[PICTURE]

Expand
titleOperation

At run-time, the TPRI.Coverage bar is a display-only object representing a contiguous range of values on the real number line.  The left and right edges of the horizontal bar represent the lower (or most negative) and the upper (or most positive) limits of this range.  Within this displayed range there is assumed to be a single range of values that are to be considered valid; these values are drawn in a different color to visually indicate the span of values that is valid.  In the image above, this valid range is drawn in blue, while the total displayed range is drawn in gray.

At design time, each of the four limits of the two ranges (left and right limits of displayed range, left and right limits of valid range) is set as a property of the object and can be specified in one of three ways.  First, the property can be hard-coded to the actual numeric value.  Second, the property can be set to the name of a variable on the host system that contains this value; at run-time this value will be actively retrieved and updated from the server.  Third, the property can be set to the name of a TPRI.TextBox [LINK] object elsewhere on the screen prepended with an ampersand ('@') character that contains the specified value; this allows the HMI user to configure the display himself at run-time.

...

titleProperties

The following properties are exposed by the TPRI.CoverageBar class.

[TABLE]

Expand
titleMethods

The following public methods are exposed by the TPRI.CoverageBar class.

 

Code Block
Public Sub SetLeftData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the covered section.

Parameters:

afValue

Value to be associated with the left side of the covered section.

 

Code Block
Public Sub SetLeftEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the entire bar.

Parameters:

afValue

Value to be associated with the left side of the entire bar.

 

Code Block
Public Sub SetRightData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right side of the covered section.

Parameters:

afValue

Value to be associated with the right side of the covered section.

 

Code Block
Public Sub SetRightEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right edge of the entire bar.

Parameters:

afValue

Value to be associated with the right edge of the entire bar.

Expand
titleEvents

There are no events exposed by the TPRI.CoverageBar class.

...

Add a variable owned by a specific control to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tscIdx

Index of calling control.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function WriteTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String, _
ByRef value As Object _
) As Integer

Description:

Write a value back to the specified variable on the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

value

New value of variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function RemoveTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String _
) As Integer

Description:

Remove an existing variable from the list of variables retrieved from the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

Return Value:

Zero for success; non-zero for failure.

Expand
titleEvents

The following events are exposed by the TPRI.OpcMgr object

 

Code Block
Public Event OnDataUpdate( _
ByVal Sender As System.Object, _
ByVal tag As String, _
ByVal value As Object, _
ByVal timestamp As Date, _
ByVal quality As Integer _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

Value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

 

Code Block
Public Event OnClientMsg( _
ByVal Sender As System.Object, _
ByVal err As Integer, _
ByVal msg As String, _
)

Description:

Passes a message to the client.

Parameters:

Sender

The source of the event.

err

Error number.

msg

Error description.

 

Code Block
Public Event OnRestart( _
ByVal Sender As System.Object, _
)

Description:

Indicates that communications with the host have restarted.

Parameters:

Sender

The source of the event.

 

Code Block
Public Event OnDisconnect( _
ByVal Sender As System.Object, _
)

Description:

Indicates that the connection to the host has been disconnected.

Parameters:

Sender

The source of the event.

TPRI.OpcCom

Expand
titleOverview

The TPRI.OpcCom object is an OPC communications client for accessing variables in global common on the host.  

Expand
titleOperation

The TPRI.OpcCom class is intended solely for internal use by the other TSENTRY objects.  For access to variables in global common exposed by the OPC server on the host, see the TPRI.OpcMgrclass.

Expand
titleProperties

There are no properties exposed by the TPRI.OpcCom class for public use.

Expand
titleMethods

There are no public methods exposed by the TPRI.OpcCom class for public use.

Expand
titleEvents

There are no events exposed by the TPRI.OpcCom class for public use.

TPRI.DataSetInfo

Expand
titleOverview

The TPRI.DataSetInfo is used to create, load, update and delete data set configuration files.

Image Added
Expand
titleOperation

Once placed on a screen, a TPRI.DataSetInfo object must be initialized in code with an appropriate call to the Initialize(..) method.  This configures the DataSetInfo object to retrieve and save data set files to the host system.

At runtime, the text box on the object display indicates the currently loaded data set.  Each of the buttons to the right perform some operation on the current data set:

Clear

Unload the current data set and restart with a fresh configuration.

Load

Load an existing data set from the host.

Save

Save the current data set to the host.

Delete

Permanently delete the current data set from the host.

 

Pressing the Load button above presents the Load Data Set form.

Image Added

This form allows the user to select and load a data set file from the host.  These files are stored on the host in the DataSet shared directory.

Expand
titleProperties

The following properties are exposed by the TPRI.DataSetInfo class.

Property Name

Type

Default Value

Description

FileExt

String

""tds"

File extension for data set files

SaveDelEnabled

Boolean

False

Security flag for enabling or disabling the Save and Delete buttons

Expand
titleMethods

The following public methods are exposed by the TPRI.DataSetInfo object.

 

Code Block
Public Sub Initialize( _
ByVal host As String, _
ByVal page As String, _
Optional ByVal loadLast As Boolean = True _
)

Description:

Initialize the object.

Parameters:

host

Name of the host to which the object should connect.

page

Name of parent page. This is used for storing the most recently used data set associated with a particular page.

loadLast

Flag to load the most recently used data set.

Remarks:

This function must be called before the object can be used to access a data set.

 

Code Block
Public Function LoadDataSet( _
Optional ByVal dsName As String = "" _
) As Integer

Description:

Load the specified data set.

Parameters:

dsName

Name of the data set to load.  If none is specified the Load Data Set form is displayed to allow the user to select the desired data set file.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function SaveDataSet( _
Optional ByVal fileExt As String = "..." _
) As Integer

Description:

Save the current data set.

Parameters:

fileExt

File extension to append to the data set name. If none is specified (or default "..."), no file extension will be appended.

Return Value:

Zero for success; non-zero for failure.

 

Public Sub ResetDataSet()

Description:

Reset the current data set.

 

Code Block
Public Function DeleteDataSet( _
Optional ByVal dsName As String = "" _
) As Integer

Description:

Delete the specified data set.

Parameters:

dsName

Name of the data set to delete.  If none is specified the current data set is deleted.

Return Value:

Zero for success; non-zero for failure.

 

The remaining public methods are intended solely for use by the other TSENTRY objects.

Expand
titleEvents

The following events are exposed by the TPRI.DataSetInfo object.

 

Code Block
Public Event OnNew( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Indicates a new data set has been created.

Parameters:

Sender

The source of the event.

e

Event argument.

 

Code Block
Public Event OnLoad( _
ByVal Sender As System.Object, _
ByVal tmpName As String _
)

Description:

Indicates that a data set has been loaded.

Parameters:

Sender

The source of the event.

tmpName

Name of the loaded data set.

 

Code Block
Public Event OnSave( _
ByVal Sender As System.Object, _
ByVal tmpName As String _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

tmpName

Name of the saved data set.

TPRI.DDVarSelect

Expand
titleOverview

The TPRI.LogMsg object actively displays all messages that are logged to a TSENTRY log message queue.  For instance, the bottom half of the NtRtMgr screen uses this object to display messages from the default ‘LogMsg’ queue.[PICTURE]DDVarSelect object is used to select a variable from the data dictionary and display its name to the user.

Image Added
Expand
titleOperation

Active operation of the TPRI.LogMsg object is fully automated by the screen framework provided that the user screen is derived from the TPRI.BaseScreen class and that it contains a TPRI.OpcMgr object.  

Configuration of a TPRI.LogMsg control consists mainly of setting the desired LogMsg queue name in the LogMsgName property.  This string must match one of the LogMsg queues defined in the system logs initialization file [LINK].  Once configured, the TPRI.LogMsg object will display all messages logged to the specified queueThe TPRI.DDVarSelect object acts as a simple text entry to allow the user to type in a valid variable name from the data dictionary.  Alternatively, the user may click on the '*' button in the upper right-hand corner of the text box to bring up the Data Dictionary Browser. Once the user selects a value from the data dictionary browser, it is automatically loaded into the text box of the TPRI.DDVarSelect object.

Use of the TPRI.DDVarSelect object requires that a separate TPRI.DataDict object exist elsewhere on the screen.  Typically a TPRI.DataDict object is dropped in an unused portion of the screen and made invisible so that the object itself is not displayed on the form.  Only one TPRI.DataDict object is required to service all of the TPRI.DDVarSelect objects on a screen.

Expand
titleProperties

Below is a list of all the properties that The following properties are exposed by the TPRI.LogMsg DDVarSelect class.[TABLE]

Property Name

Type

Default Value

Description

BorderStyle

BorderStyle

Flat

Border style

tFont

Drawing.Font

 

Text font

tToolTipText

String

""

Tool tip text

Expand
titleMethods

There are no public methods exposed by the TPRI.LogMsg DDVarSelect class.

Expand
titleEvents

There are no public events exposed by the TPRI.LogMsg class.

TPRI.ComboBox

Expand
titleOverview

The TPRI.ComboBox is used as a live display and input of global common variables that are defined only to have a finite set of allowable values.  

[PICTURE]

Expand
titleOperation

The TPRI.ComboBox is similar to the TPRI.TextBox [LINK] in that it displays the current value of a variable in global common and operates in two possible modes, read-only mode and input mode.  However, whereas the TextBox is a text-entry box that allows the user to enter any new value, the ComboBox is a drop down list that allows the user only to select a new value from the presented list of choices.  Moreover, since many times the HMI user does not think of the list of choices in terms of numerical values but instead in conceptual possibilities, the ComboBox allows the designer to associate a text string with each of the possible variable values; these strings can be displayed at run-time instead of the actual values themselves.

For example, suppose there is a variable in global common representing the current mode of a controller: automatic, manual, or off.  The variable itself is an integer, and is defined such that automatic = 2, manual = 1, and off = 0.  The TPRI.ComboBox object therefore limits the user choices in the drop down box to ‘Auto’, ‘Manual’, or ‘Off’, though it internally manages updating the variable value on the host to a 2, 1, or 0, respectively.

When the TPRI.ComboBox object is initially connected to the host, it displays the descriptive string associated with the current value of the variable in global common.  If this value is changed by some other process, the display will be updated accordingly to display the new descriptive string.  If the user makes a new selection from the drop down list, however, the background color of the display changes color and the active update of the value is put on hold while the user finalizes his selection.  The new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

In the case where the current value of the variable on the host is not in the list of available values defined in the TPRI.ComboBox object, the object will display “{XXX}” where XXX is the current value of the variable.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when a new item is selected from the list.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Expand
titleProperties

Below are all of the properties of the TPRI.ComboBox object.

[TABLE]The following events are exposed by the TPRI.DDVarSelect class.

 

Code Block
Public Event VarNameUpdate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Indicates the variable name has been updated.

Parameters:

Sender

The source of the event.

e

Event argument.

TPRI.DataDict

Expand
titleOverview

The TPRI.DataDict object is used to access the data dictionary on the controller.

Image Added
Expand
titleOperation

Normally, a TPRI.DataDict object on a user screen is configured as invisible so that it is hidden from the user.  The variable selection form itself is accessed by calling the DoModal(..) function. This form allows the user to graphically navigate through the data dictionary to choose a variable from global common.

Image Added

 

The top left of this form contains the Global Common Structure Tree.  The root elements in this tree represent each of the available global common, and expanding one of these commons reveals its internal structure.  Single clicking on variable name highlights the variable, while double clicking automatically selects the variable and closes the form.

To the right of the Global Common Structure Tree is the Selected Variable information box.  Once highlighted in the structure tree, the full structure name, element type, and description of the selected variable are displayed.

Below the Selected Variable information box is the Return selection box.  The main edit box here displays the variable name string as it will be returned to the screen.  Normally, this string consists of the fully qualified variable name; however, instead of returning a string representing the variable itself, the user has the option to instead return a string representing some property of the variable.  The following options are available:

 

Name

The variable name itself.

Desc

The variable description (prepends '#' to the variable name).

Min

The specified minimum value of the variable (prepends '<' to the variable name).

Max

The specified maximum value of the variable (prepends '>' to the variable name).

Init

The specified initial value of the variable (prepends '=' to the variable name).

String

Treat character array as a string (prepends '$' to the variable name and removes any trailing square braces '[]' indicating an array)

 

Clicking the accept button closes the form.

The bottom half of the variable selection form allows the user to search through variable names and descriptions for strings.  Typing in the selection string and hitting the enter key activates the search, which fills the list box below with all matching variables.  Single clicking on a found variable locates it in the structure tree and displays its information in the Selected Variable box.  Double clicking on the variable name automatically selects it and closes the variable selection form.  

Tip: The user can search the data dictionary for multiple strings by separating them with spaces in the Search string.  In this case all of the specified words must exist in either the variable name or description in order for the variable to be displayed.

The data dictionary display is initialized by copies of the structure and variable data dictionary initialization files used to initialize the data dictionary for the processes on the control system.  The TPRI.DataDict object looks for these copies hosted on the web server at the locations specified by the VarsFileName and StructFileName properties of the object.  Normally, these copies are made as part of the data dictionary building process on the host.

For more in-depth information about the data dictionary, refer to Data Dictionary.

Expand
titleProperties

The following properties are exposed by the TPRI.DataDict class.

Property Name

Type

Default Value

Description

VarsFileName

String

"/tsentry/pif/gsmVars.txt"

Name of variable definition file on host web server.

StructFileName

String

"/tsentry/pif/gsmStruct.txt"

Name of structure definition file on host web server

 

Expand
titleMethods

The following public methods are exposed by the TPRI.ComboBox classDataDict object.

 

Code Block
Public Function ConvertStrToNumStartComm( _
ByVal StrText sHostName As String, _
ByVal sPathDir As String _
) As Integer

Description:

Start communications with a host.

Parameters:

sHostName

Name or IP address of the data host.

sPathDir

Path/subdirectory of page on host.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function DoModal( _
ByVal defVarName As String _
) As Integer

Description:

Retrieve the value associated with the specified descriptive string.

Parameters:

StrText

Descriptive stringDisplay the data dictionary browser form.

Parameters:

defVarName

Default variable name to highlight.

Return Value:

Zero for success; non-zero for failure.

 

Public Function GetVarName() As String

Description:

Get the selected variable name.

Return Value:

Variable value associated with the descriptive stringSelected variable name.

 

Code Block

Public

public: 

Function

int 

ConvertNumToStr

GetFiles( _

ByVal StrNum As String _ ) As String

Description:

Retrieve the descriptive string associated with the specified variable value.

Parameters:

StrNum

Variable value.

Return Value:

Descriptive string associated with the passed value


tpriIniFile** pStructIni,
tpriIniFile** pVarsIni,
Boolean bForceRefresh
);

Description:

Create new tpriIniFile objects containing the structure and variable definition files.  This method is only callable from a C++.NET object due to the requirement of the tpriIniFile class definitions.

Parameters:

pStructIni

Address of pointer to assign to new tpriIniFile object containing structure.  If successfully assigned this object must be explicitly deleted; it is not managed by the garbage collector.

pVarsIni

Address of pointer to assign to new tpriIniFile object containing structure.  If successfully assigned this object must be explicitly deleted; it is not managed by the garbage collector.

bForceRefresh

Flag to refresh the files from the host or simply return the latest data.

Return Value:

Zero for success; non-zero for failure.

Expand
titleEvents

[TABLE]

...

titleMethods

...

titleEvents

TPRI.DDVarSelect

Expand
titleOverview

The TPRI.DDVarSelect object is used to select a variable from the data dictionary and display its name to the user.

[PICTURE]

...

titleOperation

...

titleProperties

[TABLE]

...

titleMethods

...

titleEvents

TPRI.DataDict

Expand
titleOverview

The TPRI.DataDict object is used to access the data dictionary on the controller.

[PICTURE]

...

titleOperation

...

titleProperties

[TABLE]

...

titleMethods

...

titleEvents

TPRI.HMI.Controls.TrendCtrl

Expand
titleOverview

The TPRI.HMI.Controls.TrendCtrl object is used to select variables for trending as well as to monitor the values of each of these variables during trending.  The main display of the TrendCtrl object is a grid of information displaying information about the entire set of trended variables.  

[PICTURE]

[TABLE]

Expand
titleOperation
Expand
titleProperties
Expand
titleMethods
Expand
titleEvents

The following There are no events are exposed by the TPRI.ComboBox class.

 

Code Block
Public Event Change( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Indicates the selected value has been changed.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

 

Code Block
Public Event OnValidate( _
ByVal Sender As System.Object, _
ByRef Cancel As Boolean _
)

Description:

The current selection is being validated.

Parameters:

Sender

The source of the event.

Cancel

Flag indicating whether or not the selection is valid.

Remarks:

This event will be raised when the current selection must be validated.  The event handler should set the Cancel parameter according to whether or not the current selection is valid.

 

Code Block
Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument. This will always be nothing.

TPRI.OpcMgr

Expand
titleOverview

The TPRI.OpcMgr object is responsible for automating all active variables on a screen.  On initialization it searches for any objects on the screen that are derived from TPRI.BaseControl and requests from each of them a list of variables that should be retrieved from the host system.  Then as these variables are updated from the server to the client, the OpcMgr object passes these updates back to each of the associated BaseControl objects.

[PICTURE]

Expand
titleOperation

In most cases, all operation of the TPRI.OpcMgr object is fully automated by the TPRI.BaseScreen framework. While connected to the data host, the OpcMgr object will display green and indicate the date/time of the most recent variable update from the host.  Before the initial connection and any time the OpcMgr object disconnects from the host, the display will turn orange and will indicate the date/time of the most recent connection attempt; the OpcMgr object should attempt to reconnect every 3-5 seconds.  Finally, there are two cases in which the OpcMgr object will turn red:

If the OpcMgr object is unable to find any variables configured on the screen for retrieval from the server, the object will turn red and display a message indicating that there are no OPC items configured.

If the OpcMgr object encounters an unrecoverable error the object will turn red and display an error indication.  Details of the error can be viewed by holding down the control key and left clicking on the object.

 

There are some situations where a screen may want to receive variable updates for data that it wishes to use for its own purposes rather than for display in one of the existing active objects.  To accomplish this, the screen should do the following:

Add an event handler for OnRestart(..).  Inside this handler make appropriate calls to the AutoAddItem() method to add all variables that the screen would like to receive directly.

Add an event handler for OnDataUpdate(..).  Inside this handler process individual variable updates.

Optionally add an event handler for OnDisconnect(..).  Place any code to reset the visual display of the screen to indicate that the screen is not connected to the data host.

...

titleProperties

The following public properties are exposed by the TPRI.OpcMgr object.

[TABLE]

Expand
titleMethods

The following methods are exposed by the TPRI.OpcMgr object.

 

Code Block
Public Function StartComm( _
ByRef hostName As String _
) As Integer

Description:

Start communications with a host.

Parameters:

hostName

Name or IP address of the data host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

By default, the TPRI.BaseScreen implementation looks for all TPRI.TrendCom objects and calls this method to automatically initialize trending.  This is disabled if the tAutoStart property is set to False.

 

Code Block
Public Function AutoAddItem( _
ByRef fullItemName As String, _
ByRef tagName As String _
) As Integer

Description:

Add a variable to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function WriteItem( _
ByRef tagName As String, _
ByRef value As Object _
) As Integer

Description:

Write a value back to the specified variable on the host.

Parameters:

tagName

Tag of variable to be written.

value

New value of variable.

Return Value:

Zero for success; non-zero for failure.

 

Public Function WriteModified( _

) As Integer

Description:

Find and write all modified variables on the screen back to the host.

Return Value:

Zero if no error, nonzero if error.

 

Code Block
Public Function RemoveItem( _
ByRef tagName As String _
) As Integer

Description:

Remove an existing variable from the list of variables retrieved from the host.

Parameters:

tagName

Tag of variable to be written.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function RefreshAll( _
) As Integer

Description:

Request the server to refresh all data values back to the client.

Return Value:

Zero for success; non-zero for failure.

 

 

The following methods should not be called from an application screen.  They are used by other active controls to configure variables associated only with those controls.

 

Code Block
Public Function AutoAddTscItem( _
ByRef fullItemName As String, _
ByRef tscIdx As Integer, _
ByRef tag As String _
) As Integer

Description:

Add a variable owned by a specific control to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tscIdx

Index of calling control.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function WriteTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String, _
ByRef value As Object _
) As Integer

Description:

Write a value back to the specified variable on the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

value

New value of variable.

Return Value:

Zero for success; non-zero for failure.

 

Code Block
Public Function RemoveTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String _
) As Integer

Description:

Remove an existing variable from the list of variables retrieved from the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

Return Value:

Zero for success; non-zero for failure.

Expand
titleEvents

The following events are exposed by the TPRI.OpcMgr object

 

Code Block
Public Event OnDataUpdate( _
ByVal Sender As System.Object, _
ByVal tag As String, _
ByVal value As Object, _
ByVal timestamp As Date, _
ByVal quality As Integer _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

Value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

 

Code Block
Public Event OnClientMsg( _
ByVal Sender As System.Object, _
ByVal err As Integer, _
ByVal msg As String, _
)

Description:

Passes a message to the client.

Parameters:

Sender

The source of the event.

err

Error number.

msg

Error description.

 

Code Block
Public Event OnRestart( _
ByVal Sender As System.Object, _
)

Description:

Indicates that communications with the host have restarted.

Parameters:

Sender

The source of the event.

 

Code Block
Public Event OnDisconnect( _
ByVal Sender As System.Object, _
)

Description:

Indicates that the connection to the host has been disconnected.

Parameters:

Sender

The source of the event.

STOPPED HERE

TPRI.OpcCom

Expand
titleOverview

The TPRI.OpcCom object is an OPC communications client for accessing variables in global common on the host.  

Expand
titleOperation

The TPRI.OpcCom class is intended solely for internal use by the other TSENTRY objects.  For access to variables in global common exposed by the OPC server on the host, see the TPRI.OpcMgr [LINK] class.

Expand
titleProperties

There are no properties exposed by the TPRI.OpcCom class for public use.

Expand
titleMethods

There are no public methods exposed by the TPRI.OpcCom class for public use.

Expand
titleEvents

There are no events exposed by the TPRI.OpcCom class for public use.

TPRI.DataSetInfo

Expand
titleOverview

The TPRI.DataSetInfo is used to create, load, update and delete data set configuration files.

[PICTURE]

...

titleOperation

...

titleProperties

DataDict object.

TPRI.HMI.Controls.TrendCtrl

Expand
titleOverview

The TPRI.HMI.Controls.TrendCtrl object is used to select variables for trending as well as to monitor the values of each of these variables during trending.  The main display of the TrendCtrl object is a grid of information displaying information about the entire set of trended variables.  

Image Added
Expand
titleOperation

At run-time, the TrendCtrl itself is used mainly as a display to provide feedback about the data being trended.  The top two rows of the TrendCtrl object display the dates and times for trended data.  The remaining rows are broken up by axis, with the trended variables shown for each axis.

The information displayed for each variable, in columns from left to right, are:

  • The color of the pen used to trend the variable.  For instance, the PidCom.rtDrift.filtDrift variable above is being plotted in yellow.

  • The label associated with the variable.  Each variable can have an associated label for a sensible description of what is being trended.  If no label is specified this column will instead display the actual name of the variable.

  • Value of the variable at the left cursor.  The value displayed in the first data column (magenta background) is the value of the variable underneath the magenta cursor bar.  If cursors are not being used, this value represents the value of the data at the leftmost edge of the trend graph.  For instance, the left cursor data value for the PidCom.rtDrift.filtDrift variable above is 2.1895e-5.

  • Value of the variable at the right cursor.  The value displayed in the second data column (cyan background) is the value of the variable underneath the cyan cursor bar.  If cursors are not being used, this value represents the value of the data at the rightmost edge of the trend graph.  For instance, the left cursor data value for the PidCom.rtDrift.filtDrift variable above is 3.3646e-4.

  • Difference in values between the left and right cursors.  The value displayed in the third data column (gray background) is equal to the left cursor value minus the right cursor value, useful for easily determining how much a value has changed during some period of time.  For instance, the difference in cursor data values for the PidCom.rtDrift.filtDrift variable above is (2.1895e-5 - 3.3646e-4) = -3.1457e-4.

 

Trends are configured via the Trend Setup form.  This form can be accessed at design-time via the TrendInfo property of the TrendCtrl object or at run-time by calling the TrendSetup() method of the TrendCtrl object.

Image Added

In the top portion of the form, the user can set various parameters to define the trend graph as a whole:

  • Trend Width: width of the trend graph in seconds, that is, the total amount of time to be displayed on the trend graph.

  • Sampling Period: sampling period for plotted points on the graph, as well as the requested sampling period for trended variables.  The total number of points plotted will equal the Trend Width divided by the Sampling Period.

  • Default Source: trend source to which all trend variables should be assigned when the Set All Variables button is pressed.  This is useful when switching between two historical trend files created from the same trigger.

 

The middle 'Trend Axes' section of the form allows the user to add, delete, and configure each of the trend axes.  Several columns are provided to configure each axis:

  1. The axis label is a descriptive string that will be attached to the axis on the trend graph.

  2. Min specifies the minimum value of the vertical range for this axis.

  3. Max specifies the maximum value of the vertical range for this axis.

  4. The axis percentage specifies what percentage of the vertical extent of the entire trend graph should be used by this particular axis.  If the Normalize Axis Percentages option is selected (see below), these percentages will be automatically calculated and each axis will be given an equal amount.  If the Normalize Axis Percentages option is disabled, the user can individually configure each axis; however, the total percentage used by all activated axes must equal 100%.

The parameters for a given axis can be modified in one of two methods.  First, the user can highlight the desired axis and single-left-click on the parameter to be modified; within a few moments the field will become editable and the user can make the appropriate selection.  Alternatively, once highlighting the desired axis the user can right click anywhere on the axis entry to display a popup menu of options.  This menu contains several commands to edit the various axis properties.

Image Added

This popup menu also presents commands to insert and delete an axis and to enable or disable the Normalize Axis Percentages option mentioned above.

 

The bottom ‘Trend Variables’ section of the form allows the user to configure each individual variable for trending.  Variables are divided up according to the axis with which they are associated.  Several columns are provided to configure each variable:

  1. The Source specifies the trend source which is responsible for providing the data for the given variable.

  2. The Variable specifies the name of the variable within the trend source.

  3. The Label is a descriptive string associated with the trend variable.  If set, this label is displayed on the TrendCtrl object instead of the actual variable name.

  4. The Color specifies the pen color to be used when plotting this trend variable.

  5. The Line Type specifies the how the trend should be plotted.  Available options include a variety of thin, medium, and thick pens drawing a solid, dashed, or dotted line.

Like the trend axis parameter, the parameters for a given trend variable can be modified in one of two methods.  First, the user can highlight the desired variable and single-left-click on the parameter to be modified; within a few moments the field will become editable and the user can make the appropriate selection.  Alternatively, once highlighting the desired axis the user can right click anywhere on the variable entry to display a popup menu of options.  This menu contains several commands to edit the various variable properties.

Image Added

This popup menu also presents commands to insert, delete, copy, and paste a variable or group of variables.

 

When editing the Source for a given variable, the user may either simply type in the appropriate source or alternatively click on the asterisk (*) to bring up the Select Trend Source dialog.  This dialog allows the user to select from the available trend sources.  It is described in detail in the TrendSrcSelect section of this manual.

 

Similarly, when editing the Variable name for a given variable, the user may either simply type in the appropriate name or alternatively click on the asterisk (*) to bring up the Data Dictionary dialog.  This dialog allows the user to browse through the available data dictionaries to find the appropriate variable in the desired source.  It is described in detail in the Data Dictionary section of this manual.  Note that if the data dictionary is used to select a variable, and a variable is chosen from a data dictionary that is different from the currently selected trend source, the trend source for the current variable will be updated to the new source accordingly.

 

Finally, there are several buttons in the lower right corner of the Trend Setup form.

  • ‘OK’ accepts all changes and closes the Trend Setup form.

  • ‘Cancel’ exits the Trend Setup form without saving the changes.

Expand
titleProperties

The following properties are exposed by the TPRI.HMI.Controls.TrendCtrl class.

Property Name

Type

Default Value

Description

AxisMinBox

TPRI.HMI.Controls.TextBox

Nothing

Reference to the TextBox object that will provide the vertical axis range minimum value.

AxisMaxBox

TPRI.HMI.Controls.TextBox

Nothing

Reference to the TextBox object that will provide the vertical axis range minimum value

Graph

Gigasoft.ProEssentials.Pego

Nothing

Reference to the Pego object that will display the trend graph

PlaybackControl

TPRI.HMI.Controls.TrendPlayback

""

Reference to the TrendPlayback object to associate with this TrendCtrl

TrendSet

TPRI.Trending.TrendSet

Empty TrendSet object

Trend configuration

UseCursors

Boolean

False

Flag to enable the use of cursors on the trend graph

Expand
titleMethods

The following properties are exposed by the TPRI.HMI.Controls.TrendCtrl class.The following public methods are exposed by the TPRI.TrendCtrl class for use by code on custom screens.

Code Block
Public Sub TrendSetup()

Description:

Load and display the Trend Setup form.

 

The remaining public methods are intended solely for use by the other TSENTRY objects.

Expand
titleEvents

The following events are exposed by the TPRI.TrendCtrl class.

Code Block
Public Event OnTrendClear( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The trend control has been cleared and reset.

Parameters:

Sender

The source of the event.

e

Event argument.

 

Code Block
Public Event OnTrendInit( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The trend control has been initialized.

Parameters:

Sender

The source of the event.

e

Event argument.

Code Block
Public Event OnChangedTrendSet( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The set of trended variables has been changed.

Parameters:

Sender

The source of the event.

e

Event argument.

Code Block
Public Event OnUpdData( _
ByVal Sender As System.Object, _
ByVal timeLast As Double, _
ByVal timestamps As String, _
ByVal values() As Single, _
ByVal cnt As Integer, _
ByVal forward As Boolean _
)

Description:

The trend control has updated data to the graph.

Parameters:

Sender

The source of the event.

timeLast

Timestamp associated with the most recent data point.

timestamps

String of timestamps for each data point.

values()

Array of data point values.

cnt

Number of data points.

forward

Indicates whether or not the above data is ordered forward in time or backward in time.

TPRI.TrendCtrl Variable Insert/Delete Form

...

Expand
titleOverview

The TPRI.TrendCom object is responsible for automating communications for all trends on a screen.  On initialization it searches for any TrendCtrl objects on the screen and begins to request data on their behalf from the host system.  As responses are received, the TrendCom object feeds the data back to the appropriate TPRI.TrendCtrl [LINK] objects.

Expand
titleOperation

In most cases, all operation of the TPRI.TrendCom object is fully automated by the TPRI.BaseScreen [LINK] framework. While connected to the data host, the TrendCom object will display green and indicate the date/time of the most recent trend data response from the host.  Before the initial connection and any time the TrendCom object disconnects from the host, the display will turn orange and will indicate the date/time of the most recent connection attempt; the TrendCom object should attempt to reconnect every 3-5 seconds.  Finally, there are three cases in which the TrendCom object will turn red:

If the TrendCom object has not been supplied a hostName to which it should connect, the object will turn red and display a message indicating that there is no host specified.

If the TrendCom object is unable to find any TrendCtrl objects on the screen or none of the TrendCtrl object specify any variables to be trended, the object will turn red and display a message indicating that there are no trend items configured.

If the TrendCom object encounters an unrecoverable error the object will turn red and display an error indication.

...

Expand
titleOperation

The TPRI.TriggerEd object acts purely as a run-time user interface for interacting with the historical trend system.  The buttons along the top row of the screen allow the user to create a New trigger definition, Load an existing trigger, Save the current trigger, Activate the current trigger, or Deactivate the current trigger.

Below the row of buttons are a set of fields to configure general information about the trigger.

Trigger Name

Name of the trigger

Pre-Trigger Time

The number of seconds prior to the beginning of the event that should be recorded in the historical data file.

Post-Trigger Time

The number of second after the end of the event that should be recorded in the historical data file.

Max Trend Time

Maximum number of seconds of data to record into a single file.

Description

Description of trigger file to store with the historical trend files.

Below the general information fields are two columns of variables.  The left column of Trigger Variables allows for specification of all variables that define the trigger.  Each line in this list defines a Boolean operation; the trigger is considered active when every one of these operations is satisfied.  Each operation is defined by a variable name, a comparison operator and comparison value selected; hence the operation is considered true when the associated variable on the host system meets the specified criterion.  In order to facilitate variable selection, each of the variable name entry fields are TPRI.DDVarSelect [LINK] objects; clicking on the '*' in the upper right hand corner of the text box will load the data dictionary browser form.

The right column of variables, the Trend Variables, specifies each of the variables that should be recorded while the trigger is considered active.  Like the Trigger Variable names, the data dictionary browser can be loaded by pressing the '*' in the upper right hand corner of any of the Trend Variable entry text boxes.

...

Expand
titleO-Modifying a Rule Configuration

Parameter values can be modified by single-left-clicking on the parameter value, which will bring up an edit box that allows for text entry.  

Pressing the enter key while editing or clicking outside of the edit box will validate the user entry; if it is valid the rule parameter will be changed, while if there is a problem the user will be prompted and asked to correct the value.

Editing a criteria or action value brings up a special text edit box that provides access to the Data Dictionary [LINK] by right clicking in the edit box.

Once any rule parameter has been modified from its original value, the rule name displayed as the label on the root node is appended with an asterisk to indicate that it has been modified.

For more in-depth information about the data dictionary, refer to Data Dictionary [LINK].

Expand
titleO-Saving a Rule

A rule can be saved to a file on disk and stored for later reference by choosing either of the first two save options from the popup menu.  The Save Rule option simply saves the rule to its current file, while the Save Rule As... option saves the rule under a different name or into a different folder.

Before the rule can be saved to disk, though, it must be validated to ensure that each of its parameters is formatted correctly and contains valid data.  If validation is not successful the user will be prompted with a list of problems and the rule display will be populated with a red Local Errors node that contains a duplicate of this list.

For instance, an improperly formatted VariableCondition statement containing unmatched parentheses causes a fatal validation error because the condition cannot be properly parsed.  On the other hand, a properly formatted VariableCondition statement that contains a variable name that cannot be located in the data dictionary only causes a non-fatal validation warning, as this rule can still be properly parsed by the rules manager process.

If only validation warnings are encountered, and there are no fatal validation errors, the user has the option of continuing with the save process or canceling the save to fix the problems; however, if any fatal errors are encountered the save cannot continue.

If a rule is currently active on the host, it can only be saved to the host share under its current name by re-activating it at the same time (see below).  The user may however choose to save the rule to a different folder under the same name.

...