PICS DataViews Interface (PicsViews)

For DV-Draw Usage Notes, click here.

OVERVIEW

The application performs the following tasks: mapping the static database cache, subscribing to all real time data points, loads views from disk, maps the appropriate view variables directly (or indirectly) to PICS data sources, and controls when DataViews renders each view. There is a glossary at the end of this document, intended to clarify terms that may have a different meaning in the DataViews system. Click here to see some annotated screen shots.

OPERATION

PICSViews is capable of loading two different types of file as the 'base' view. The first type is a single view file. The second type is called a layout file. A single view file contains one DataViews drawing (although a single DataViews drawing may actually contain multiple objects, or object sets, that the users considers 'drawings'). A layout is a special form of the single view file that contains a number of named rectangle objects. Each rectangle's name matches the name of a single view file that is to be loaded in the rectangle's position in the layout. The rectangles in a layout may overlap, but views are not transparent, so the topmost rectangle (actually, the view loaded in that position) will obscure any other views that are behind it. See the Layout Files section below for more details.

When the File | Open menu item is selected, PICSViews displays a list of available layouts by default. You may change the listed file type to 'Views' or 'All Files' if the file you're seeking isn't shown. The file open dialog is also a standard system dialog, so you may also browse the drives and/or directories on your system to locate a view.

LAYOUT FILES

A layout file is simply a regular view that contains only named rectangle objects that are used to locate and place other views within the display window. Each rectangle should be named to match the view file that is to be placed within. For example:


Figure 1 - Sample layout file

The layout file shown in Figure 1 (above) contains four rectangles, named: "Background.v", "Overlay1.v", "Overlay2.v", and "MiniSpds.v". When PicsViews loads this layout file, it will get the names of each of the rectangles and attempt to load the views from files matching the rectangle names. It will also do the work necessary to have DataViews display each view in the given position and layer. If the rectangle named "Background.v" in the example were to be saved with the "in front" attribute (available in DV-Draw) then the other views would be obscured, even though they would still be loaded because PicsViews actually knows nothing about the layering of the layout rectangles, or what obscures what.

Any other information included in a layout file will be ignored by PicsViews. This allows you to include text items for documentation purposes. If any rectangles are used in the documentation portion of a layout file, they should remain UNNAMED or an error will result. By default, PicsViews uses the complete extents of all existing objects in the layout view to determine the overall size of the display viewport, so any documentation or special text settings should be placed within the boundaries of the display rectangles to avoid inadvertently increasing the area used to place the views.

Some special text items may also be included to control how the layout is fitted into the display window. These settings may be placed within the view by creating named text objects (the object names must match the setting name):

VIEW CONSTRUCTION

The DataViews product, DV-Draw is used to construct view and layout files for PICSViews to load. Most of the features available within DV-Draw are supported by PICSViews. All known exceptions are listed at the end of this section. DataViews is relatively new to the Windows platform, so their TrueType font support is somewhat lacking compared to the other features of the product. (Some of the weaknesses in TrueType are in the Windows font rendering engine, not all can be blamed on DataViews.)

For full-screen views, keep in mind the aspect ratio of your target display hardware when designing your view. The DataViews design surface is a perfect square defined using a logical coordinate system of -16K,-16K to +16K,+16K. Out of that perfect square, PicsViews only uses either the extent rectangle or the bounds of the layout (or view when a single view is loaded). Views constructed specifically to be embedded (or overlayed) on a larger view may have any aspect ration, but remember, even those views may have their aspects changed, based on how the extent is fitted into the display window.

Creating Variables

The off-the-shelf view editor (DV-Draw) supports a number of different data sources, including file, memory, constant and function. While PicsViews will rebind any variable whose name matches either a reserved name, or a data point name, the use of file data sources is not recommended. When a file data source is used, the file must exist in order for the view to function properly, even when all of the variables contained within the file have been rebound. For this reason it is suggested that all variables reside in either a memory or function data source. Constants may be used if necessary, but variables in a Constant data source should never be given reserved or data point names because constants cannot be rebound. If you need a PICS constant, create a memory variable using its name in the data base, or enter the value directly as a constant variable.

Function Data Sources

DV-Draw refers to function data sources as FDSeval and FDSrandom. FDSrandom data is of very limited use in production views. However, FDSeval may be used to greatly enhance the capabilities of your views. For example, you might create an FDSeval variable that is computed by multiplying the value of a number of digitals together and change a color dynamic based on the entire group's state. Or you might use relatively raw inputs to compute useful values that are not produced by the PICS compute applications.

Referencing PICS Data

The variables assigned to active objects within a view may be named using the following syntax to access PICS data:

PointName:attribute

For example, RECL-0:value would return the floating point value of the point named RECL-0. The variable's data type (in the DataViews drawing) should correspond to the attribute named. The following attributes are supported in this program:

Reserved Variable Names

PicsViews will automatically map any variable whose name matches a PICS data point to the associated real time value (or static, as the attribute indicates). PicsViews will also map matrix variables to a matrix translation table for variables specified as Filename.m:matrix. See the section on matrix files below for detailed information. PicsViews will also map the following variable names to internal values:

Private View Variables

Every view may have its own, internal variables in addition to the PICS and PicsViews values that are available. Internal variables will generally be contained within a function data source (FDS) and will compute a value at runtime based on PICS and/or PicsViews values. Internal variables should have a colon (':') as their first character to signal PicsViews that the variable is internal and should not be mapped. This will allow files to load a bit faster, since PICSViews will not need to search for the variable name in the list of point names and known pre-defined names.

Matrix Files

Some DataViews objects (such as size graphs) accept input in the form of a single matrix variable, rather than in an array of individual values. To support this feature, PicsViews allows you to name the matrix variable using the syntax Filename.m:matrix, where Filename.m specifies the name of an ASCII file containing a matrix map, and :matrix signals PicsViews that it is to attempt to load the named matrix file. Any matrix variables whose names do not include the :matrix tag will not be rebound by PicsViews. Here's a sample of a matrix file (a detailed description of the contents follows):

    ;Sample Matrix File
    5,5
       *,    *, P100,    *,    * 
       *, P101, P102, P103,    *
    P104, P105, P106, P107, P108
       *, P109, P110, P111,    *
       *,    *, P112,    *,    *

The first line, beginning with a semi-colon, is a comment. Comments and blank lines are ignored by the matrix mapper. The next line "5,5" indicates the dimensions of the matrix. These dimensions should match exactly the dimensions specified in the variable's data definition for the view. The map must be defined using the given dimensions. Using an asterisk ('*') indicates that there is no point at that location, zero will be used. You may also place a constant value in place of an asterisk. The other positions in the sample all have real time data point names. The matrix mapper will create a table to move the values of these points into the appropriate places in the matrix at run time. A point may appear in the matrix as often as the dimensions allow.

A vector variable may be created using a matrix file, by defining only one row.

Using ASCII file data to drive Views

DV-Draw has the ability to read any ASCII file (using white space as value delimiters) for test data. The default file (default.dat) contains roughly 5000 random values ranging between zero and one. However, data files produced by the PICS Retrieve application would also work (once the headers are removed and empty value cells were filled). In general, special views would be constructed (at this time, at least) to review ASCII file data.

Active Subdrawings

An active subdrawing is defined as any subdrawing that contains internal dynamics. For example, a common gage may include an internal variable that controls the needle. Active subdrawings present a special problem for PicsViews because of the way DataViews links them to their data. For views designed to be displayed by PicsViews, the following procedure will be used.

The subdrawing's internal variables should be given meaningful names (e.g. Needle for the needle in a gage subview). The meaningful names should be mapped to actual PICS points when the subdrawing is inserted into a view. Remember however, that variable ranges and dynamic definitions are contained within the subdrawing, so active subdrawings may be of more limited utility than first glance may suggest.

Unsupported DataViews Features

DataViews is a very powerful package with many, many features and capabilities. In the interest of getting something functional working and delivered to FPC, some of the DataViews features are not supported. Inclusion on any of these features in a view to be displayed by PICSViews will result in unpredictable behavior

COMMAND LINE

PicsViews supports command line parameters, for use in pre-defining default settings for a view. This allows you to avoid embedding some configuration parameters in the layouts or views themselves. The following items may be placed on the command line in any order:

For example, this command line:

PicsViews -Refresh:1000 -Stretch:Yes -PlantMode:Operate "Core Dynamics.lay"

would load all of the views referenced in the layout file "Core Dynamics.lay" using a default refresh of 1 second (1,000 milliseconds) and stretch the views to fit the viewports defined in the layout.

Prefixing a command line parameter with an exclamation point will cause PicsViews to ignore any settings contained within a view, in addition to setting a default value. For example:

PicsViews -!Refresh:1000 -!Stretch:Yes -PlantMode:Operate "Core Dynamics.lay"

would be the same as described before, but any refresh and stretch settings in the layout or view being loaded will be ignored.

PicsViews User Interface

With the exception of the menu bar and Windows default keys, all of the key/mouse events that PICSViews handles are completely configurable through the use of Action Files. The default action file maps the following key and mouse events to the described actions:

Active View

The 'Active View' is defined by DataViews as the view currently under the mouse pointer. PicsViews extends this concept slightly to keep the most recently active view when the mouse moves (a) out of the program window or (b) over a non-drawport portion of the display. The second event (b) can occur if a template contains areas between boundary rectangles that do not belong to any view (as in the sample given in the Layout Files section of this document).

Action Files

PicsViews supports additional view behavior instructions in the form of 'Action Files' (*.x). Action files are ASCII text files that are loaded in conjunction with a view. To associate an Action file with a view, both files must be given the same base filename (only the extension changes from '.v' to '.x'). The file format is very similar to INI files used by Windows applications. There must be a header section, there may be an OnLoad section, and one or more action definition sections. The header section defines information about the Action file, such as version number, that may be used in configuration control and/or by PicsViews to determine how to interpret the file.

Syntax

Action files follow the INI file syntax exactly. Blank lines are ignored. If the first character on a line in a semi-colon, the line is treated as a comment and ignored (e.g. ;This is a comment). Section names appear on a line by themselves and are encapsulated in square brackets (e.g. [Section]). Item-value pairs are listed one pair per line and are separated by an equal sign (e.g. item=value). Any spaces within square brackets or around the equal sign in an item-value pair are significant, so be sure any spaces in those locations are intended.

The Header Section

This section contains information about the file and how it should be interpreted by PicsViews. The following items are found in the Header section:

The OnLoad Section

This section is not implemented in PICSViews v1.0. The intent of this section is to define a special action to be executed immediately after the view has been loaded. For example, loading related views, etc. Other special event sections may be added in a future version.

Action Sections

Each action section corresponds to the name of an object contained within the view. Currently, the only item that is contained within an action section is 'OnClick' which indicates that

The Global Action File

PicsViews supports a 'global' action file (which must be named 'PicsViews.x' and located in the DataViews search path, preferably in the PICSViews or PICSViews\Views directory) to define actions common to all views and layouts. Generally these actions will include things like a view to be loaded when a specific condition occurs, such as a plant trip or a specific keypress (like F8 always loads the RCP Status display). This file is not required, but must have the correct name and location if it is intended for use. Typically all global actions will be unbound (not attached to specified objects, see the next section), but if a standard layout is defined at a site, that layout might contain a standard set of objects that are always visible. In that situation it may appear sensible to make those actions global, but it would be more sensible to attach them to the common view to avoid coupling the layout too tightly to the base application.

Action Definition Sections

An action section of the extra file contains information describing the trigger for an action as well as the action itself. The section name represents an object in a view, or an asterisk ('*') to indicate that the action is not bound to any particular object. PicsViews scans the action list in the same sequence that it exists in the file (at load time, changes while a view is open have no effect), so in the event that conflicting or overlapping actions are defined, PicsViews will only execute the first matching action. This allows you to use the asterisk to bind 'global' actions to the same triggers used for object-specific actions earlier in your file.

Since PicsViews action files are not used by any Windows INI file functions, you may use the same section name (object name) multiple times in order to define multiple actions for a single object. You cannot define more than one action (or trigger) per section. If you try to define multiple actions and/or triggers in a single section, PicsViews behavior is undefined and may result in a program error.

There are currently (version 1.0) seven keywords defined for an action section. Each of these is discussed in detail in the following sections.

Action

As the name implies, this key will define the action to be taken. This is the most complex of all action section keywords and will be dealt with in excruciating detail later, for now, here's a list of possible actions and a short definition of each:

Sample Action Entries

The following list of action entries is provided to show the basic syntax of each of the actions.

    Action=Load,ViewFile.v
    Action=Popup,ViewFile.v
    Action=ClosePopup
    Action=ZoomTo,RectangleObjectName
    Action=UnZoom
    Action=CenterOn,ObjectName
    Action=UnCenter
    Action=SetVar,VarName,Value
    Action=IncVar,VarName
    Action=DecVar,VarName
    Action=MapVar,DVName,PICSName
    Action=Zoom,In
    Action=Zoom,Out
    Action=Pan,Left
    Action=Pan,Up
    Action=Pan,Right
    Action=Pan,Down
    Action=Reset
    Action=Refresh
    Action=ExitApp
    Action=ToFront
    Action=ToBack
    Action=Center

Button

The button keyword is used to specify which mouse button (optionally combined with shift-keys) will trigger this event. The mouse button is specified first, using one of the following names: Left, Middle, or Right. If any modifier keys are required, they should be listed using commas (or plus signs) to separate them using the following names: Alt, Control, and Shift. Modifiers may be combined, but button names may not. For example, to define Control+Shift+Left Button as a trigger, this entry would be included in the action section:

Button=Left+Ctrl+Shift

Key

The key keyword is used to specify which function key (optionally combined with shift-keys) will trigger this event. The key name is specified first, followed by any modifier key names, if necessary. If any modifier keys are required, they should be listed using plus signs (or commas) to separate them using the following names: Alt, Control, and Shift. Modifiers may be combined, but key names may not. For example, to define Shift+Alt+F8 as a trigger, this entry would be included in the action section

Key=F8+Alt+Shift

Name

To make it easier for one action to refer to another, you may give each action a name. These names should be unique (if not, then PicsViews will use the first match it encounters). When searching for an action by name, the other triggers (mouse buttons and/or keys) are ignored.

OnFailure

If an action fails for some reason (e.g. a view to be loaded cannot be found) then this item defines how PicsViews will respond to that failure. You may specify any of the following:

Trigger (not implemented in version 1.0)

Define a data trigger for this action. A data trigger monitors the value of a variable and triggers an action when the variable crosses some threshold or enters a particular state. When implemented, it is planned that triggers may include more than one variable and/or condition, with the additional possibility of having the ability to define different actions for different regions (or results) of trigger testing.

Menu

Specifies text to display on the action menu in PicsViews. If this keyword is missing, then no entry is made on the menu. PicsViews, in theory, supports as many menu items as actions, however in practice, Windows supports a much more limited number. Currently, PicsViews 1.0 stores but otherwise ignores this setting. Menu management will be added at a later date.

Glossary