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.

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.

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

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

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.

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.

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.

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.

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.

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").

Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the previous page.

Remarks:

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

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

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.

Public Event ErrorTerminate()

Description:

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

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

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

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

Public Overridable Sub OnInitialized()

Description:

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

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.

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

Description:

Start active operation of the screen from an ASP web pageUpdate the value of one of the active variables associated with the control.

Parameters:

vobjWindow

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

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 only not be called from any user code; it is intended solely for use by the container ASP to initiate activity on the screenother 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.

ProtectedPublic Overridable Function StartFromFormGetModifiedVars( _
ByRef vobjForm As Object, _
ByRef host tagList() As String, _
ByRef pathvalList() As String, _
ByRef args As StringObject _
) As Integer

Description:

Start active operation of the screenRetrieve list of variables and corresponding values that have been modified and must be written back to the data host.

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 screentagList()

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.

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 overridable public methods are exposed by the TPRI.BaseScreen class.

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

Image Added

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 object.

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.

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

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.

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

Image Added

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...)

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

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

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

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

Image Added

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:

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

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.

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.